Skip to content

How to work with Herdsman

Run Herdsman where the work lives. Attach from wherever you are.

Herdsman is a background session server plus one or more terminal clients. Panes keep running in the server. Clients attach, detach, and render the session.

Start Herdsman from the project directory:

Terminal window
herdsman

Herdsman starts or attaches to your local background session automatically. You do not manage sockets. Run shells, servers, tests, and agents normally inside panes.

Detach the client with ctrl+b q. Your panes keep running.

Reattach later:

Terminal window
herdsman

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

Terminal window
herdsman server stop

SSH to the machine that has the code and credentials, then run Herdsman there:

Terminal window
ssh you@server
herdsman

This works like a terminal multiplexer. Your shell is remote. The Herdsman server is remote. The agents and panes run on the remote machine. Detach with ctrl+b q, disconnect, then SSH back and run herdsman again.

Use this path when you already live inside an SSH shell, when you are on a phone or tablet SSH client, or when you want the simplest setup.

Herdsman works on your phone without a mobile app or web dashboard. Install any SSH client, connect to the machine where your agents run, and start Herdsman there:

Terminal window
ssh you@server
herdsman

The same persistent Herdsman session opens in your phone terminal. The TUI adapts to narrow screens, so you can inspect agents, switch workspaces, and check panes without leaving SSH.

On iPhone, apps like moshi work well.

Herdsman agent session over SSH on a phone
agent session over SSH
Herdsman responsive switch menu on a phone
responsive switch menu

Attach through SSH without opening a shell first:

Terminal window
herdsman --remote workbox
herdsman --remote ssh://you@server:2222

The remote server keeps the panes running and sends their terminal content and session state over SSH. Your local Herdsman draws the UI using your local theme and presentation settings.

Use this path when you want the remote session to feel local. The client runs on your machine, so local desktop features such as image clipboard paste can be bridged to the remote server. If you SSH first and run herdsman on the server, Herdsman runs entirely on that server and cannot read your local desktop clipboard.

For repeat targets, put the host in your SSH config:

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

Then attach with:

Terminal window
herdsman --remote workbox

Use herdsman for local work. Use ssh you@server then herdsman when you want Herdsman to behave like tmux on that remote shell or when you are using a phone SSH client. Use herdsman --remote <host> for a local UI attached to one remote session, including local clipboard image paste. To keep Local and several SSH machines in one window, save them with herdsman machine add <host> --label <label>; see Connecting machines.

For remote bootstrap details, named remote sessions, custom binaries, and direct terminal attach, see Persistence and remote access.