Connecting machines

Preview build 2026-09-29-8e78f929d8f0, published from 8e78f929d8f0. Stable docs remain at /docs/.

Keep your local work and remote agents in one Herdr window. Save an SSH machine once, then switch between its workspaces and Local without opening another client. The agent list includes connected machines, so you can see where work is running and which agent needs an answer.

Each machine keeps its own Herdr server, sessions, and running processes. A lost connection to one machine does not disconnect the others.

Herdr requests SSH compression to reduce screen-update traffic on limited connections. This works with older compatible Herdr servers and does not change how typing or other input is delivered. Herdr’s -C option overrides Compression no in your SSH config. If SSH reuses an existing connection through an external ControlMaster, that connection keeps its original compression setting.

Recovering SSH authentication

On Linux and macOS clients, when remote.manage_ssh_config=true, Herdr shares an approved OpenSSH connection across machine add, the sidebar, and saved-machine API commands. Run herdr machine status [<label-or-id>] [--json] for fresh, noninteractive checks. Reachable means the remote Herdr server is available now, not that every open TUI is connected. Run herdr machine reconnect <label-or-id> in a terminal to complete native SSH authentication and verify the saved machine. It does not install or update Herdr. Open clients recheck failed connections within 30 seconds; no restart is needed. Clicking ! auth, ! error, or a failed connection’s reconnecting status shows a notice with its latest error and the relevant CLI command. It never opens a credential popup. The rest of the machine row keeps its normal expand/collapse behavior.

The shared connection uses ControlPersist 600 (10 minutes of idle time); this is not MFA validity. Active connections can remain open, while corporate policy, the SSH server, or the network may end them sooner. Local Windows recovery is not supported yet. For unmanaged SSH connections, authentication remains your responsibility: running ssh by itself does not grant Herdr approval unless it uses the shared ControlPath. Host-key checking is unchanged; an unknown or changed host key remains Attention.

Before you connect

You need normal SSH access to the remote machine. Verify it first:

ssh workbox

workbox can be a host from your SSH config. You can also use a target such as ssh://you@server:2222.

Multi-machine connections support Linux, macOS, and Windows clients connecting to Linux or macOS servers on x86_64 or aarch64, or Windows servers on x86_64. Interactive setup can install or update the complete remote package after confirmation; background reconnects only discover installed packages. See Remote attach over SSH for SSH configuration, authentication, and custom binaries.

Add a machine

Run setup in an interactive terminal so Herdr can ask before installing or replacing anything:

herdr machine add workbox

In an interactive terminal, Herdr discovers running sessions: it selects the only running session, or lets you choose with Up/Down and Enter when several are running. Esc or Ctrl+C cancels. If a successful query finds no running sessions, setup uses default. If no Herdr installation is found, setup offers to install it for default. If an installed binary cannot report its sessions, setup reports the error; pass --remote-session <name> to select a session explicitly.

The sidebar shows the default session as workbox, the SSH host without any user@ prefix. Add --label "Build machine" to choose a different name. A machine profile targets one remote session; it does not combine every session on the host. Non-interactive commands use default unless --remote-session is supplied.

To skip discovery and use a specific session, add --remote-session:

herdr machine add workbox --remote-session agents

Without --label, this machine shows as workbox/agents. If the default name is already taken, machine add asks you to pass --label.

On Windows servers, setup also checks executables used by Herdr processes owned by the SSH user. It validates their capabilities before reuse, so a compatible running build can be used even when SSH’s PATH points to an older installation.

Herdr checks both the installed binary and the running server. It starts the requested background server before saving the profile. Compatible client and server versions do not have to match. Missing or incompatible installations go through an approval-based setup. When the running server needs replacement, setup asks before stopping it and its pane processes, then starts the compatible server. The default answer is No. If installation and replacement are both needed, one confirmation covers them. machine add does not use experimental live handoff. Cancelling or failing setup leaves the profile unsaved.

Run herdr to open the UI. If a local client is already open, added and enabled machines normally appear within a second and connect in the background without changing your selection. An in-progress machine switch finishes before profile changes are applied. The remote server keeps running after setup exits.

Switch between machines

Choose a machine or one of its workspaces in the sidebar. The selected machine receives your pane input and terminal size, and supplies the visible terminal content and graphics. Other connected machines keep updating their workspace information, agent states, and notifications without streaming their pane screens.

Click the arrow beside any machine to collapse or expand its workspace list without switching away from your current workspace. This also works while that machine is reconnecting.

For keyboard navigation, press prefix+w, then use the workspace navigation keys (Up/Down by default) to highlight workspaces across connected machines in sidebar order. Enter activates the highlighted workspace; Esc or the prefix key cancels without switching. Compact and expanded sidebars reveal the highlighted row, including under a collapsed machine. On desktop, navigation wraps at the ends; the mobile switcher stops at the first or last workspace. Disconnected machines are skipped.

When highlighting a workspace on another machine, press Enter before using other keyboard actions. This prevents pane, tab, workspace, or custom-command shortcuts from acting on the current machine by mistake. Clicking cancels a remote desktop keyboard preview. Expanded sidebars respect each machine’s collapsed worktree groups.

Local opens immediately on startup without waiting for SSH connections. Selecting Local also cancels an unfinished remote switch without waiting for the remote machine to reply. If Local itself is reconnecting, your selection resumes when it is ready. Local accepts input once its fresh screen and terminal settings are ready. A stalled machine cannot hold up another machine’s input. Multiple Herdr clients can also view different tabs on the same server independently; see Client and server for shared-tab sizing.

