Linux Sandboxes

Linux sandboxes are Linux virtual machines (VMs). Each sandbox is a virtual machine, a microVM, that runs its own Linux kernel on shared physical hardware and has its own operating system, files, network connection, and fixed amount of processor, memory, and disk. The hardware enforces the boundary and isolation between sandboxes.

Use cases

Sandboxes are used wherever code must run in a real environment, but you cannot trust the code or you cannot afford for it to affect anything else.

• Code execution for AI agents: an agent writes code, runs it in a sandbox, reads the output, and decides what to do next. The sandbox gives the agent a real shell and filesystem while keeping its actions away from your infrastructure.
• Coding agents: an agent clones a repository, installs dependencies, edits files, runs the test suite, and opens a pull request, all inside one sandbox.
• Reinforcement learning (RL): training runs create very large numbers of identical environments, run one episode in each, score the result, and discard the environment. Fast creation from a shared snapshot keeps the cost of each environment low.
• Evaluation and benchmarks: each test case or model run gets a clean, identical machine, so results do not depend on leftover state from a previous run.
• Code interpreters and data analysis: a chat application runs user or model-generated Python against uploaded files and returns tables, charts, and results.
• Untrusted user code: online coding platforms, grading systems, and plugin hosts run code submitted by users without exposing other users or the service.
• Computer-use agents: an agent operates a graphical desktop, a browser, or desktop applications through screenshots and input events.
• Development environments: a developer gets a preconfigured machine from an image, connects over SSH or from an editor, and previews web applications through a URL.

Create a Linux sandbox

Create a Linux sandbox from the dashboard or programmatically.

1. Go to Daytona Sandboxes ↗
2. Click Create
3. Select Linux sandbox
4. Click Create

from daytona import Daytona

daytona = Daytona()
sandbox = daytona.v2.create()

from daytona import Daytona
from daytona.v2 import PortRequest, VolumeMount

daytona = Daytona()
volume = daytona.v2.volume.get("my-volume")

sandbox = daytona.v2.create(
    name="my-sandbox",
    labels={"team": "research", "run": "42"},
    cpu=2,
    memory=4,
    disk=20,
    ports=[PortRequest(vm_port=8080), PortRequest(vm_port=5353, proto="udp")],
    network_policy={"block_all": True, "allow_domains": ["pypi.org", "*.github.com"]},
    volumes=[VolumeMount(volume_id=volume.id, mount_path="/data", subpath="runs/42")],
    env={"LOG_LEVEL": "debug"},
    secrets=["GITHUB_TOKEN"],
    persistent=True,
    spot=False,
    region="us",
    cpu_arch="amd64",
    cpu_type="zen5",
    lifecycle={
        "idle_timeout_secs": 3600,
        "on_idle_timeout": "pause",
        "wake_on_request": True,
        "timeout_secs": 604800,
        "on_timeout": "delete",
    },
    idempotency_key="run-42-create",
    wait=120,
)

CPU types

A CPU type is a processor model that a Linux sandbox can request when it is created. Each type belongs to one architecture, amd64 or arm64, and has a tier: its rank within that architecture, starting at 1 for the lowest. Requesting a CPU type also sets the sandbox's architecture.

The CPU type list contains every type that a create request accepts, whether or not a runner provides it. To see which types a region can serve, add the region. A type is available in a region when a running runner there provides it. When no runner provides the type itself, a runner with a higher tier of the same architecture can serve it as a fallback. Availability reflects the runners that are live at request time. List regions gives the region slugs.

# List CPU types
daytona cpu-type list

# Check CPU type availability in a region
daytona cpu-type list --region us-west-1

Disk and network classes

A disk class is the tier of a host's local NVMe storage, and a network class is the tier of its network interface. Each class has a tier: its rank within its dimension, starting at 1 for the lowest. A create request cannot select a class. A new sandbox runs on hosts with its region's default classes, a fork keeps the classes of its source, and a persistent sandbox keeps its own classes when it starts again.

Each list contains the classes that hosts advertise and regions default to.

# List disk classes
daytona disk-class list

# List network classes
daytona network-class list

Lifecycle

Every Linux sandbox moves through a lifecycle. A Linux sandbox can have several different states. Each state reflects the status of your sandbox. A Linux sandbox transitions between states in response to user actions, or automatically when one of its timeouts elapses.

