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¶

You do not need to uninstall Hamr to move between releases. Update it in place using the same method you used to install it.

By default, updates:

Replace the Hamr binaries with the newer release
Update bundled built-in plugins
Preserve ~/.config/hamr/ and user-created plugins

Use --reset-user-data only if you want a clean reset of your user configuration and plugins.

After upgrading, restart Hamr so the new binaries are running:

hamr restart

If you are not using systemd, hamr restart restarts the daemon. Start the GTK UI again with hamr if needed.

Arch Linux (AUR)¶

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

# Restart the running instance after the package update
hamr restart

Quick Install Script Or Manual Download¶

Re-run the installer to update your existing install in place:

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

# Optional: install a specific release instead of latest
HAMR_VERSION=vX.Y.Z curl -fsSL https://hamr.run/install.sh | bash

# Restart the running instance after the update
hamr restart

If you originally used --systemd, you can pass it again during the update, but it is not required for existing systemd users.

Build From Source¶

If you installed from a local clone, pull the new version and re-run the install step you used originally:

git pull

# If you use the repo installer
./install.sh

# Or rebuild manually
cargo build --release
cp target/release/{hamr,hamr-daemon,hamr-gtk,hamr-tui} ~/.local/bin/
hamr restart

NixOS / Nix¶

For profile installs, upgrade the flake reference:

nix profile upgrade github:stewart86/hamr

For NixOS or Home Manager setups, update the hamr flake input and rebuild your system or home configuration.

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.