Skip to content

Linux Sandboxes

View as Markdown

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.

TermDescription
SandboxAn isolated Linux machine created on demand to run code.
HostThe physical server that runs many sandboxes at once. Daytona calls these servers runners.
GuestThe operating system running inside a sandbox, as opposed to the operating system of the host.
KernelThe core of an operating system. It manages memory, processes, files, and devices.
HypervisorSoftware on the host that creates virtual machines and keeps them separated from each other and from the host.
ImageA packaged filesystem, such as python:3.12-slim, that defines what software a sandbox starts with.
SnapshotA saved copy of a sandbox’s memory and disk that new sandboxes resume from.

Use cases

Section titled “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

Section titled “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()

The following example sets the remaining parameters:

from daytona import Daytona
from daytona.v2 import PortMapping


daytona = Daytona()


sandbox = daytona.v2.create(
    name="my-sandbox",
    labels={"team": "research", "run": "42"},
    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,
    region="us",
    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,
)
ParameterTypeDescription
imagestrSets the registered image that the sandbox starts from, by name or img_ ID. This is the first positional argument. If omitted, the sandbox boots the platform default image.
namestrSets the display name. If omitted, a name is generated. Within one workload cell, a create with the same name and different arguments is refused until the first sandbox is deleted.
labelsDict[str, str]Attaches key-value metadata to the sandbox.
cpufloatSets the guaranteed CPU cores as a float. The value is raised to at least one core per 4 GiB of guaranteed memory. The default is 0.125.
memoryintSets the guaranteed memory in GiB. The default is 1 GiB.
diskintSets the guaranteed writable disk in GiB. The default is 512 MiB.
resourcesResourcesSets CPU, memory, and disk in one object, in place of cpu, memory, and disk. It also carries cpu_max, the vCPU limit, which defaults to 16, and memory_max, the memory limit in GiB, which defaults to 32.
portsSequence[PortMapping]Forwards inbound ports to the sandbox. Each mapping has a port and a proto, which defaults to tcp.
envDict[str, str]Sets environment variables inside the sandbox.
secretsSequence[str]Attaches project secrets by name. The sandbox sees each secret as an opaque placeholder.
network_policyNetworkPolicyInputSets the outbound network policy with block_all, allow_domains, and allow_cidrs. You can change it after create.
spotboolRuns the sandbox on discounted capacity that can be reclaimed. The default is False.
regionstrSets the region or global region slug. The default is the project default.
cpu_archstrSets the CPU architecture, amd64 or arm64. The default is amd64.
cpu_typestrSets the CPU hardware tier slug: zen3, zen4, zen5, zen5c, arrowlake1, arrowlake2, graviton, graviton3, and graviton4. The slug also sets the architecture. See CPU types.
lifecycle_policyLifecyclePolicyConfigSets the lifecycle policy with timeout_seconds and on_timeout, and idle_expiry_seconds and on_idle_timeout. The action is delete. By default, there is no idle timeout, and the wall-clock timeout uses the project or platform default, if one is enabled.
idempotency_keystrMakes a retried create in the same workload cell return the same sandbox. A create in another cell makes a separate sandbox. To keep creates in one region, set region. If name is set, the key is derived from it. Otherwise, each call generates a new key.
wait_secondsintSets how many seconds create waits for the sandbox to start. The server holds the request for up to 3 seconds, and the SDK waits for the rest. 0 returns immediately. The default is 60. If the sandbox has not started in time, or fails, create() returns it without raising. Check sandbox.state before using it.

CPU types

Section titled “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.

Terminal window
# List CPU types
daytona cpu-type list


# Check CPU type availability in a region
daytona cpu-type list --region us-west-1
FlagTypeDescription
--regionstringSets one region slug. Without it, the command lists CPU types without availability. With it, the table output adds an AVAILABLE column. The column shows exact if a runner in the region provides the type, fallback if a higher tier of the same architecture serves it, and - otherwise.

Lifecycle

Section titled “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 lost, and its local filesystem and memory are gone.

