Persistence and remote access

Herdr keeps panes running in a background server. Your terminal client can detach and reconnect later.

For the local, SSH, and herdr --remote workflows, see How to work with Herdr.

Detach and reattach

Start Herdr:

herdr

Detach the client with ctrl+b q.

Your panes and agents keep running. Reattach by running Herdr again:

herdr

If you want to end the session and stop its panes, stop the default server:

herdr server stop

Named sessions

Use named sessions when you want independent Herdr servers.

herdr session list
herdr session attach work
herdr session attach side-project
herdr session stop work
herdr session delete side-project

A named session has its own panes, tabs, workspaces, sockets, and runtime state. It still shares the same global config file.

Use --json for scripts:

herdr session list --json
herdr session stop work --json
herdr session delete side-project --json

Remote attach over SSH

Run Herdr on a server and attach from any SSH client:

ssh you@server
herdr

In this mode your shell is remote, Herdr runs on the remote host, and panes keep running there after you detach.

You can also attach through SSH from your local machine:

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

In this mode your local Herdr is a thin client. It connects over SSH, starts or attaches to the remote Herdr server, and streams the UI back to your local terminal. Because the client runs locally, Herdr can bridge local desktop features such as image clipboard paste into the remote session by copying the image to a remote temp file and pasting that path.

For repeat targets, use your SSH config:

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

Then attach with:

herdr --remote workbox

Remote attach supports Linux and macOS hosts on x86_64 and aarch64. Herdr checks the remote platform, 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.

If you SSH into the server first and run herdr there, Herdr runs entirely on the server. That mode is useful and simple, but it cannot access your local desktop clipboard beyond normal terminal text paste.

When your local and remote platforms match, Herdr can copy the current local binary. Otherwise it downloads the matching release asset from https://herdr.dev/latest.json.

For local builds or custom binaries, set HERDR_REMOTE_BINARY to a local file path before running remote attach.

HERDR_REMOTE_BINARY=target/release/herdr herdr --remote workbox

Remote named sessions

Use --session with --remote to attach to a named session on the remote host:

herdr --remote workbox --session agents

Direct terminal attach

Full Herdr attach opens the whole workspace UI. Direct attach opens one server-owned terminal in your current terminal.

Attach by agent target:

herdr agent attach reviewer

Attach by terminal ID:

herdr terminal attach term_abc123

Direct attach streams the current rendered terminal state, then live ANSI frames. Input goes straight to that terminal.

Detach with ctrl+b q. Send a literal ctrl+b with ctrl+b ctrl+b.

Only one writable direct attach client owns input and resize for a terminal. Use --takeover to replace an existing owner:

herdr terminal attach term_abc123 --takeover

Single-process escape hatch

Use --no-session to run Herdr without the background server/client split:

herdr --no-session

This is mainly an escape hatch for debugging or compatibility. The default persistent session mode is the normal path.