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

herdr describes itself as an agent multiplexer that lives in your terminal. In practice it is a workspace manager for AI coding agents: a place to launch, arrange and keep tabs on several agents at the same time, each in its own pane and workspace, with persistent sessions, git worktrees and SSH-backed remote access. It is written in Rust and distributed as one self-contained binary.

herdr is evolving fast and is not carried in the Ubuntu archive. The common install routes are a piped shell script or a manually fetched binary, both of which put you in charge of every future update.

The unofficial deb.griffo.io repository offers a cleaner path: herdr packaged as a proper Ubuntu .deb and delivered over APT, so you install it and keep it current with the same commands you already use.

Install the Latest herdr on Ubuntu: The Short Version

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

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 - Orchestrate multiple AI coding agents together, each isolated in its own pane and tab.
  • 🗂️ Workspaces and sessions - Persistent, named sessions stay alive in the background and reattach on demand.
  • 🌿 Git worktree aware - Each agent can run on its own worktree and branch, so parallel work never steps on itself.
  • 🖥️ Remote over SSH - Connect to a herdr server on another host and work with it as though it were local.
  • ⌨️ Keyboard-driven TUI - A quick, mouse-optional terminal UI with configurable keybindings, tabs and panes.
  • 🔌 Integrations and a socket API - Built-in agent integrations, a scriptable API, and a growing set of plugins.
  • 📡 Stable and preview channels - Stay on the stable line or opt into preview releases.
  • 📦 Single static binary - No runtime dependencies to install or manage.

Why Use the deb.griffo.io Repository?

  • Easy installation and updates through APT rather than a shell installer.
  • Automatic dependency management provided by the Ubuntu packaging.
  • Always tracks upstream releases so you stay near the latest herdr.
  • No compiling from source and no Rust toolchain to look after.
  • Works across supported Ubuntu releases, with the codename detected for you.

Prerequisites

Before starting, confirm you have:

  • An Ubuntu system (Jammy 22.04 LTS, Noble 24.04 LTS, or newer)
  • sudo privileges
  • curl installed (sudo apt install curl if needed)

herdr orchestrates AI coding agents but does not ship them; install the agent CLIs you plan to use (such as Claude Code) on their own.

Step 1: Add the deb.griffo.io Repository

Register the 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

Breaking it down:

  1. Create the keyrings directory - makes sure /etc/apt/keyrings exists with the right permissions.
  2. Install the GPG key - downloads and de-armours the repository key into its own keyring so APT can verify signatures.
  3. Add the repository - writes a signed-by source line, letting lsb_release -sc fill in your Ubuntu codename.
  4. Update the package list - refreshes APT’s view of available packages.

Step 2: Update the Package List

If you did not run the final command above, do it now:

sudo apt update

Step 3: Install herdr

Install with APT:

sudo apt install herdr

APT fetches herdr and installs it across the system.

Step 4: Verify the Installation

The binary is herdr. Check the version:

herdr --version

You should see something like:

herdr 0.7.5

Run herdr --help for the complete command listing.

Getting Started with herdr

Your First Session

Launched on its own, herdr opens a persistent session, or reattaches to the one already running in the background:

# Launch or attach to the persistent session
herdr

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

# Reattach to a named session later
herdr session attach work

The server/client design means your workspaces survive a closed terminal or a dropped SSH connection and are waiting when you return.

Working with Remote Hosts

Give herdr an SSH target and it attaches to a herdr server on that machine:

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

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

A remote build server or cloud VM then behaves like part of your local setup.

Inspecting Workspaces, Worktrees and Agents

herdr offers scriptable helpers over its socket API:

# 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

Pairing each agent with its own git worktree keeps their branches, and their diffs, cleanly separated.

Channels, Config and Completions

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

# Generate shell completions for your shell
herdr completion bash

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

Configuration lives at ~/.config/herdr/config.toml, which makes your keybindings and settings easy to track in version control.

Keeping herdr Updated

herdr rides along with your normal Ubuntu upgrades:

sudo apt update && sudo apt upgrade

When a newer herdr appears in deb.griffo.io, apt upgrade installs it alongside your other packages. Since it is managed by APT, prefer apt over the built-in herdr update for upgrades.

Other Tools from deb.griffo.io

The repository includes many tools that sit well next to herdr:

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

Troubleshooting

GPG or Key Errors

If APT flags the repository as unsigned or the key as invalid, re-import it:

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 locate herdr:

  1. Re-run sudo apt update after adding the repository.
  2. Verify your Ubuntu release is supported (Jammy, Noble, or newer).
  3. Check the source list: cat /etc/apt/sources.list.d/deb.griffo.io.list.

A Previous herdr Installer Shadows the Package

If you installed herdr earlier with the standalone installer, an older binary in ~/.local/bin can override the packaged one:

which -a herdr

Delete the stray binary or reorder your PATH so /usr/bin/herdr wins. When herdr comes from APT, manage upgrades with apt rather than herdr update.

Uninstalling

Remove herdr with:

sudo apt remove herdr

To also remove 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

On Ubuntu, deb.griffo.io turns herdr into a first-class APT package: no installer script, no manual updates, just a fast way to run and orchestrate a fleet of AI coding agents from a single terminal. Persistent sessions, per-agent git worktrees and remote SSH access all sit behind one command, maintained with apt upgrade.

If you routinely run several agents at once, want your sessions to outlast a dropped connection, or simply prefer a keyboard-driven workflow, herdr is an excellent fit, and installing it this way keeps it effortless to keep current.

Frequently Asked Questions

How do I install the latest herdr on Ubuntu?

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 Ubuntu. 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 Debian?

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

Which Ubuntu releases are supported?

Jammy 22.04 LTS, Noble 24.04 LTS and newer. 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.