Concepts - boat

Boat gives you sandboxes. A sandbox is a full Linux virtual machine with its own disk. You stop it to stop paying, and you resume it later with the same disk.

Lifecycle

State	API state names	CLI and dashboard show	Billed	Disk
Starting	`provisioning`, `provisioned`, `cloning`	`provisioning`, `starting`, `cloning`	From `provisioned`	Restoring
Running	`ready`, `idle`, `running`	same	Yes	On the machine, saved each minute
Stopping	`archiving`	`stopping`	No	Last save in progress
Stopped	`archived`	`stopped`	No	Saved for 14 days, then deleted
Error	`error`	`error`	No	Held for 3 days
Deleted	none	none	No	Erased

The API calls a stopped sandbox archived. It is the same state. Nothing is moved or deleted. idle and running differ only for the integrated agent: running means a prompt runs now. Commands work in both. What works at ready, and what comes a few seconds later, is in Readiness and resume speed.

Words

Word	Meaning
Sandbox	One Linux virtual machine that you create, with its own disk, IP address and id (`bx_...`).
Machine	The hardware under a sandbox. A resume or a fork puts the sandbox on a new machine.
Size	The CPU, memory and disk of a sandbox: `small`, `default` (the medium size), `large`, `xlarge`. Read Machines.
Snapshot	A saved copy of the disk. Boat takes one every minute and one at each stop. Only the newest one is used. Read Snapshots.
Named snapshot	A snapshot that you save under a name. It never expires. Start new sandboxes from it with `boat new --from <name>`. Read Named snapshots.
Template	Not a separate object. “Use a named snapshot as a template” means: start many sandboxes from one named snapshot.
Stop	Save the disk, then remove the machine. Memory and running programs are not kept. There is no pause. A stopped sandbox costs nothing, and Boat keeps its disk for 14 days. Read Stop a sandbox.
Auto-stop	A timer that stops the sandbox. The default is 1 hour after the create or the last resume. Read Auto-stop.
Always on	A sandbox with auto-stop turned off. It runs until you stop it.
Resume	Start a stopped sandbox again, from its newest snapshot. Same id, new machine, new IP address.
Fork	Make a new sandbox that copies the newest snapshot of another sandbox. The source does not change.
Restore	Get older files back. Resume and fork cannot use an older snapshot. Read Restore an older snapshot.
Recover	Restart the machine of a sandbox that does not answer. The disk is not touched. Read Troubleshooting.
Delete	Erase a sandbox and its snapshots for good. You cannot get it back. Read Delete a sandbox.
Ready	The sandbox runs commands now. Read Readiness.
Hydrated	All file content has arrived after a resume or fork. Files are readable before that.
Environment	Settings that a sandbox starts with: variables, secret files, repositories and logins. Read Environments.
Setup script	Commands that run when a sandbox starts. Read Setup scripts.
Public URL	An HTTPS address for one port of a sandbox. Read Public URLs.
Share code	A secret code (`bsh_...`) that lets another account start a sandbox from your named snapshot.
Organization	A team account. Members share sandboxes, a balance and seats. Read Organizations.
Active wallet	The account that pays for a new sandbox: you, or an organization. Read Active wallet.
Seat	One paid member place in an organization. Each seat adds the plan price, the included time and the limits.

Words at other providers

Other providers use some of the same words for other things. This table gives the closest Boat word.

Boat	E2B	Daytona	Modal
Sandbox	Sandbox	Sandbox	Sandbox
Stop (disk kept, memory not kept)	Pause in filesystem mode. A default pause keeps memory, a Boat stop does not	Stop	No match. Save a filesystem snapshot, then terminate
Resume	Resume (connect)	Start	Create a sandbox from the saved image
Delete	Kill	Delete	Terminate
Named snapshot	Template	Snapshot	Filesystem snapshot (an image)
Fork	No direct match. Create from a template or snapshot	No direct match	Create from a filesystem snapshot
Auto-stop	Timeout	Auto-stop interval	Timeout
Stopped state	Paused	Stopped. Boat has no separate archive step: a stopped sandbox is already in storage	No match

Two differences cause most surprises:

A Boat snapshot is automatic and per sandbox. A Daytona snapshot is closer to a Boat named snapshot.
A Boat stop does not keep memory. Programs that you started by hand do not come back. Enabled systemd services and Docker containers start again. Read What a snapshot saves.