Skip to content
These pages describe the newest preview build. For the current release, read the stable documentation.

Install Herdsman

Herdsman publishes release binaries for Linux, macOS, and Windows. Windows has platform-specific limitations; see Windows support.

On Linux or macOS, run:

Terminal window
curl -fsSL https://remziduzagac.github.io/herdsman/install.sh | sh

On Windows, run:

Terminal window
powershell -ExecutionPolicy Bypass -c "irm https://remziduzagac.github.io/herdsman/install.ps1 | iex"

If endpoint security blocks that fileless PowerShell command, open Command Prompt and run:

Terminal window
curl.exe -fsSLo install.cmd https://remziduzagac.github.io/herdsman/install.cmd && install.cmd && del install.cmd

The installer downloads the release binary for your platform, checks its checksum, and places it on your PATH. On Windows, PATH points to the active versioned release directory; the installer also updates the current and stable bin compatibility aliases, so updates do not need to overwrite a running herdsman.exe.

If you already use Homebrew, on macOS or Linux, install from herdsman’s tap:

Terminal window
brew install remziduzagac/tap/herdsman

Update it with brew upgrade herdsman.

If you already use mise, install the release binary straight from GitHub:

Terminal window
mise use -g github:remziduzagac/herdsman

mise holds back releases younger than a day, so a new release shows up in mise the day after it is published. To take one right away, ask for its version, such as mise use -g github:remziduzagac/herdsman@1.0.0.

herdsman runs its own signed package repositories for Debian and Ubuntu, Fedora and RHEL, and Arch Linux, on x86_64 and aarch64. Add the repository once; after that, herdsman updates with the rest of your system.

The repositories are signed with this key:

971C 0D3C 67E6 6F3C 70BC CBF9 7E19 E781 6ABF 24EF
herdsman packages <2682213+remziduzagac@users.noreply.github.com>

On Debian and Ubuntu:

Terminal window
sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://remziduzagac.github.io/herdsman/herdsman.asc | sudo tee /etc/apt/keyrings/herdsman.asc > /dev/null
echo "deb [signed-by=/etc/apt/keyrings/herdsman.asc] https://remziduzagac.github.io/herdsman/apt stable main" \
| sudo tee /etc/apt/sources.list.d/herdsman.list
sudo apt update && sudo apt install herdsman

On Fedora and RHEL:

Terminal window
sudo curl -fsSLo /etc/yum.repos.d/herdsman.repo https://remziduzagac.github.io/herdsman/rpm/herdsman.repo
sudo dnf install herdsman

dnf asks you to confirm the key on first install; compare it with the fingerprint above.

On Arch Linux:

Terminal window
curl -fsSL https://remziduzagac.github.io/herdsman/herdsman.asc | sudo pacman-key --add -
sudo pacman-key --lsign-key 971C0D3C67E66F3C70BCCBF97E19E7816ABF24EF
printf '\n[herdsman]\nServer = https://remziduzagac.github.io/herdsman/arch/$arch\n' | sudo tee -a /etc/pacman.conf
sudo pacman -Sy herdsman

Update with sudo apt upgrade, sudo dnf upgrade or sudo pacman -Syu. The packages install herdsman to /usr/bin, so herdsman update leaves them to your package manager.

If you already use Nix, Herdsman provides a flake that builds Herdsman from source:

Terminal window
nix run github:remziduzagac/herdsman/v0.x.y
nix build github:remziduzagac/herdsman/v0.x.y
nix profile install github:remziduzagac/herdsman/v0.x.y

Replace v0.x.y with the latest release tag. You can omit the tag to track main, but release tags are recommended for normal installs.

The flake also exposes a development shell:

Terminal window
nix develop github:remziduzagac/herdsman

Use the same Nix workflow to update Herdsman. For a profile install, list your profile entries and upgrade the Herdsman entry:

Terminal window
nix profile list
nix profile upgrade <index-or-name>

If Herdsman is an input in your own flake, update that input and rebuild your system, Home Manager, or development environment:

Terminal window
nix flake update herdsman

You can also download a binary from GitHub releases.

Choose the asset that matches your system:

System Asset
Linux x86_64 herdsman-linux-x86_64
Linux aarch64 herdsman-linux-aarch64
macOS Intel herdsman-macos-x86_64
macOS Apple silicon herdsman-macos-aarch64
Windows x86_64 herdsman-windows-x86_64.zip

On Linux or macOS, make it executable and move it somewhere on your PATH.

Terminal window
chmod +x herdsman-linux-x86_64
mv herdsman-linux-x86_64 ~/.local/bin/herdsman

Every release includes herdsman-windows-x86_64.zip. The archive contains herdsman.exe and its app-local ConPTY runtime. Keep the extracted directory together; do not copy only herdsman.exe.

Start Herdsman:

Terminal window
herdsman

If your shell cannot find herdsman, restart the terminal or check that the install directory is on your PATH.

Herdsman checks for new releases and notifies you in the app. You can update manually:

Terminal window
herdsman update

Use herdsman update only for installs managed by Herdsman’s own installer. Update Homebrew, mise, Nix, apt, dnf and pacman installs through those package managers instead.

By default, herdsman update installs the new binary and leaves endpoint-generation-1 servers and their pane processes running. Start Herdsman again to reconnect with the updated client. Client-only changes work immediately. A new server-side action stays unavailable until that server is updated and restarted; the client shows a notice instead of disconnecting. Servers from before endpoint generation 1 need one final stop during update.

When it finishes, herdsman update lists any running server still on the old version with the command that restarts it, and your saved SSH machines, which run their own Herdsman. Run herdsman update on each machine to update it too.

To opt into experimental live server handoff for supported running sessions, run:

Terminal window
herdsman update --handoff

When both servers support agent-status transfer, live handoff preserves hook-reported agent status until the next report arrives. Handoff from an older server can temporarily show a running agent as idle.

Live handoff does not apply to Homebrew, mise, or Nix package-manager updates. For those installs, update with the package manager, then run Herdsman again to reconnect with the updated client. The compatible old server keeps running. Restart it later with herdsman server stop or herdsman session stop <name> only when you want server-side changes from the new release.

herdsman can also update and hand off from the app, or on its own at a quiet moment: see Update without restarting.

Every push to herdsman’s test branch publishes a preview build, ahead of the next release. Previews get less testing than releases and can break. The newest preview has its own documentation.

Previews need an install made with the install script or a manual download. Homebrew, mise, Nix, apt, dnf and pacman installs receive releases only, and herdsman channel set preview refuses to switch them.

On such an install, run:

Terminal window
herdsman channel set preview

This switches the channel and updates to the newest preview straight away. Switch back with herdsman channel set stable.

To move a package-manager install to previews, remove it with its package manager first, for example brew uninstall herdsman, so that only one herdsman is on your PATH. Then install with the script and switch the channel. Your configuration and sessions in ~/.config/herdsman stay as they are.

Release binaries are available for Linux and macOS on x86_64 and aarch64, and for Windows x86_64. See Windows support for supported workflows and known limitations. Windows ARM64 runs the x86_64 build under Windows emulation.