Pattern 1: one always-on sandbox per project
This pattern is the simplest, and each project is fully isolated.- Make a sandbox for each user project with
--no-auto-stop. - Clone or copy the user’s code into it.
- Run the user’s dev server.
- Expose the dev server.
- Anyone who has the full
_tokenURL can open it. boat does not check who signs in. Treat the URL like a password. - The preview stays up while the sandbox runs.
- A detached dev server does not come back after a stop or resume. To make it come back, run it as an always-on service.
Use this pattern when the project has real traffic, or when the user pays you enough to cover the cost.
Pattern 2: one always-on sandbox per user
This pattern is like pattern 1. The difference is that one sandbox holds all the projects of one 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
This pattern is the cheapest, and each sandbox is isolated. Most platforms end up with it. The sandbox runs only while the user works.- The user sends a message.
- If the sandbox of the user is stopped, run
boat resumeon it. This takes a few seconds. - At the same time, start your daemon and the preview again.
- Send the message to the agent.
- When the agent finishes, wait a short countdown.
- Run
boat stop. The stop makes a snapshot of the file system and stops the billing of machine time.
See Snapshots.
When the user is away for more than 14 days
boat keeps the disk of a stopped sandbox for at least 14 days. After that, automated retention cleanup can delete it once enabled. The job currently reports candidates without deleting them in production. Save a saved snapshot before day 14 to keep logins, browser sessions and files.- Record the stop time of each sandbox in your app.
- Each day, find the sandboxes that are still stopped after 13 days.
- Save a saved snapshot of each one:
boat snapshot <id> user-<userId>. This works on a stopped sandbox. - When the user comes back, start from it:
boat new --from user-<userId>. Then delete the saved snapshot.
When the user is done for good
You can resume a stopped sandbox. A delete is the end.- To delete, use
DELETE /sandboxes/{sandboxId},boat delete, or Delete permanently… in the⋯menu of the dashboard. - You cannot undo a delete. You cannot resume the sandbox after it.
When a stop is refused
A stop saves the disk of the sandbox first. If that save fails, boat refuses the stop. The sandbox keeps running, so the user does not lose work. You do not pay for that time. The meter pauses by itself from the first failed attempt. A stuck sandbox never shows on your invoice, and you have nothing to claim back. See When a stop is refused. What your backend sees:- Treat a refused stop as retryable, not as fatal.
- The stop stays pending. boat retries it until a save succeeds.
- Then the sandbox stops by itself.
- boat also sends an email to the sandbox owner.
force.
- 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.
Cost
To charge this cost to your users, read the meter of each sandbox for the billing period.
- Use
GET /sandboxes/{sandboxId}/usage, orboat usage <id>. - It works on running and stopped sandboxes.
- It counts exactly what boat charged 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.