SOP: Remote Attach Setup

Fresh

Wire up herdr --remote so a local terminal acts as a thin client for a Herdr server running on a remote host.

Prerequisites

SSH access to the remote host (Linux or macOS, x86_64 or aarch64)
Herdr installed locally
Native Windows herdr --remote is NOT supported; from Windows, SSH into the server and run herdr there

Procedure

Add the host to your SSH config for repeat targets:

Host workbox
  HostName server.example.com
  User you
  Port 2222

Attach:

herdr --remote workbox

You can also attach ad hoc without SSH config:

herdr --remote ssh://you@server:2222

On first attach, Herdr checks the remote platform and prefers a matching herdr already on the remote PATH, then checks ~/.local/bin/herdr. If no matching binary exists, interactive runs prompt to install one to ~/.local/bin/herdr. Non-interactive runs fail instead of modifying the host.
If ~/.local/bin is not on the remote PATH, Herdr warns after install. Fix the remote PATH if needed.
Detach with ctrl+b q. The remote server and its agents keep running.

Options worth knowing

Option	Effect
`--session agents`	Attach to a named session on the remote host
`--remote-keybindings server`	Use the remote server's keybindings instead of your local snapshot
`--handoff`	Experimental live handoff when replacing a running remote server
`HERDR_REMOTE_BINARY=path`	Push a local/custom binary instead of downloading a release

By default, herdr --remote uses your local keybindings (snapshot from attach time). Local custom command keybindings are not sent because those commands would run on the remote host.

SSH bridge behavior

By default, Herdr runs the bridge through a temporary SSH config that includes your SSH config first, then adds fallback keepalive settings (ServerAliveInterval, ServerAliveCountMax). Your own keepalive settings win. To use plain ssh with no generated config:

[remote]
manage_ssh_config = false

Choosing the right remote path

Situation	Use
You already live in an SSH shell, or you are on a phone SSH client	`ssh you@server` then `herdr`
You want the remote session to feel local, with local clipboard image paste bridged	`herdr --remote <host>`
You are on Windows	`ssh you@server` then `herdr`

Verification checklist

[ ] herdr --remote <host> opens the remote session UI locally
[ ] Detach (ctrl+b q), reconnect, panes still running
[ ] Named session attach works: herdr --remote <host> --session <name>

SOP: Remote Attach Setup ​

Prerequisites ​

Procedure ​

Options worth knowing ​

SSH bridge behavior ​

Choosing the right remote path ​