How to Install herdr on Debian: A Terminal Workspace Manager for AI Coding Agents

herdr is an agent multiplexer that lives in your terminal, a workspace manager built for running and orchestrating several AI coding agents side by side. Written in Rust and shipped as a single static binary, it gives tools like Claude Code, Codex, Gemini and Aider a proper home: persistent sessions, panes and tabs, per-agent git worktrees, and remote access over SSH, all driven from one keyboard-friendly TUI.

herdr moves quickly and is not part of the official Debian archive. Installing it usually means a shell installer or a hand-downloaded binary, after which you own the update problem yourself.

The unofficial deb.griffo.io repository removes that friction: it packages herdr as a standard Debian .deb served over APT, so installation and updates use the tooling you already run for the rest of your system.

Install the Latest herdr on Debian: The Short Version

If you only came for the commands, this adds the repository and installs the latest herdr .deb package on Debian:

sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://deb.griffo.io/EA0F721D231FDD3A0A17B9AC7808B4DD62C41256.asc | sudo gpg --dearmor --yes -o /etc/apt/keyrings/deb.griffo.io.gpg
echo "deb [signed-by=/etc/apt/keyrings/deb.griffo.io.gpg] https://deb.griffo.io/apt $(lsb_release -sc 2>/dev/null) main" | sudo tee /etc/apt/sources.list.d/deb.griffo.io.list > /dev/null
sudo apt update
sudo apt install herdr

The rest of this guide explains what each command does, how to verify the install, how to keep herdr up to date, and what to check when something goes wrong.

What Makes herdr Special?

  • 🤖 Many agents at once - Run and orchestrate multiple AI coding agents, each in its own pane, tab and workspace.
  • 🗂️ Workspaces and sessions - Named, persistent sessions keep running in the background and reattach instantly.
  • 🌿 Git worktree aware - Give each agent its own worktree and branch so parallel work never collides.
  • 🖥️ Remote over SSH - Attach to a herdr server running on any machine and drive it as if it were local.
  • ⌨️ Keyboard-driven TUI - A fast, mouse-optional interface with configurable keybindings, tabs and panes.
  • 🔌 Integrations and a socket API - Built-in agent integrations plus a scriptable API and a growing plugin ecosystem.
  • 📡 Stable and preview channels - Track the steady release line or opt into preview builds.
  • 📦 Single static binary - A self-contained Rust build with no runtime dependencies.

Why Use the deb.griffo.io Repository?

  • Easy installation and updates through APT, no curl-to-shell installer.
  • Automatic dependency management handled by Debian packaging.
  • Always tracks upstream releases so you stay close to the latest herdr.
  • No compiling from source and no Rust toolchain to maintain.
  • Works across supported Debian releases, with the codename detected automatically.

Prerequisites

Before you start, make sure you have:

  • A Debian-based system (Bookworm 12, Trixie 13, Forky, or Sid)
  • sudo privileges
  • curl installed (sudo apt install curl if needed)

herdr drives AI coding agents but does not bundle them; install whichever agent CLIs you use (for example Claude Code) separately.

Step 1: Add the deb.griffo.io Repository

Add the signing key and repository source:

# Create the keyrings directory
sudo install -d -m 0755 /etc/apt/keyrings

# Download and install the repository GPG key
curl -fsSL https://deb.griffo.io/EA0F721D231FDD3A0A17B9AC7808B4DD62C41256.asc | sudo gpg --dearmor --yes -o /etc/apt/keyrings/deb.griffo.io.gpg

# Add the repository (auto-detects your distro codename)
echo "deb [signed-by=/etc/apt/keyrings/deb.griffo.io.gpg] https://deb.griffo.io/apt $(lsb_release -sc 2>/dev/null) main" | sudo tee /etc/apt/sources.list.d/deb.griffo.io.list > /dev/null

# Update the package list
sudo apt update

What each command does:

  1. Create the keyrings directory - ensures /etc/apt/keyrings exists with proper permissions.
  2. Install the GPG key - downloads the repository key and de-armours it into a dedicated keyring for verification.
  3. Add the repository - writes a signed-by source line, with lsb_release -sc supplying your Debian codename.
  4. Update the package list - refreshes APT so it knows about the new packages.

Step 2: Update the Package List

If you skipped the last line, run the update now:

sudo apt update

Step 3: Install herdr

Install herdr with APT:

sudo apt install herdr

APT downloads herdr and installs it system-wide.

Step 4: Verify the Installation

The binary is simply herdr. Confirm the version:

herdr --version

You should see output similar to:

herdr 0.7.5

Explore everything it offers with herdr --help.

Getting Started with herdr

Launching and Attaching to a Session

Running herdr on its own starts a persistent session (or reattaches to the one already running):

