Skip to main content
boat.dev sandboxes are Ubuntu virtual machines with git, Docker and Node.js, billed by the second while they run. A stopped sandbox keeps its disk, and boat stops a sandbox at its auto-stop time: an hour after you start it, unless something extends it. That makes a sandbox a worker you pay for only while you use it. This guide sets up a sandbox as an r5d worker that stops cleanly whenever boat stops it and connects again when you start it. An optional skill then keeps it running while agents work on it, and lets boat stop it once it’s idle.

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 user user, who has passwordless sudo and the docker group. The script:
  1. installs Bun at the version r5d pins, checked against its published checksum, and the CLIs at your environment’s version;
  2. enrolls the sandbox as your worker with the token (r5d-worker auth --enroll);
  3. 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;
  4. adds boat’s pre-stop hook, ~/.boat/pre-stop.
boat runs the pre-stop hook before every stop: yours, the dashboard’s and the auto-stop, for up to 60 seconds. A stop doesn’t signal the sandbox’s programs, and a worker that is simply cut off can’t tell how the commands it ran ended (its next start moves its workspace lock aside, but their outcomes stay unknown), so the hook stops the worker first: it ends what runs on it and releases its workspace before boat saves the disk. When you start the sandbox again, the worker connects by itself:
  • 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.
While the worker is offline, chats on it pause with Paused until worker ’…’ reconnects and continue by themselves once it connects (When the chat’s worker is unavailable). You can’t send a new message to a chat whose worker is offline: start the sandbox first.

Create the sandbox

  1. 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.
  2. 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.
  3. 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.
    With the boat CLI, download the script instead and run, in its directory:
  4. The worker shows under Your workers within about a minute. To follow the setup, boat info <sandbox> shows whether it succeeded, and boat ssh <sandbox> journalctl -u r5d-worker -f the 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.
The worker publishes its changes to r5d as it goes, so your other workers have them. To publish everything right before you stop it, choose Sync workspace in the worker’s menu in Settings → Workers (or run 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 the boat-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.
If a check fails, for example because your model provider is down, the sandbox simply stops at its auto-stop time, cleanly.

Set it up

  1. A boat API key. In boat’s dashboard, open API keys, choose Custom and select only sandbox.read, sandbox.update and sandbox.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.
  2. 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.
  3. The skill. Open Skills from the sidebar’s More tab, choose New skill, name it boat-keepalive and replace its SKILL.md with the text below (Create a skill).
  4. 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, or boat 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.sh in boat 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 50 shows why; systemctl status r5d-worker whether 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).