Patterns

​

Pattern 1: one always-on sandbox per project

1. Make a sandbox for each user project with --no-auto-stop.
2. Clone or copy the user’s code into it.
3. Run the user’s dev server.
4. Expose the dev server.

boat ssh <id> "cd ~/project && npm run dev -- --host 0.0.0.0 --port 3000 &"
boat ssh <id> "host 3000 --private"
# prints https://<subdomain>-3000.on.boat.dev?_token=...

curl -sS -X POST "$BOAT_API_BASE/sandboxes/$BOAT_ID/commands" \
  -H "Authorization: Bearer $BOAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command":"npm run dev -- --host 0.0.0.0 --port 3000 &","cwd":"project"}'

curl -sS -X POST "$BOAT_API_BASE/sandboxes/$BOAT_ID/commands" \
  -H "Authorization: Bearer $BOAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command":"host 3000 --private"}'

await sandbox.command({
  sandboxId,
  command: "npm run dev -- --host 0.0.0.0 --port 3000 &", cwd: "project",
});
const hosted = await sandbox.command({ sandboxId, command: "host 3000 --private" });
console.log(hosted.stdout); // https://<subdomain>-3000.on.boat.dev?_token=...

sandbox.command(sandbox_id, CommandRequest(
    command="npm run dev -- --host 0.0.0.0 --port 3000 &",
    cwd="project",
))
hosted = sandbox.command(sandbox_id, CommandRequest(command="host 3000 --private"))
print(hosted.stdout)  # https://<subdomain>-3000.on.boat.dev?_token=...

• Only the people you give the _token URL to can open it.
• The preview stays up while the sandbox runs.

​

Pattern 2: one always-on sandbox per user

• Each project has its own folder and its own port.
• You install a small daemon in the sandbox. It multiplexes the agent sessions.
• This works well for up to 5 to 10 fullstack projects per user.

​

Pattern 3: stop and resume around usage

1. The user sends a message.
2. If the sandbox of the user is stopped, run boat resume on it. This takes a few seconds.
3. At the same time, start your daemon and the preview again.
4. Send the message to the agent.
5. When the agent finishes, wait a short countdown.
6. Run boat stop. The stop makes a snapshot of the file system and pauses billing.

​

When the user is done for good

• To delete, use DELETE /sandboxes/{sandboxId}, boat delete, or the ⋯ menu in the dashboard.
• A delete force-stops the sandbox. It permanently deletes the snapshots that only this sandbox uses.
• Boat keeps snapshot data that a fork, a resume or a named template still reads.
• You cannot undo a delete. You cannot resume the sandbox after it.

​

When a stop is refused

1. Treat a refused stop as retryable, not as fatal.
2. The stop stays pending. Boat retries it until a save succeeds.
3. Then the sandbox stops by itself.
4. Boat also sends an email to the sandbox owner.

• The sandbox stops with its last successful snapshot.
• Everything written after that snapshot is lost.
• You cannot undo it. Offer it only after a stop has already failed.
• Without force, the sandbox stops this way by itself after 3 days of failed saves. Boat sends an email to the owner before that.

boat stop bx_23456789 --force

curl -sS -X POST "https://boat.dev/api/v1/sandboxes/bx_23456789/stop" \
  -H "Authorization: Bearer $BOAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"force":true}'

await sandbox.stop({ sandboxId: "bx_23456789", force: true });

sandbox.stop(sandbox_id="bx_23456789", stop_request=StopRequest(force=True))

​

Cost

• Use GET /sandboxes/{sandboxId}/usage, or boat usage <id>.
• It works on running and stopped sandboxes.
• It counts exactly what Boat charged your balance for that sandbox.

​

Two improvements

• No preview downtime. Publish successful builds to a static host or a CDN. The sandbox is only for the agent and the dev preview. Production traffic never depends on a running sandbox.
• No agent latency. Run a copy of the agent without tools on your own server. It answers immediately and stalls while the sandbox resumes. For a working implementation, see optibox.