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. Once the agent is done, a delete discards the sandbox's filesystem and memory.

• Coding agents. An agent clones a repository, installs dependencies, edits files, runs the test suite, and opens a pull request, all inside one sandbox. The sandbox keeps its filesystem on its host until it is deleted. A filesystem snapshot saves that filesystem as an image, and new sandboxes boot from it with the captured files.

• 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. A restored sandbox resumes the captured processes and memory instead of booting.

• Untrusted user code. Online coding platforms, grading systems, and plugin hosts run code submitted by users without exposing other users or the service. Each sandbox is a microVM with its own Linux kernel. The hardware enforces the boundary between sandboxes.

• 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. Requests through SSH, VNC, and preview URLs count as activity for the idle timeout. A reset of the idle timer keeps the sandbox alive during work that Daytona does not count as activity.

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 PortMapping, Resources

daytona = Daytona()

sandbox = daytona.v2.create(
    name="my-sandbox",
    labels={"team": "research", "run": "42"},
    resources=Resources(cpu=2, memory=4, disk=20),
    ports=[PortMapping(port=8080), PortMapping(port=5353, proto="udp")],
    network_policy={"block_all": True, "allow_domains": ["pypi.org", "*.github.com"]},
    env={"LOG_LEVEL": "debug"},
    secrets=["GITHUB_TOKEN"],
    spot=False,
    cpu_arch="amd64",
    cpu_type="zen5",
    lifecycle_policy={
        "idle_expiry_seconds": 3600,
        "on_idle_timeout": "delete",
        "timeout_seconds": 604800,
        "on_timeout": "delete",
    },
    idempotency_key="run-42-create",
    wait_seconds=120,
)

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. An ephemeral sandbox is deleted, and only data on a volume or in other storage outside the sandbox remains. Preemption describes the reclaim policy.

from daytona import Daytona

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

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. A create with a type that no runner in the region serves, itself or as a fallback, is refused, or waits until its create deadline. 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 IDs.

# List CPU types
daytona cpu-type list

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

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.

The capture runs in the background: the image starts as pending, moves to building, 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()
sandbox.process.run("pip install requests")

# Capture the filesystem; the sandbox keeps running
image = sandbox.capture_image(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")

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, is building while the runner captures the sandbox, and becomes ready when the capture finishes. A snapshot restores on the runner that captured it, or on another runner of the region with the same CPU model and hypervisor version. It restores in another region only where Daytona has enabled cross-region restore and the source sandbox was not persistent.

from daytona import Daytona

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

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

# Wait until the capture is ready
while snapshot.status not in ("ready", "failed"):
    snapshot = daytona.v2.snapshots.get(snapshot.id, wait="ready")
if snapshot.status == "failed":
    raise RuntimeError(snapshot.error)

# Resume the captured processes and memory in a new sandbox
restored = daytona.v2.create_from_snapshot("my-snapshot", labels={"team": "research"})

Filesystem persistence

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

A Linux sandbox keeps its filesystem on its host until it is deleted. Deleting the sandbox or losing its host discards the filesystem. Filesystem snapshots keep the filesystem beyond the sandbox, and new sandboxes boot from them.

Memory persistence

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

A Linux sandbox keeps its memory only while it runs. Memory snapshots keep memory and processes beyond the sandbox.

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. A Linux sandbox keeps its filesystem and memory until it is deleted, or until its host fails: the sandbox then moves to error (lost in the CLI and API), and its local filesystem and memory are gone.

The following tables list the states of a Linux sandbox and the transitions between them. The SDKs report the states in the State column. The CLI and API report the more detailed status in the API status column.

A sandbox can transition between states in response to various actions. The following table lists the initial state, target state, and trigger for the transition.

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 error or destroyed. The SDKs use the states in the sandbox states table, so the SDK started state corresponds to the running status 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 in one of the listed states
sandbox.wait(until=["starting", "started"], timeout=60)

Delete

Delete a Linux sandbox to tear down its virtual machine. Deletion works in any state. The API returns once teardown starts, and the SDKs and the CLI wait until the sandbox is deleted. The sandbox moves from deleting to deleted when the teardown finishes. Deleting a sandbox discards its filesystem and memory. Images and snapshots captured from the sandbox remain.

To keep files from a sandbox, take a filesystem snapshot or write the files to a volume or other storage outside the sandbox.

from daytona import Daytona

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

sandbox.delete()

# Delete by sandbox ID, without fetching the sandbox first
daytona.v2.delete("{sandboxId}")

Timeouts

Daytona 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 policy, and change them later through update lifecycle policy.

The action for both timers is delete. Auto-delete is not a separate setting. It is the idle timeout with the delete action.

Timeout

The timeout is a wall-clock budget. It starts when the sandbox starts running. Activity does not extend it. A delete timeout fires in any state, except while the sandbox is still being created: a sandbox that does not reach running is deleted at its create deadline. 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 delete.

from daytona import Daytona

daytona = Daytona()
sandbox = daytona.v2.create(
    # Delete the sandbox 2 hours after it is created
    lifecycle_policy={"timeout_seconds": 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, the sandbox being created or starting to run, and a reset of the idle timer. A change to the lifecycle policy does not count as activity. The idle timeout is off by default unless the project sets one, has a minimum of 60 seconds, and requires an action. The API raises a smaller value to 60 seconds, and the CLI refuses it. The action fires within about 2 minutes after the interval elapses.

Auto-delete

Delete a Linux sandbox after a period of inactivity.

from daytona import Daytona

daytona = Daytona()
sandbox = daytona.v2.create(
    lifecycle_policy={"idle_expiry_seconds": 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 whether or not an idle timeout is set, in any state except deleting and deleted. 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_policy={"idle_expiry_seconds": 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. A deleting or deleted sandbox cannot be updated.

from daytona import Daytona
from daytona.v2 import DISABLED

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

# Delete the sandbox after 30 minutes without activity; omitted fields keep their current value
lifecycle = sandbox.update_lifecycle_policy(idle_expiry_seconds=1800, on_idle_timeout="delete")
print(lifecycle.idle_expiry_seconds, lifecycle.on_idle_timeout)

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

# Clear the idle timeout
lifecycle = sandbox.update_lifecycle_policy(idle_expiry_seconds=DISABLED)

Permissions

Linux sandboxes use the sandbox permissions of their project, and snapshots use the image and snapshot permissions. You can grant each to an organization role or an API key.

Setting, changing, or clearing a delete action in a lifecycle policy, and resetting the idle timer of a sandbox whose idle action is delete, also require the permission to delete sandboxes. The audit logs record sandbox creates, lifecycle changes, deletes, and snapshots.