Machines

Run the agents, their dev servers and their databases on another computer, and keep driving them from the board on your laptop. A server, a cloud VM, a dev box your team shares: if ssh gets you in, kelpie can use it.

What a machine is

Five feature branches, each with its own dev server, database and agent, is more than a laptop wants to carry. A machine moves that work somewhere bigger without changing how you work with it.

The machine runs its own kelpie board, headless. Your board reaches it over one ssh connection and shows its sessions beside your local ones, each with a cloud chip. Chat, the diff, Start feature and review all work the same. Every port your processes listen on over there is forwarded to the same port on your laptop, so a feature’s URL is still localhost:3000, its annotation toolbar still loads, and a phone you have paired with the board still opens its preview.

Any Linux box will do. Kelpie is tested on Ubuntu 24.04. Size it at about 4 GB of memory per feature you expect to run at once.

Adding one

There is one requirement: ssh <host> logs you in without asking anything. No password, no passphrase, no host-key question. A key without a passphrase or a running ssh agent does it. Check it first:

ssh -o BatchMode=yes me@box true && echo ok

Then give the box a Claude sign-in. claude setup-token prints a long-lived token: keep the line that starts with sk-ant-oat01-, not the code the browser shows, and save it where kelpie looks:

claude setup-token
# paste the sk-ant-oat01- line into ~/.config/kelpie/claude-token, then:
chmod 600 ~/.config/kelpie/claude-token
kelpie machine add me@box

machine add does the rest over that one connection:

1. Checks that ssh logs in by itself, and stops with ssh’s own reason if it does not.
2. Installs git, gh, tmux, Docker, node, pnpm, bun and Claude Code. It uses sudo where there is one; on a box where you have none, it checks they are already there.
3. Stores Claude’s token on the box, readable by you only.
4. Signs the box’s gh in with your GitHub token, and copies your git name and email, so its agents can push branches and open pull requests.
5. Sends it the kelpie you are running, into ~/.local/share/kelpie, so the box needs no access to kelpie’s repository, and starts its board as a user service that survives logout and reboots.
6. Adds the machine to your config. A running board picks it up within seconds.

Run it again at any time to update the box to the build you have. --name sets what the board calls it; --token-file reads the token from somewhere else.

Providers

Kelpie never talks to a cloud API. It runs ssh, so login, keys and host checks stay with OpenSSH, and a provider plugs in by giving you an ssh Host. Once ssh name works, kelpie machine add name does too.

A server or VPS

Nothing to do beyond a key: kelpie machine add [email protected], or a Host you already have in ~/.ssh/config.

Google Compute Engine

Reach the VM through IAP, so it needs no public ssh port. Allow IAP’s range, 35.235.240.0/20, to reach port 22 on a network tag, give the VM that tag, and add a Host whose ProxyCommand opens the tunnel:

Host gce-box
  HostName gce-box
  User me
  IdentityFile ~/.ssh/kelpie_machine
  ProxyCommand gcloud compute start-iap-tunnel gce-box 22 --listen-on-stdin --project my-project --zone us-central1-a --verbosity=error

The kelpie repository has docs/machine-gce.sh, which creates the VM (an e2-standard-4: 16 GB, room for three features), writes that Host and runs machine add on it.

AWS EC2

The same shape through Session Manager, as AWS documents it: a Host for the instance id whose ProxyCommand opens the session:

Host i-0123456789abcdef0
  User ubuntu
  ProxyCommand sh -c "aws ssm start-session --target %h --document-name AWS-StartSSHSession --parameters 'portNumber=%p'"

GitHub Codespaces and Coder

Both write the Host for you: gh codespace ssh --config prints entries to add to ~/.ssh/config, and coder config-ssh adds them itself. Mind the provider’s own limits: a codespace stops when it idles and is deleted after a while, and its agents stop with it.

Sandboxes with no ssh

Some sandbox services offer only an exec command, not ssh. Kelpie does not support those yet: it needs ssh’s port forwarding for the board and for every dev server, and an exec pipe carries one stream, not ports.

Using it

The New menu gets a machine picker once a machine is connected. It lists the same repos whichever machine you pick. On a machine, New, chat, Start feature and review use the repo’s checkout there, and clone it into the box’s home first if it has none. A session started on a machine is a chat you type into from the board, since the box has no screen to open a window on.

The first time you start something in a repo on a machine, kelpie copies that repo’s git-ignored .env* files over, readable by you only, and never over a file the box already has. Secrets your dev server needs arrive without a separate step.

From the terminal, and for agents that drive kelpie, --machine does the same as the picker:

kelpie chat --machine box --cwd ~/acme --ask "run the test suite"
kelpie feature --machine box --cwd ~/acme fix-login --ask "the login form drops the email"

A port already in use on your laptop is not forwarded, so a database running on the box never shadows the one running here.

Staying connected

Your board connects with nobody at a terminal, so the login has to keep not asking. The usual way it breaks is a sign-in that expires: a gcloud or aws session behind a ProxyCommand, or a key that left the agent. Kelpie retries every few seconds, and a machine that stays unreachable shows on the board within a few minutes as a setup problem, with ssh’s reason and the command to run yourself:

gce-box is not connecting: ERROR: (gcloud.compute.start-iap-tunnel) ... Reauthentication failed.
  ssh gce-box true

Sign in again in a terminal and it reconnects on its own. If ssh logs in but the board does not answer, the fix it names restarts the box’s board service instead.

The machine’s entry in ~/.config/kelpie/config.json is what machine add wrote:

"machines": [
  { "name": "box", "ssh": "me@box" }
]

ssh can also be the argv of a command that opens ssh and accepts ssh options after it, such as ["gh", "codespace", "ssh", "-c", "name", "--"], and port is set when the box’s board is not on 4321.

What it does not protect

A machine keeps the agents off your laptop. It does not keep them apart from each other, or from your accounts: everything on the box runs as one user, with your Claude token, your GitHub sign-in and your repos’ secrets. Give each person a box of their own.

On a box several people share, each person’s board gets a port nobody else holds, and only your own dev servers are forwarded to you. But anyone on that box can reach your board on its loopback port, so share one only with people you would hand your Claude sign-in.

Questions

Is a machine a sandbox?

No, and kelpie does not call it one. It holds your repos, your Claude token and your GitHub sign-in. Treat it as your own dev box, not as a container for code you do not trust.

What happens to the agents when my laptop sleeps?

They keep running. The box’s board owns them; your board only shows them, and catches up when the connection comes back.

Does it work with agents other than Claude Code?

The box’s board shows whatever agents run there, the same as yours does. Setup signs in Claude Code only; sign the others in on the box yourself.

How do I remove one?

Delete its entry from machines in your config. To stop its board too, run ssh box 'bash -s -- remove' < docs/machine-setup.sh from the kelpie repository; repos, worktrees and config on the box are left as they were.