Every Linux sandbox supports wait for state, delete, timeouts, and lifecycle policy updates. Stop and start, pause and resume, fork, auto-stop, and auto-pause require a persistent sandbox. A persistent Linux sandbox keeps its filesystem across stop and start and across host failure. It keeps its memory and running processes across pause and resume, and in forks. An ephemeral Linux sandbox keeps its filesystem and memory until it is deleted.

Wait for state

Wait until a Linux sandbox reaches a target state. The wait stops early when the sandbox reaches a state from which the target is no longer reachable, such as failed or deleted. The SDKs use their own state names, so the SDK started state corresponds to the running state in the CLI and API.

# Block until the sandbox is started; returns the sandbox
sandbox.wait(until="started", timeout=60)

# Block until the sandbox is stopped or paused
sandbox.wait_for_state(["stopped", "paused"], timeout=60)

Stop / start

Stop and start a persistent Linux sandbox. Stopping shuts down the virtual machine and keeps the filesystem. Memory state is cleared. While a stop is in progress, the sandbox is in the stopping state and does not accept new requests. Starting boots the sandbox from its preserved filesystem, possibly on a different host. To keep running processes without consuming CPU, pause the sandbox instead.

from daytona import Daytona

daytona = Daytona()
sandbox = daytona.v2.create(persistent=True)

# Stop shuts down the VM; the filesystem is kept and memory is cleared
sandbox.stop()
sandbox.wait_for_state(["stopped"], timeout=60)

# Start boots the sandbox from its preserved filesystem
sandbox.start()

Pause / resume

Pause and resume a persistent Linux sandbox. Pausing keeps the filesystem and memory state, and the sandbox no longer consumes CPU. While a pause is in progress, the sandbox is in the pausing state. Resuming restores memory and continues all processes from the point they were frozen. Daytona also pauses a persistent spot sandbox when it reclaims the capacity, or stops it when it has volumes attached.

from daytona import Daytona

daytona = Daytona()
sandbox = daytona.v2.create(persistent=True)

# Pause freezes the sandbox with filesystem and memory intact
sandbox.pause()
sandbox.wait_for_state(["paused"], timeout=60)

# Resume continues all processes from the point they were frozen
sandbox.resume()

Fork

Fork a persistent Linux sandbox to copy its filesystem and memory state into a new, independent sandbox. A fork of a running sandbox starts running. A fork of a paused sandbox stays paused with the captured memory. A fork of a stopped sandbox copies only the filesystem and stays stopped. You can start, stop, and delete the fork without affecting the original.

Daytona records the source of each fork, so you can trace a fork back to the sandbox it was created from. You can fork a fork to build branches. Deleting the source sandbox does not affect its forks.

from daytona import Daytona

daytona = Daytona()
sandbox = daytona.v2.create(persistent=True)

forked = sandbox.fork(name="my-sandbox-fork")

Delete

Delete a Linux sandbox to tear down its virtual machine. Deletion works in any state, and the call returns once teardown starts. The sandbox moves from deleting to deleted when the teardown finishes. Daytona discards the sandbox's filesystem and memory, including the filesystem of a persistent sandbox. Images and snapshots captured from the sandbox remain, and forks of the sandbox are not affected.

Before Daytona detaches the sandbox's disk volumes, it runs a final commit on them, and the volumes keep their data.

from daytona import Daytona

daytona = Daytona()
sandbox = daytona.v2.create()

sandbox.delete()

Timeouts

Daytona stops, pauses, or deletes a Linux sandbox automatically when one of its two timers elapses. Each timer pairs an interval in seconds with the action it fires. Set both timers at create in the lifecycle object, and change them later through update lifecycle policy.

The valid actions depend on whether the sandbox is persistent and apply to both timers. Delete is valid for every Linux sandbox:

Auto-stop, auto-pause, and auto-delete are not separate settings. Each one is the idle timeout with the matching action.

Wake on request starts a stopped persistent sandbox, or resumes a paused one, when a request arrives for it through the Daytona proxy. Wake on request does not wake a sandbox whose delete timeout has elapsed.

Timeout

The timeout is a wall-clock budget. It starts when the sandbox is created and re-arms with the full budget every time the sandbox enters running: on start, resume, and wake. Activity does not extend it. A delete timeout fires in any state. A stop or pause timeout fires only while the sandbox is running. Once set, the timeout cannot be cleared.

