Sandboxes

What is a sandbox?

A sandbox is a hardware-isolated microVM — a Firecracker virtual machine with its own kernel, filesystem, and network stack. It is created from any OCI image, a Dockerfile build, or a snapshot, and it behaves like a small, dedicated Linux machine: you can run processes, write files, install packages, open network connections, and even run a Docker daemon inside it.

Because isolation is enforced by the hypervisor, code inside a sandbox cannot observe or interfere with other sandboxes or the host. That makes sandboxes the right primitive for running untrusted code — AI-generated programs, user submissions, agent tool calls — as well as for any workload that benefits from clean, reproducible environments.

Every sandbox runs the Daytona toolbox agent, which exposes command execution, file transfer, git operations, long-running sessions, and SSH over the API. This works on any image with zero changes — you do not need to install anything into your image to make it sandbox-ready.

Sandbox or function? A sandbox is a machine you hold and interact with — you create it, run things in it, and delete it when done. If instead you want to package code and call it on demand while Daytona manages the machines for you, see Functions. The rest of this page is about sandboxes.

Lifecycle states

A sandbox moves through a small set of states over its life. Creation is asynchronous: the API accepts the request and returns immediately with the sandbox in pending, then boots it in the background. The SDKs poll until the sandbox is ready, so in practice you only see intermediate states when polling the REST API yourself.

State	Meaning
`pending`	Create accepted; the sandbox is queued for placement.
`assigned`	Placed on capacity; the microVM is booting.
`running`	Booted and ready — toolbox calls (exec, files, SSH) work now.
`stopping` → `stopped`	A warm stop in progress / complete. Compute is released; the filesystem is kept (persistent sandboxes).
`pausing` → `paused`	A pause in progress / complete. Memory and processes are preserved along with the disk.
`failed`	The sandbox could not boot or hit an unrecoverable error.
`deleted`	The sandbox and its ephemeral storage are gone.

Which operations are valid depends on the current state and on whether the sandbox is persistent:

Action	Valid from	Requires
Toolbox calls (exec, files, git, SSH)	`running`	—
`stop()`	`running`	`persistent: true`
`start()`	`stopped`, `paused`	`persistent: true`
`pause()`	`running`	`persistent: true`; no volumes or Docker device
`resume()`	`paused`	—
`fork()`	—	`persistent: true`; no volumes or Docker device
`delete()`	any state	—

Ephemeral vs persistent

By default a sandbox is ephemeral: its writable disk lives on fast host-local storage and exists only while the sandbox does. Ephemeral sandboxes are the fastest to create and are ideal for disposable work — run, collect results, delete. Their only lifecycle operations are create and delete; there is no stop or pause.

Setting persistent: true at create time gives the sandbox a durable, network-backed write layer instead. That single change unlocks the richer lifecycle: warm stop and start (release compute, keep the filesystem, start again later — possibly on different hardware), pause and resume (additionally preserving memory and running processes), and fork (duplicating the sandbox into a new one). It also changes failure semantics: if the host running a persistent sandbox fails, the sandbox becomes stopped and can be started again — it is never lost.

See Persistent sandboxes for tradeoffs and examples.

Persistence is independent of where a sandbox's data lives: both ephemeral and persistent sandboxes can attach volumes and object stores for storage that outlives any single sandbox.

Python

from rlp import Daytona, CreateSandboxFromImageParams
 
daytona = Daytona()
 
# Ephemeral (default): create, use, delete.
scratch = daytona.create(CreateSandboxFromImageParams(image="python:3.12-slim"))
 
# Persistent: can be stopped and started later.
durable = daytona.create(CreateSandboxFromImageParams(
    image="python:3.12-slim",
    persistent=True,
))
durable.stop()
durable.start()

Spot sandboxes

Independently of persistence, a sandbox can be created on the spot tier (spot: true) for discounted CPU and memory in exchange for being reclaimable when the platform needs capacity. When a spot sandbox is reclaimed, a persistent one is paused (resumable later) and an ephemeral one is deleted; a reclaimed sandbox is stamped with spot_evicted_at. Use spot for interruption-tolerant work, ideally combined with persistent: true so reclaim means "paused" rather than "gone". See Spot sandboxes.

Resources

Each sandbox has three resource dimensions: CPU (which may be fractional, e.g. 0.5 cores), memory, and writable disk. How those numbers are enforced depends on the sandbox's mode. In the default burstable mode, your request is a guaranteed floor and the sandbox can opportunistically use idle capacity beyond it; in dedicated mode the sandbox is shaped exactly as requested for fully predictable performance.

See Burstable vs dedicated for how enforcement works and how to choose, and the parameter reference for defaults and limits.

What is a sandbox?

Lifecycle states

Ephemeral vs persistent

Spot sandboxes

Resources

On this page