Installation¶

Architecture Overview¶

Hamr consists of several components that work together:

hamr-daemon: Core service that manages plugins and search
hamr-gtk: GTK4 launcher UI (what you see when you press the hotkey)
hamr: Unified CLI and default entrypoint (starts GTK; auto-starts daemon)
hamr-tui: Terminal UI for headless environments

The daemon runs continuously and communicates with the UI clients via JSON-RPC.

Requirements¶

GTK4 4.20+ and gtk4-layer-shell (for the GTK4 interface)
A supported Wayland compositor: Hyprland or Niri
Python 3.9+ (for plugins)
Rust 1.88+ (for building from source)

Compositor Support Matrix¶

Compositor	Status	Notes
Hyprland	✅ Supported	Full functionality with layer-shell
Niri	✅ Supported	Full functionality with layer-shell
Sway	✅ Supported	Works with layer-shell protocol
KDE Wayland	✅ Supported	Requires layer-shell support
GNOME Wayland	❌ Not Supported	No layer-shell protocol support
X11	❌ Not Supported	Wayland-only application

Arch Linux (AUR)¶

# Pre-built binary (recommended - faster install)
paru -S hamr-bin

# Or build from source
paru -S hamr

After installing:

# Option 1: Run directly (no systemd)
hamr

# Option 2 (recommended, opt-in): systemd user services
hamr install
systemctl --user start hamr-gtk

Note: AUR packages do not auto-enable systemd services; hamr install is the opt-in step.

Manual Download¶

Download pre-built binaries directly from GitHub:

# Download latest release
wget https://github.com/Stewart86/hamr/releases/latest/download/hamr-linux-x86_64.tar.gz

# Extract
tar -xzf hamr-linux-x86_64.tar.gz
cd hamr-linux-x86_64

# Install binaries
mkdir -p ~/.local/bin
cp hamr hamr-daemon hamr-gtk hamr-tui ~/.local/bin/
cp -r plugins ~/.local/bin/

# Run directly (no systemd)
~/.local/bin/hamr

# Or (recommended, opt-in): set up systemd user services
~/.local/bin/hamr install
systemctl --user start hamr-gtk

NixOS / Nix¶

Quick install¶

# Try without installing (recommended)
nix run github:Stewart86/hamr --no-write-lock-file -- --help

# Install to your profile
nix profile install github:Stewart86/hamr

NixOS / Home Manager¶

Add the flake input to your configuration:

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    hamr.url = "github:Stewart86/hamr";
  };

  outputs = { self, nixpkgs, hamr, ... }: {
    # NixOS
    nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux"; # or your system
      modules = [{
        environment.systemPackages = [ hamr.packages.x86_64-linux.default ];
      }];
    };

    # Or Home Manager
    homeConfigurations.myuser = home-manager.lib.homeManagerConfiguration {
      pkgs = nixpkgs.legacyPackages.x86_64-linux;
      modules = [{
        home.packages = [ hamr.packages.x86_64-linux.default ];
      }];
    };
  };
}

Note: The Nix build uses separate derivations for binaries and plugins, preventing Rust toolchain stripping issues with Python plugin files.

Quick Install (All Distributions)¶

curl -fsSL https://hamr.run/install.sh | bash

# Or opt-in to systemd setup during install
curl -fsSL https://hamr.run/install.sh | bash -s -- --systemd

The install script will:

Download the latest release binaries
Install to ~/.local/bin/
Copy bundled plugins next to the binaries (~/.local/bin/plugins/)
Optionally run hamr install to set up systemd user services (opt-in)

Installer Flags:

Flag	Description
`--check`	Dry-run mode: show what would be installed without making changes
`--yes`	Assume yes for all prompts (non-interactive mode)
`--reset-user-data`	Reset user configuration and plugins (backup created)
`--systemd`	Run `hamr install` after installing binaries (opt-in)

Manual Dependencies¶

Arch Linux:

sudo pacman -S gtk4 gtk4-layer-shell python

Fedora:

sudo dnf install gtk4-devel gtk4-layer-shell-devel python3

Ubuntu/Debian:

sudo apt install libgtk-4-dev gtk4-layer-shell-dev python3

Layer-shell Package Names by Distribution¶

Distribution	Package Name
Arch Linux	`gtk4-layer-shell`
Fedora	`gtk4-layer-shell-devel`
Ubuntu/Debian	`gtk4-layer-shell-dev`
openSUSE	`gtk4-layer-shell-devel`
Gentoo	`gui-libs/gtk4-layer-shell`

Post-Installation Setup¶

You can run Hamr immediately (no systemd required):

hamr

To install and enable systemd user services (recommended, opt-in), run:

hamr install --check  # Preview what will be set up
hamr install          # Set up systemd services and directories
systemctl --user start hamr-gtk

This creates:

Systemd user services (hamr-daemon.service, hamr-gtk.service)
Config directory (~/.config/hamr/)
Essential plugins copied to user config

Then start the launcher:

# Option 1: Via systemd (recommended for auto-start on login)
systemctl --user start hamr-gtk

# Option 2: Direct (works without systemd)
hamr

Without systemd: Running hamr will auto-start the daemon as a background process. No additional setup needed.

For full CLI documentation, see CLI Reference.

Keybinding¶

Bind hamr toggle to a key in your compositor config.

Hyprland¶

exec-once = hamr
bind = $mainMod, SPACE, exec, hamr toggle
bind = $mainMod, V, exec, hamr plugin clipboard

Niri¶

// ~/.config/niri/config.kdl
spawn-at-startup "hamr"

binds {
    Mod+Space { spawn "hamr" "toggle"; }
    Mod+V { spawn "hamr" "plugin" "clipboard"; }
}

Verify Installation¶

Check if Hamr daemon is running:

hamr status

View logs:

# Daemon logs (debug builds write to /tmp/hamr-daemon.log)
tail -f /tmp/hamr-daemon.log

# Or if using systemd
journalctl --user -u hamr-daemon -f

For detailed logging configuration, including RUST_LOG and HAMR_PLUGIN_DEBUG environment variables, see the Logging Guide.

If you encounter issues, see the Troubleshooting Guide for common problems and solutions.

Updating¶

Arch Linux (AUR):

paru -Syu hamr
# or
paru -Syu hamr-bin

Other distributions:

# Re-run the installer to update
curl -fsSL https://hamr.run/install.sh | bash

Uninstall¶

The recommended way to uninstall depends on how you installed Hamr.

Using the CLI (recommended)¶

hamr uninstall          # Remove binaries, services, socket (preserves config)
hamr uninstall --purge  # Remove everything including ~/.config/hamr

This will:

Stop and disable systemd user services
Remove service files
Remove binaries (hamr, hamr-daemon, hamr-gtk, hamr-tui)
Remove system plugins next to binaries
Remove socket files
Clean PATH entries from shell rc files
Preserve user config by default (use --purge to remove)

Using the uninstall script¶

If the hamr binary is already removed or broken:

curl -fsSL https://hamr.run/uninstall.sh | bash

# Or remove everything including config
curl -fsSL https://hamr.run/uninstall.sh | bash -s -- --purge

# Non-interactive mode
curl -fsSL https://hamr.run/uninstall.sh | bash -s -- --yes

Arch Linux (AUR)¶

hamr uninstall          # Remove systemd services first
paru -R hamr            # or hamr-bin

NixOS / Nix¶

nix profile remove hamr

Or remove the flake input from your NixOS/Home Manager configuration.