Remote Work and Restore

Your tangible win

After this lesson, you can choose the correct Herdr connection path for a remote project and predict what will survive a detach, a server restart, or an update.

Three ways to attach

Local work

From the project directory, run:

cd ~/your-project
herdr

Herdr starts or attaches to the local background session. Run shells, servers, tests, and agents normally inside its panes.

SSH first, Herdr second

Use this when you already work in a remote shell, use a phone SSH client, or want the simplest mental model:

ssh you@server
herdr

The shell, Herdr server, panes, and agents all run on the remote server. Detach with Ctrl+B, then Q; disconnect SSH; reconnect later and run herdr again.

Local thin client

Use this when you want the remote session to feel local:

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

Your local Herdr is only the client. The remote host still owns the Herdr server and the work. Local desktop features such as image clipboard bridging can work through this path.

Detach is not stop

Detach the client with:

Ctrl+B, then Q

That closes your view, not the Herdr server. Panes, shells, agents, servers, tests, and commands continue running. Reattach with:

herdr

To actually stop the session and its panes:

herdr server stop

Named sessions

Named sessions provide independent Herdr servers with their own panes, tabs, workspaces, sockets, and runtime state:

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

Use a named session when you want a strong boundary between unrelated projects or operational contexts.

What survives?

Detach and reattach

This is the strongest persistence path because the original processes never stop:

Ctrl+B, then Q
herdr

Server restart

After the server stops and starts, Herdr restores the saved shape: workspaces, tabs, panes, working directories, layout, and focus. Ordinary shells, servers, tests, and commands are gone; panes return as new shells.

Native agent session restore

Supported official integrations can report native agent session references. Herdr can use those references to resume an agent conversation after a server restart. Check the current integration state:

herdr integration status

Without a valid native session reference, the pane falls back to a normal shell in its saved directory.

Pane history replay

Optional pane history restores recent terminal contents, not the old process. It is off by default because terminal output can contain secrets, tokens, prompts, and command output. If you enable it:

[experimental]
pane_history = true

Treat the Herdr config/session directory like terminal history.

Live handoff

Live handoff is an experimental, opt-in path for replacing a running server while trying to keep live panes and processes:

herdr update --handoff
herdr --remote workbox --handoff

It can preserve live PTYs and processes when it succeeds, but in-flight CLI requests, waits, subscriptions, client sockets, and pane-to-pane messages may be interrupted. Reconnect and retry those operations.

Checkpoint: choose the remote path

1. Identify where the repository and credentials live.
2. Run Herdr on that machine.
3. Choose SSH-first if you want a simple remote terminal.
4. Choose herdr --remote if you want a local-feeling client.
5. Detach with Ctrl+B, then Q.
6. Reconnect and verify the agent state before sending new input.

Remember this

Run Herdr where the work lives. Attach from wherever you are. Detach to preserve live work; restart only when reconstruction is acceptable.