When the timeout is omitted at create, Daytona applies the project's lifecycle defaults. Without a project default, Daytona applies the platform default timeout of 300 seconds, if the platform default is enabled. An explicit timeout must not exceed the organization maximum, 86,400 seconds (24 hours) unless the organization sets a different maximum.

When the action is omitted, it defaults to pause for persistent Linux sandboxes and delete for ephemeral Linux sandboxes.

from daytona import Daytona

daytona = Daytona()
sandbox = daytona.v2.create(
    # Delete the sandbox 2 hours after it last entered running
    lifecycle={"timeout_secs": 7200, "on_timeout": "delete"},
)

Idle timeout

The idle timeout fires after the sandbox has had no activity for the interval. Activity is any request through the toolbox API, preview URLs, VNC, and SSH, a toolbox command that is still running, and any lifecycle operation on the sandbox. The idle timeout is off by default unless the project sets one, has a minimum of 60 seconds, and requires an action. An idle stop or pause fires only while the sandbox is running. The action fires within about 2 minutes after the interval elapses.

Auto-stop

Stop a persistent Linux sandbox after a period of inactivity.

from daytona import Daytona

daytona = Daytona()
sandbox = daytona.v2.create(
    persistent=True,
    lifecycle={"idle_timeout_secs": 900, "on_idle_timeout": "stop"},
)

Auto-pause

Pause a persistent Linux sandbox after a period of inactivity. With wake on request, the next request through the Daytona proxy resumes it.

from daytona import Daytona

daytona = Daytona()
sandbox = daytona.v2.create(
    persistent=True,
    lifecycle={"idle_timeout_secs": 3600, "on_idle_timeout": "pause", "wake_on_request": True},
)

Auto-delete

Delete a Linux sandbox after a period of inactivity.

from daytona import Daytona

daytona = Daytona()
sandbox = daytona.v2.create(
    lifecycle={"idle_timeout_secs": 3600, "on_idle_timeout": "delete"},
)

Reset the idle timer

Reset the idle timer of a Linux sandbox to keep it alive while it does work that Daytona does not count as activity. The reset counts as activity, so the idle countdown restarts from now. The timeout is not affected.

The reset succeeds in any state, whether or not an idle timeout is set. It never moves the timer backwards: when newer activity arrives at the same time, the newer activity wins.

from daytona import Daytona

daytona = Daytona()
sandbox = daytona.v2.create(
    lifecycle={"idle_timeout_secs": 3600, "on_idle_timeout": "delete"},
)

lifecycle = sandbox.reset_idle_timer()
print(lifecycle.idle_timeout_at)

Update lifecycle policy

Update the timeouts of an existing Linux sandbox. Omitted fields keep their current values. The new actions must be valid for the sandbox, as listed in timeouts.

from daytona import Daytona
from daytona.v2 import DISABLED

daytona = Daytona()
sandbox = daytona.v2.create(persistent=True)

# Pause the sandbox after 30 minutes without activity and wake it on request; omitted fields keep their current value
lifecycle = sandbox.set_lifecycle(idle_timeout_secs=1800, on_idle_timeout="pause", wake_on_request=True)
print(lifecycle.idle_timeout_secs, lifecycle.on_idle_timeout)

# Re-anchor the timeout to 1 hour from now
lifecycle = sandbox.set_lifecycle(timeout_secs=3600)
print(lifecycle.timeout_at)

# Clear the idle timeout
lifecycle = sandbox.set_lifecycle(idle_timeout_secs=DISABLED)

Filesystem persistence

Filesystem persistence keeps the contents of a sandbox's disk: installed packages, cloned repositories, build artifacts, and the files the sandbox writes. A sandbox with a preserved filesystem starts with its environment intact, with nothing to reinstall or rebuild.

Linux sandboxes are ephemeral by default. An ephemeral Linux sandbox keeps its writable disk on the host's local storage. Deleting the sandbox discards the disk, and a host failure loses the sandbox. A persistent Linux sandbox keeps its writable disk on network storage that any host in the region can attach. Stop releases compute and keeps the filesystem, and start boots the sandbox again, possibly on another host. A host failure leaves a persistent sandbox stopped instead of lost.

from daytona import Daytona

daytona = Daytona()
sandbox = daytona.v2.create("python-3.12", persistent=True)

# Write state to the filesystem
sandbox.process.run("pip install requests && echo done > /root/setup.log")

# Stop releases compute; the filesystem stays on network storage
sandbox.stop()
sandbox.wait_for_state(["stopped"], timeout=60)

