What you need
- A boat.dev account with a plan or its free trial. The trial allows 2 sandboxes running at once, 25 hours of compute and an auto-stop time of at most 2 hours.
- An r5d installation that offers worker templates: Settings → Workers shows Cloud server and boat.dev when you create an enrollment token.
How it works
r5d writes a setup script around a one-time enrollment token. boat runs it once in the new sandbox, as the sandbox’s useruser, who has passwordless sudo and the docker group. The script:
- installs Bun at the version r5d pins, checked against its published checksum, and the CLIs at your environment’s version;
- enrolls the sandbox as your worker with the token (
r5d-worker auth --enroll); - runs the worker as the systemd service
r5d-worker, with the sandbox’s ID in its description (boat.dev sandbox bx_…) and in/home/user/.boat/sandbox-id; - adds boat’s pre-stop hook,
~/.boat/pre-stop.
- Within 10 minutes of the stop, boat gives you the same machine back, as it was. The hook left a timer that starts the worker as soon as the machine wakes up: it connects within a few seconds. Started again only seconds after it stopped, the machine may not notice it slept, and the worker connects within 3 minutes.
- Later, the sandbox starts on a new machine from the saved disk. The worker waits until boat has restored your home folder, then connects, usually within 15 seconds.
Create the sandbox
-
In Settings → Workers → Enrollment tokens, enter a label for the worker, such as
boat-1, choose Worker and create the token. In the setup checklist, choose A boat.dev sandbox under Where will your agents run? instead. -
Choose boat.dev and copy the setup script,
r5d-boat-setup.sh. The token in it works once, within an hour, so create the sandbox within that hour. -
In boat’s dashboard, open Sandboxes → Advanced create (the button beside New):
- choose a size;
default(4 vCPU, 8 GB) suits most work; - keep Auto-stop after at 1 hour, or set a longer time;
- turn on No env, so your boat secrets, GitHub access and agent logins stay off a machine where r5d’s agents run;
- paste the script under Setup script, and create the sandbox.
- choose a size;
-
The worker shows under Your workers within about a minute. To follow the setup,
boat info <sandbox>shows whether it succeeded, andboat ssh <sandbox> journalctl -u r5d-worker -fthe worker’s log.
Start and stop it
- Stop it in boat’s dashboard, with
boat stop <sandbox>, or let the auto-stop come. Whatever runs on the worker ends; chats on it pause. - Start it with Resume in the sandbox’s menu in boat’s dashboard, or
boat resume <sandbox>. Chats on it continue once the worker connects.
r5dctl workspace sync --worker boat-1); the keep-alive skill below does this before every stop.
boat keeps a stopped sandbox’s disk for at least 14 days. To keep it longer, save a snapshot in boat before then. boat doesn’t save /tmp, /var/tmp or caches such as ~/.cache.
Keep it running while you use it
boat’s auto-stop doesn’t know about r5d: at its time, boat stops the sandbox even while agents work there. A workspace chat on the worker can watch it for you with theboat-keepalive skill below. Ten minutes before each auto-stop time, the chat checks the worker:
- In use: an agent works there, a command runs for an agent (also a background process such as a dev server), or a terminal runs a command or printed something in the last 30 minutes. The chat moves the auto-stop time to an hour from then and says why in one line, such as Extended to 15:42 UTC: 2 agents working, dev server on :3000.
- A terminal idle for more than 30 minutes doesn’t count: the chat closes it and says so.
- Not in use, and no command ended in the last 15 minutes: the chat publishes the worker’s workspace and stops the sandbox. It then pauses with the worker, and continues by itself once you start the sandbox again.
Set it up
-
A boat API key. In boat’s dashboard, open API keys, choose Custom and select only
sandbox.read,sandbox.updateandsandbox.stop. Under Restrict to specific sandboxes or environments, select your r5d sandboxes (left empty, the key covers all your sandboxes), then give it an expiry and create it. The key can only read, extend and stop sandboxes. -
An account secret. In r5d, open Settings → Secrets and add the key as the environment variable
BOAT_API_KEY(Secrets). Every agent of your account can use it in its commands; agents never see secrets in chat. -
The skill. Open Skills from the sidebar’s More tab, choose New skill, name it
boat-keepaliveand replace itsSKILL.mdwith the text below (Create a skill). -
The chat. In the sidebar’s list, point at Workspace chats and choose its +, choose the boat worker in the composer’s worker menu, and send:
Use the boat-keepalive skill to keep this worker (boat-1) alive while it’s in use, and let boat stop it when it’s idle.
Keep one such chat per boat worker. It must run on that worker: it looks at the worker’s terminals on the machine, and pauses and continues with it. Each check makes several model requests on the chat’s model, which is why it starts ten minutes before the auto-stop time.
SKILL.md
Delete it
Delete the sandbox with Delete permanently in its menu in boat’s dashboard, orboat delete <sandbox>. That deletes its disk and snapshots, with anything the worker hadn’t published. Then, in r5d:
- revoke its sign-in under Settings → CLI & API → Authorized devices, where it is listed as Only boat-1;
- stop or delete its keep-alive chat;
- revoke the boat API key in boat’s dashboard once no sandbox needs it.
If something goes wrong
- The worker doesn’t connect after you create the sandbox.
boat info <sandbox>shows the setup’s status and error. A token works once, within an hour: create a new token, copy the new script into the sandbox and run it there (bash r5d-boat-setup.shinboat ssh <sandbox>). Running the script again finishes what a failed setup left. - The worker doesn’t connect after you start the sandbox.
boat ssh <sandbox> journalctl -u r5d-worker -n 50shows why;systemctl status r5d-workerwhether it runs. - The sandbox stopped while agents worked. Its auto-stop time came. Start it again: the chats continue. Add the keep-alive skill, or give the sandbox a longer auto-stop time in boat’s dashboard (Stops in on its row).