# Launch or attach to the persistent session
herdr

# Use or create a named session
herdr --session work

# Attach to a named session later
herdr session attach work

Because herdr uses a server/client model, your workspaces keep running in the background even after you close the terminal, ready to reattach.

Driving Remote Servers over SSH

Point herdr at a remote machine and it attaches through SSH to a herdr server there:

# Attach to a remote herdr server
herdr --remote user@server

# Open a named session on a remote host
herdr --remote user@server --session build

This makes a beefy build box or cloud VM feel like a local workspace.

Workspaces, Worktrees and Agents

herdr exposes helpers over its socket API for scripting and inspection:

# List workspaces, git worktrees and running agents
herdr workspace list
herdr worktree list
herdr agent list

# Show local client and running server status
herdr status

Give each agent its own git worktree and it works on an isolated branch, keeping diffs clean and reviewable.

Channels, Config and Completions

# Choose the stable or preview update channel
herdr channel set stable

# Generate shell completions for your shell
herdr completion zsh

# Print the default configuration to start a config.toml
herdr --default-config

herdr keeps its configuration at ~/.config/herdr/config.toml, so you can version your keybindings and settings.

Keeping herdr Updated

Because herdr arrived via APT, updates come with the rest of the system:

sudo apt update && sudo apt upgrade

Whenever deb.griffo.io ships a newer herdr, apt upgrade installs it automatically. When herdr comes from APT, let the package manager handle upgrades rather than the built-in herdr update.

Other Tools from deb.griffo.io

The repository packages plenty of tools that fit naturally alongside herdr:

  • Zellij - a terminal workspace and multiplexer for everyday shells.
  • Ghostty - a fast, GPU-accelerated terminal emulator.
  • Neovim - the hyperextensible Vim-based text editor.
  • lazygit - a simple terminal UI for git commands.

Troubleshooting

GPG or Key Errors

If APT reports an unsigned repository or an invalid key, import it again:

curl -fsSL https://deb.griffo.io/EA0F721D231FDD3A0A17B9AC7808B4DD62C41256.asc | sudo gpg --dearmor --yes -o /etc/apt/keyrings/deb.griffo.io.gpg
sudo apt update

Package Not Found

If APT cannot see the herdr package:

  1. Re-run sudo apt update after adding the repository.
  2. Confirm your release is supported (Bookworm, Trixie, Forky, or Sid).
  3. Inspect the source list: cat /etc/apt/sources.list.d/deb.griffo.io.list.

Conflicting herdr Installations

If you previously installed herdr with its own installer, an older copy in ~/.local/bin may take precedence:

which -a herdr

Remove the stray binary, or let the APT-managed herdr in /usr/bin win by adjusting your PATH. Since the packaged herdr is updated through APT, the built-in herdr update is unnecessary here.

Uninstalling

Remove herdr with:

sudo apt remove herdr

To also drop the repository and key:

sudo rm /etc/apt/sources.list.d/deb.griffo.io.list
sudo rm /etc/apt/keyrings/deb.griffo.io.gpg
sudo apt update

Conclusion

Installing herdr from deb.griffo.io gives Debian users a fast way to run a whole fleet of AI coding agents from one terminal, without a bespoke installer or manual updates. Persistent sessions, per-agent git worktrees and remote access all live behind one command, and keeping it current is just another apt upgrade.

Whether you juggle several agents at once, want your sessions to survive a dropped connection, or simply prefer a keyboard-driven workflow, herdr is a natural fit, and APT makes it painless to maintain.

Frequently Asked Questions

How do I install the latest herdr on Debian?

Add the deb.griffo.io APT repository and its signing key, then run sudo apt install herdr. The repository tracks upstream herdr releases, so you get the latest packaged version rather than a build frozen when your distribution was released.

Is there a .deb package for herdr?

Yes. deb.griffo.io publishes herdr as a signed .deb for Debian. You could download that .deb and install it by hand, but adding the repository is the better option: APT then resolves dependencies and picks up new versions on its own.

How do I update herdr to the latest version?

Run sudo apt update && sudo apt upgrade. Once herdr is installed from APT there is no separate updater to remember, since new releases arrive with the rest of your system updates.

How do I install herdr on Ubuntu?

Exactly the same way; lsb_release -sc simply resolves to a different codename. There is a companion guide with the Ubuntu specifics: How to install herdr on Ubuntu.

Which Debian releases are supported?

Bookworm 12, Trixie 13, Forky and Sid. Because the repository line is built from lsb_release -sc, the matching suite is selected for you.

Resources

Disclaimer: The deb.griffo.io repository is an unofficial community project and is not affiliated with the official Debian or Ubuntu projects, or with the upstream herdr project.