Choosing Sandbox Options

How durability, resource mode, and pricing tier combine — and how to pick the right mix.

Three of the most important create-time choices — durability, resource mode, and pricing tier — are often confused for alternatives, but they are independent axes. A sandbox picks one value from each, and the choices compose freely. Understanding them as separate dimensions makes it easy to describe exactly the sandbox you want: for example "durable, cheap, and interruption-tolerant" is simply persistent + burstable + spot.

The three axes

Axis	Parameter	Values	Controls
Durability	`persistent`	ephemeral (default) / persistent	Whether the machine survives being turned off — and thus whether it can stop/start, pause/resume, and fork
Resource mode	`mode`	burstable (default) / dedicated	Whether your CPU/memory/disk request is a floor you can burst past, or an exact fixed shape
Pricing tier	`spot`	on-demand (default) / spot	A discount on CPU/memory in exchange for being reclaimable under capacity pressure

Each axis is covered in depth on its own page — Persistent sandboxes, Burstable vs dedicated, and Spot sandboxes. This page is about how they fit together.

Durability: ephemeral vs persistent

Durability decides what "off" means. An ephemeral sandbox (the default) keeps its writable disk on fast host-local storage; it exists only until you delete it, and it has just two lifecycle operations — create and delete. A persistent sandbox puts its write layer on durable network-backed storage, so it can be stopped and started later (on any hardware), paused and resumed with live memory intact, and forked — and it survives host failure by becoming stopped rather than being lost.

The trade is speed and cost: ephemeral sandboxes get the fastest create path and bill only while they run; persistent sandboxes cold-boot and bill for storage for as long as they exist, even while stopped.

Resource mode: burstable vs dedicated

Resource mode decides how your CPU/memory/disk request is interpreted. In burstable mode (the default) the request is a guaranteed floor: the sandbox is always guaranteed at least what it asked for, and can opportunistically use idle host capacity above it (up to the platform burst caps). In dedicated mode the sandbox is shaped exactly as requested — no bursting, fully reproducible performance.

Billing follows the guarantee, not the peak, which is what makes burstable the economical default: you reserve a small floor, pay for that floor, and get bursts for free when capacity is idle.

Pricing tier: on-demand vs spot

Pricing tier decides the rate and the reliability. On-demand (the default) is full price and never reclaimed. Spot discounts CPU and memory in exchange for reclaimability: when a host runs hot, spot sandboxes are reclaimed newest-first. Because the CPU/memory charge is based on your guarantee, spot effectively discounts the floor you reserve.

Crucially, what a reclaim does depends on the durability axis:

Ephemeral spot → deleted on reclaim.
Persistent spot → paused (memory + processes preserved, resumable).
Persistent spot with attached volumes or a Docker device → warm-stopped (disk survives, memory does not), because pausing is unavailable for those.

This is the clearest example of the axes interacting: spot's behavior is only fully defined together with durability.

Combining the axes

All eight combinations are valid. These are the ones worth knowing:

Durability	Mode	Tier	Good for
ephemeral	burstable	on-demand	The default. Disposable work, agents, one-off jobs — cheap floor, fast peaks, delete when done.
ephemeral	dedicated	on-demand	Reproducible one-off benchmarks; no need to keep the machine afterward.
persistent	burstable	on-demand	Long-lived dev environments and stateful agents you stop/resume; economical everyday shape.
persistent	burstable	spot	Interruption-tolerant long-running work — cheapest resumable option; reclaim = pause. The recommended cheap-and-durable mix.
ephemeral	burstable	spot	Cheap disposable batch work that is idempotent or writes results to a volume/object store; reclaim = delete.
persistent	dedicated	on-demand	Stateful services needing predictable performance and warm stop/start.

A quick decision guide

Do you need the machine to survive being turned off (stop/pause/fork, or crash-resilience)? → persistent: true. Otherwise leave it ephemeral.
Does run-to-run performance need to be identical? → mode: "dedicated". Otherwise leave it burstable (cheaper, bursts for free).
Can the work tolerate being interrupted and retried/resumed? → spot: true for the discount. Pair it with persistent: true so a reclaim pauses instead of deleting — and avoid volumes/Docker on that sandbox if you want the reclaim to preserve live memory.

See the parameter reference for defaults, minimum clamps, and the burst caps.