How to work with PK-Herdr

Next docs describe unreleased work from master. Stable docs remain at /docs/.

Run PK-Herdr where the work lives. Attach from wherever you are.

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

Local work

Start PK-Herdr from the project directory:

pk-herdr

PK-Herdr 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:

pk-herdr

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

pk-herdr server stop

Remote work through normal SSH

SSH to the machine that has the code and credentials, then run PK-Herdr there:

ssh you@server
pk-herdr

This works like a terminal multiplexer. Your shell is remote. The PK-Herdr server is remote. The agents and panes run on the remote machine. Detach with ctrl+b q, disconnect, then SSH back and run pk-herdr 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 possible setup.

Work from your phone

You do not need a PK-Herdr mobile app or a web dashboard. Install any SSH client on your phone, connect to the machine where your agents run, and start PK-Herdr there:

ssh you@server
pk-herdr

The same persistent PK-Herdr 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.

agent session over SSH

responsive switch menu

Remote work from your local terminal

Attach through SSH without opening a shell first:

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

Your local PK-Herdr acts as a thin client. It connects over SSH, starts or attaches to the remote PK-Herdr server, and streams the UI back to your local terminal. When [remote].manage_ssh_config is enabled, PK-Herdr reuses one OpenSSH connection for setup probes, installs, server checks, and the final bridge. Password-based hosts therefore prompt once instead of once per setup command.

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 pk-herdr on the server, PK-Herdr 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:

pk-herdr --remote workbox

Which path to use

Use pk-herdr for local work. Use ssh you@server then pk-herdr when you want PK-Herdr to behave like tmux on that remote shell or when you are using a phone SSH client. Use pk-herdr --remote <host> when you want a local thin client for a remote session, including local clipboard image paste bridging.

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