# Start boots the sandbox again, possibly on another host
sandbox.start()
response = sandbox.process.run("cat /root/setup.log")
print(response.stdout)  # done

Memory persistence

Memory persistence keeps the runtime state of a sandbox: running processes, open connections, and everything loaded in memory. A sandbox with preserved memory continues from the point it was frozen, instead of starting from a clean boot.

A persistent Linux sandbox keeps its memory across pause and resume. Pause freezes the sandbox in place, and the sandbox no longer consumes CPU. Resume continues every process from the point it was frozen. A fork copies the filesystem and memory into a new, independent sandbox.

from daytona import Daytona

daytona = Daytona()
sandbox = daytona.v2.create("python-3.12", persistent=True)

# Start a process that holds state in memory
sandbox.process.start("python3 -m http.server 8000")

# Pause freezes the sandbox with its filesystem and memory
sandbox.pause()

# Resume continues every process from the point it was frozen
sandbox.resume()
response = sandbox.process.run("curl -s -o /dev/null -w '%{http_code}' http://localhost:8000")
print(response.stdout)  # 200: the server is still running

Memory snapshot

A memory snapshot saves the memory and disk of a running Linux sandbox under a name. A sandbox restored from the snapshot resumes the captured processes and memory instead of booting. The restored sandbox gets the CPU, memory, and disk of the source sandbox. Deleting the source sandbox does not delete its snapshots.

The capture runs in the background: the snapshot starts as pending and becomes ready when the capture finishes. A snapshot restores only in the region of its source sandbox, on the host that captured it, and the restore fails while that host is unavailable.

from daytona import Daytona

daytona = Daytona()
sandbox = daytona.v2.create("python-3.12", persistent=True)

# Capture the memory and disk of the running sandbox
snapshot = sandbox.create_snapshot("my-snapshot")

# Block until the capture is ready
snapshot = daytona.v2.snapshots.get(snapshot.id, wait="ready", timeout=60)

# Resume the captured processes and memory in a new sandbox
restored = daytona.v2.create_from_snapshot("my-snapshot")

Filesystem snapshot

A filesystem snapshot saves the filesystem of a running Linux sandbox as an image. The sandbox keeps running, and new sandboxes boot from the image with the captured files. Unlike a memory snapshot, a filesystem snapshot holds no processes or memory. Ephemeral and persistent Linux sandboxes can both be captured.

The capture runs in the background: the image starts as pending and becomes ready when the capture finishes. A named image is permanent until you delete it. An unnamed image is anonymous. Daytona deletes an anonymous image after its idle window passes without a sandbox create from it. The idle window is the server maximum of 7 days by default.

from daytona import Daytona

daytona = Daytona()
sandbox = daytona.v2.create("python-3.12")
sandbox.process.run("pip install requests")

# Capture the filesystem; the sandbox keeps running
image = sandbox.snapshot_filesystem(name="my-env")

# Wait until the capture is ready, then boot new sandboxes from it
while image.status not in ("ready", "failed"):
    image = daytona.v2.images.get(image.id, wait="ready")
if image.status == "failed":
    raise RuntimeError(image.error)
clone = daytona.v2.create("my-env")

Spot

Linux sandboxes run on reserved capacity by default. A spot Linux sandbox runs on discounted capacity that Daytona can reclaim at any time to free resources for full-price sandboxes. Spot multiplies the CPU, memory, and disk price by 0.7. Apart from price and reclaim, a spot Linux sandbox supports the same images, resources, volumes, and lifecycle operations as any other Linux sandbox.

A reclaim is immediate, with no advance notice and no grace period. The outcome depends on whether the sandbox is persistent:

Daytona does not bring a reclaimed sandbox back on its own. A reclaimed sandbox carries the reclaim time in spot_evicted_at until it is started or resumed. To continue, resume a paused sandbox or start a stopped one. The sandbox stays spot and can be reclaimed again.

from daytona import Daytona

daytona = Daytona()

# A persistent spot sandbox is paused on reclaim instead of deleted
sandbox = daytona.v2.create("python-3.12", spot=True, persistent=True)

# spot_evicted_at is None unless Daytona reclaimed the sandbox
sandbox = daytona.v2.get(sandbox.id)
if sandbox.spot_evicted_at:
    # Start resumes a paused sandbox or starts a stopped one
    sandbox.start()