When a connection is lost, the last workspace and agent state remains visible but dimmed. That is cached information, not live state. Input and navigation into those cached panes stay disabled until a fresh connection and matching screen arrive. Reconnecting never takes selection away from the machine you are using.

Rename, disable, or remove

Read profile IDs from the list rather than deriving them from labels or hostnames:

herdr machine list
herdr machine rename <profile-id> --label "New name"
herdr machine disable <profile-id>
herdr machine enable <profile-id>
herdr machine remove <profile-id>

For scripts, add --json to machine list.

Renaming changes the displayed label without reconnecting. Disabling keeps the profile for later; removing forgets it. Both disconnect only that machine from the client and leave its remote sessions and agents running, even if the host is unreachable.

Removing or disabling the machine you are viewing returns you to Local. If Local is unavailable, Herdr shows that and retries its connection instead of selecting a different remote machine. With enabled saved machines, the client can remain usable even if Local fails or restarts.

Connection problems

• Reconnecting: Herdr retries automatically after a network interruption, sleep, or SSH failure. Repeated failures increase the delay up to two minutes; brief successful connections do not reset it. A connection must remain healthy for a minute before the next interruption gets a fast retry. SSH connections are checked for application-level activity and probed when quiet, so a broken connection does not stay Online indefinitely. Local detects native connection closure or failure instead of using remote health probes.
• Attention: The target needs an action such as authentication, host-key approval, or a compatible server. Other machines remain usable. ! auth means authentication failed; ! error indicates another issue. Click the badge for the error and a CLI command. In a collapsed sidebar, either appears as !.
• Saved-machine file error: An unreadable or invalid catalog leaves current connections unchanged. Herdr shows a notice and automatically retries reading it.

When both installations support bridge idle cleanup, saved-machine connections to Linux and macOS also close their remote bridge after a minute without traffic in either direction. Sleep counts toward that deadline, which is checked when the host wakes. Quiet healthy connections exchange health checks; watching continuous output does not require typing. Cleanup leaves the remote Herdr server, sessions, and pane processes running. Older installations remain compatible without this optional cleanup.

Background connections never answer prompts or install, update, restart, or hand off a server. For non-authentication Attention, run the standalone setup command shown by Herdr in an interactive terminal, for example:

herdr --remote workbox

Use your profile’s target. If you chose a named session when adding it, include the optional --session <name> here too. Follow the requested setup prompts; open clients retry automatically. machine reconnect does not install or update Herdr. Do not stop a running server merely because its version differs from the client.

If authentication fails, check ordinary SSH first. For a passphrase-protected key, load it with ssh-add before starting Herdr’s non-interactive background connections.

For Git authentication or SSH signing inside remote panes, enable ForwardAgent yes for the trusted host in your SSH config. Herdr does not enable forwarding for you. When a session starts with an agent, updated Linux and macOS servers give panes a stable agent address, so existing and new panes can use the forwarded agent after --remote or a saved machine reconnects. A working inherited agent or earlier connection keeps priority over later clients and temporary setup checks; if it disappears, another live attachment can supply the agent.

This requires an updated remote server, not just an updated local client. Local sessions started without an agent leave SSH_AUTH_SOCK alone. Panes created before the server update, or before an agent was first supplied to the session, keep their original environment and need to be recreated once to inherit the stable address. Older compatible servers and connections without agent forwarding can still attach normally.

Settings and automation

The UI uses the client’s local theme, sidebar settings, and keybindings by default. Custom commands and plugins advertised by the selected server still run there. Herdr does not copy local command plugins, configuration, executables, or secrets onto SSH hosts. Missing remote commands fail visibly. Use the UI’s reload config action after editing client settings; see Configuration.

Default agent rows show a machine token when multiple machines are present. Existing custom rows are preserved; add machine explicitly if you want that label in your layout. Sidebar row layouts also support conditional colors for machine labels.

Workspace, tab, pane IDs, and agent names are scoped to one server. Two machines may both contain w1:p1 or an agent named reviewer. Selecting a machine in the UI does not retarget CLI commands running in an existing pane: they still use that pane’s inherited session and socket. For remote automation, use herdr --machine <label-or-id> agent list, then pass the same prefix when controlling those remote IDs. The CLI uses the saved profile’s SSH target and session directly; it does not need an open TUI. Without --machine, existing session/socket routing is unchanged. See CLI reference for supported commands, update requirements, and remote path rules.

Updates and saved data

Saved profiles contain only an opaque ID, label, SSH target, explicit remote session, and enabled state. Herdr does not store passwords, private keys, agent tickets, or SSH control sockets in the catalog. Authentication stays with OpenSSH.

Herdr separately remembers each machine’s remote OS and resolved executable path so repeated --machine commands can skip discovery. Existing profiles learn missing information on first use. This cache is optional: missing, invalid, or unwritable cache files do not prevent commands from working. Commands still check live server compatibility. If a cached executable is missing or no longer supports API forwarding, Herdr rediscovers it during the initial read-only check; it never automatically repeats a command that may already have changed remote state.

The client and server negotiate compatibility rather than requiring identical versions. Saved-machine connections additionally need the server’s surface_interest and health_check capabilities. Older servers without those capabilities show Attention until explicitly updated, even if a standalone attach works. Other missing server methods disable only their corresponding actions.

Updating a compatible client does not replace the running remote server or stop its agents. When you need new server-side behavior, update that server explicitly. Normal replacement asks before stopping the server and its pane processes.

Live handoff is experimental and opt-in. For a supported server that needs replacement during standalone setup, you can explicitly add --handoff to herdr --remote; it is not needed for normal connections or authentication fixes. See Update for restart and handoff choices, and Session state and restore for what survives each operation.