Core concepts¶

A few terms used throughout these docs.

Machine vs Sandbox¶

They are the same thing, named for two audiences:

Machine — the resource noun used by the API (/v1/machines) and the dashboard. Neutral: it can be a throwaway sandbox or a long-lived dev environment.
Sandbox — the SDK ergonomic (Sandbox()), framing a Machine for the common case: create → run code → destroy.

A "sandbox" is just how you use a Machine. There is no separate sandbox resource.

microVM¶

Each Machine is a real Firecracker microVM with its own Linux kernel — the security boundary for running code an LLM just wrote. This is stronger than a shared-kernel container.

Lifecycle¶

create ──▶ running ──▶ (stop ──▶ stopped ──▶ start ──▶ running) ──▶ destroy

State	Meaning	Billing
`running`	Booted, can exec / terminal	vCPU + storage
`stopped`	Disk preserved, not running	storage only ("stopped is cheap")
destroyed	Gone, disk reclaimed (unless preserved)	none

Two usage patterns (same Machine)¶

Pattern	Lifespan	Driven by
Sandbox (AI/untrusted code)	seconds–minutes	`exec` then destroy (SDK)
Dev environment	hours–days	terminal/SSH + volumes, kept running

Exec¶

run() / POST /v1/machines/{id}/exec runs a command inside the microVM through its network namespace (no SSH needed) and returns {exit_code, stdout, stderr}.

Volumes¶

Persistent disks you can attach to a Machine. Data survives destroy/recreate. See Volumes.

Snapshots¶

Point-in-time CoW images of a machine's root volume (disk undo / clone). Not off-site backups. See Snapshots.

Images / stacks¶

The base filesystem a Machine boots from (base, python, node, debian13, ubuntu24.04). See Images.

API keys & scopes¶

Programmatic auth uses sk_live_… keys. A read key can list; a full key can create and run. See Authentication.