Install a Herden Host

A Host is the computer that runs your coding agents. Run these commands on that computer as the user who will run Claude Code or Codex.

1. Enable SSH

On Ubuntu or Debian:

sudo apt update
sudo apt install openssh-server
sudo systemctl enable --now ssh

On macOS, open System Settings → General → Sharing → Remote Login. Enable it for your user account and keep the Host awake for remote access.

Herden needs public-key authentication, PTY sessions, and OpenSSH stream-local forwarding. Standard OpenSSH defaults allow them. Herden does not alter SSH or firewall configuration.

2. Connect with Tailscale

Install Tailscale on the Host and sign in.
Install Tailscale on the iPhone, join the same tailnet, and connect.
Keep ordinary OpenSSH on port 22. Do not enable Tailscale SSH; Herden pairs its own SSH key and needs Unix-socket forwarding.

The phone must be able to reach the Host on TCP port 22. No router port forwarding is needed.

3. Install Herden

curl -fsSL https://herden.app/install.sh | sh

The installer selects the binary for your OS and architecture, verifies its SHA-256 checksum, installs it to ~/.local/bin, and adds that directory to common shell startup files. It also installs the release licence and attribution notice. Running the same command again safely verifies or upgrades an existing installation.

When a directory you own is already on your PATH, such as Homebrew's on a Mac, the installer links herden there and it works in this Terminal straight away. Otherwise it ends with the one command that makes it available here; new Terminals already find it.

4. Start and pair

Install and sign in to Claude Code or Codex on the Host. Complete their first-run login and directory-trust prompts there, then start Herden:

herden

In an ordinary shell tab inside that session, run:

herden pair

Leave the QR code visible. On the iPhone, open Herden → Hosts → Add Host, choose the scanner, and scan it. Each code expires after two minutes and enrols one phone.

Troubleshooting

Symptom	Next step
`herden: command not found`	Run `export PATH="$HOME/.local/bin:$PATH"` or open a new Terminal.
Expired QR code	Run `herden pair` again and keep its Terminal open.
Host unreachable	Check Tailscale on both devices, the Host address, firewall, and access policy.
Permission denied	Pair as the user running Herden. Check Remote Login and confirm Tailscale SSH is not intercepting port 22.
Stream-local forwarding denied	Enable `AllowStreamLocalForwarding yes` and ensure `DisableForwarding` is not enabled for the user.
Agent waits on first launch	Finish its login or directory-trust dialogue on the Host.

For a custom SSH port, add --port 2222 to the pairing command, using the port configured on your Host. Reconnection cannot wake a sleeping computer.