Sandbox states
StateDescription
queuedThe create request is recorded and waits to be published for placement.
pendingThe create request is accepted and the sandbox is queued for placement.
assignedThe sandbox is placed on a host.
bootingThe microVM is booting and will be ready to use.
runningThe sandbox is running and ready to accept requests.
deletingThe sandbox is being deleted.
deletedThe sandbox and its storage are removed.
failedThe sandbox could not boot or hit an unrecoverable error.
lostThe host running the sandbox was lost.
State transitions
Initial stateTarget stateTrigger
queuedpendingThe create request is published for placement.
pendingassignedThe sandbox is placed on a host.
assignedbootingThe host prepares the sandbox image and the microVM boots.
bootingrunningThe sandbox finishes booting and accepts requests.
any statedeletingA delete is requested, or the platform reclaims a spot sandbox.
deletingdeletedThe sandbox is removed and its resources are released.
any active statefailedThe sandbox fails to boot or hits an unrecoverable error.
runninglostThe host running the sandbox is lost.

Wait for state

Section titled “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 in one of the listed states
sandbox.wait_for_state(["started"], timeout=60)
ParameterTypeDescription
untilstrSets the one state that wait() waits for. wait_for_state() takes a list and returns on any of its states. The default is "started".
timeoutfloatSets the wait limit in seconds. None or 0 waits without a limit. When the timeout elapses, both methods raise RequestTimeoutError. The default is 60 for wait() and None for wait_for_state().
  • wait() and wait_for_state() raise SandboxTerminalStateError when the sandbox reaches destroying, destroyed, or error before a target state.
  • Pass terminal_states to wait_for_state() to change the set of terminal states.

Delete

Section titled “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. 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 copy the files to storage outside the sandbox.

from daytona import Daytona


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


sandbox.delete()

Timeouts

Section titled “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.

TimerPurposeFires afterDefault
TimeoutCap how long a sandbox livesThe interval has passed since the sandbox was created, active or notProject or platform default
Idle timeoutDelete a sandbox that is not in useThe sandbox has had no activity for the intervalProject default, or off

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

Timeout

Section titled “Timeout”

The timeout is a wall-clock budget. It starts when the sandbox is created. Activity does not extend it. A delete timeout fires in any state. 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

Section titled “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. The action fires within about 2 minutes after the interval elapses.

Auto-delete
Section titled “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
Section titled “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_policy={"idle_expiry_seconds": 3600, "on_idle_timeout": "delete"},
)


lifecycle = sandbox.reset_idle_timer()
print(lifecycle.idle_timeout_at)
  • reset_idle_timer() updates sandbox.lifecycle_policy.
  • idle_timeout_at is None when no idle timeout is set.
  • When the idle timeout action is delete, the API key also needs the delete:sandboxes permission.

Update lifecycle policy

Section titled “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()


# 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)

Memory snapshot

Section titled “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")


# 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")
ParameterTypeDescription
namestrSets the snapshot name, 1 to 128 characters of letters, digits, ., _, and -. Snapshots and images in the project share one name space. A name in use fails with 409. This parameter is required.
snapshotstrSets the snapshot that create_from_snapshot() restores from, by name or by ID, snap_.... This parameter is required.
  • The source sandbox must be running and served from a warm template.
  • The snapshot kind is full: memory and disk.
  • A restored sandbox is never spot.
  • See snapshots for the restore options and for listing and deleting snapshots.

Filesystem snapshot

Section titled “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 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")
ParameterTypeDescription
namestrSets the image name, which must be unique in the project. The default is None, which makes the image anonymous.
idleintSets how many seconds an anonymous image can go without a sandbox create before deletion. It applies only to anonymous images. -1 sets the maximum. The default is the server maximum.
  • snapshot_filesystem and snapshotFilesystem return the pending image and do not wait for the capture. daytona image capture waits unless you pass --no-wait.
  • The API call requires the write:images permission.
  • See capture images for promoting and deleting captured images.

Spot

Section titled “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, and lifecycle operations as any other Linux sandbox.

A reclaim is immediate, with no advance notice and no grace period. The sandbox moves to deleting, then deleted. Only data stored outside the sandbox remains.

from daytona import Daytona


daytona = Daytona()
sandbox = daytona.v2.create("python-3.12", spot=True)
ParameterTypeDescription
spotboolPlaces the sandbox on discounted, reclaimable capacity. The default is False.
  • Set spot when you create the sandbox. You cannot change it on an existing sandbox.
  • See preemption for the reclaim policy.