Run Agents on boat.dev

boat.dev gives you Linux sandboxes that you reach over SSH. A sandbox is an Ubuntu 24.04 VM with systemd and passwordless sudo. pocketty connects to it over plain SSH with your phone’s key, so you get herdr Panes, Changes, Files and previews in the cloud.

A sandbox is not an always-on host by default. It stops on a timer, and its address changes each time it starts again. Read Stop and start before you rely on it.

Before You Start

• A boat.dev account, and a computer with curl and jq.
• A boat.dev API key that can create sandboxes and use SSH. In the dashboard, open the API Keys tab and allow the actions sandbox.create, sandbox.read, sandbox.update, sandbox.stop, sandbox.resume, sandbox.delete and ssh. Put the key in the variable BOAT_API_KEY in your shell.

1. Create the Sandbox

On your computer, run:

curl -sS -X POST https://boat.dev/api/v1/sandboxes \
  -H "Authorization: Bearer $BOAT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"type":"small","ttlSeconds":7200}'

Copy sandbox.id from the answer, for example bx_abcd2345. small is the smallest size. ttlSeconds is the time until the sandbox stops. The sandbox is ready when GET https://boat.dev/api/v1/sandboxes/<id> shows state as idle.

2. Add Your Phone’s Key

1. In pocketty, open Settings. Under Device Key, tap Copy Key.

2. On your computer, send the key to the sandbox. Put your key in KEY, and your sandbox id in ID:

   KEY='ecdsa-sha2-nistp256 AAAA… pocketty'
   ID=bx_abcd2345
   curl -sS -X POST https://boat.dev/api/v1/sandboxes/$ID/sshkey \
     -H "Authorization: Bearer $BOAT_API_KEY" \
     -H 'Content-Type: application/json' \
     -d "{\"key\":\"$KEY\"}" | jq '{sshUser, sshEndpoint}'

The answer holds the values that pocketty needs:

• sshUser is the User. It is user.
• sshEndpoint is host:port. The part before the colon is the Address. The part after it is the Port. The port is not 22.

boat.dev accepts the phone’s P-256 key. Send key to host and the setup command do not work here, because you add the key through the API.

3. Add the Sandbox on Your Phone

1. Tap + on the host list.
2. Type these:
   • Name: any name you want. It is only a label in pocketty.
   • Address: the host from sshEndpoint.
   • Port: the port from sshEndpoint.
   • User: user.
3. Keep Sign in with on Device key, and tap Save.
4. Tap the host. The dot next to its name turns green when pocketty is connected.

4. Set Up herdr and the pocketty Daemon

Only your phone has the key for this sandbox, so do the setup from pocketty. On the host screen, tap New shell, and run:

curl -fsSL https://pocketty.app/vm.sh | bash

The script:

• Installs herdr, with its hooks for Claude Code, Codex and Pi.
• Runs herdr as a systemd user service.
• Installs the pocketty daemon, which sends agent notifications.

When it is done, go back to the host screen, and pull down to refresh it. The host screen then shows New workspace. Tap it, type a name, and tap Create. Start your agent in the new Pane.

The sandbox now works like any other host:

• Changes and the file browser show the files on the sandbox.
• Previews load the dev servers on the sandbox through SSH.
• The sandbox can reach relay.pocketty.app, which agent notifications use.

Stop and Start

boat.dev stops a sandbox when its timer ends. It does not stop a sandbox when you disconnect, and it has no idle timer. The timer counts from the time the sandbox is created or resumed.

A stopped sandbox keeps its files. When you resume it, boat.dev puts it on a new machine, and these things change:

• The Address and the Port. Read them again from the sshkey call.
• The host key.
• Processes that you started by hand, such as a dev server. They do not come back.

Your phone’s key stays on the sandbox. herdr and the pocketty daemon start again, but herdr does not answer until you restart it.

To resume a stopped sandbox:

1. Call POST https://boat.dev/api/v1/sandboxes/<id>/resume, and send {"ttlSeconds":7200}.
2. Call the sshkey endpoint from step 2 again. It gives the new sshEndpoint.
3. In pocketty, delete the old host, and add the sandbox again as in step 3. A new host also trusts the new host key.
4. Tap the host, tap New shell, and run systemctl --user restart herdr. Go back to the host screen, and pull down to refresh it.

To stop a sandbox before its timer ends, call POST https://boat.dev/api/v1/sandboxes/<id>/stop.

Delete the Sandbox

A stopped sandbox costs nothing. To delete one for good, send DELETE https://boat.dev/api/v1/sandboxes/<id> with the header X-Ascii-Confirm-Delete: <id>. You cannot undo this.

If It Does Not Connect

• Timeouts: the sandbox is stopped or has a new address. Resume it, then read the Address and Port again from the sshkey call.
• Sign-in refused: the sandbox does not have your phone’s key. Do step 2 again.
• The sshkey call says the key cannot perform ssh: your API key does not allow the action ssh. Make a new key in the dashboard.
• No New workspace: pull down on the host screen to refresh it. If it still does not show, herdr does not answer. Restart it as in Stop and start. In New shell, systemctl --user status herdr shows the service.
• No notifications: in New shell, check pocketty status and pocketty devices. See Agent Notifications.