Linux Sandboxes

Daytona provides Linux sandboxes as the default sandbox for AI agents. A Linux sandbox is an isolated runtime environment you manage programmatically to run code. Each sandbox has a dedicated filesystem, network stack, and allocated vCPU, RAM, and disk. Agents and developers can install packages, run servers, compile code, and manage processes.

Linux sandboxes run as containers or as Linux virtual machines (VMs). The snapshot sets the sandbox class, and both classes use the same SDKs, CLI, and API. Linux sandboxes start from a snapshot or a Docker image, keep their filesystem across stop and start, and are deleted when a timeout elapses or on request.

Use cases

Linux 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 pushes a branch, all inside one sandbox.
• Reinforcement learning (RL) and evaluation: each episode or test case gets a clean, identical machine created from a shared snapshot, so results do not depend on leftover state and each environment stays cheap.
• Untrusted user code: online coding platforms, grading systems, code interpreters, and plugin hosts run code submitted by users or generated by a model 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.
• Long-lived and branching agent sessions: a Linux VM sandbox pauses when the agent goes idle and resumes with its processes and memory intact, and is forked to try several approaches from the same point.

Create a Linux sandbox

Create a sandbox.

from daytona import Daytona

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

Create a Linux VM sandbox

Create a Linux VM sandbox.

from daytona import Daytona, CreateSandboxFromSnapshotParams

daytona = Daytona()
sandbox = daytona.create(CreateSandboxFromSnapshotParams(snapshot="daytona-vm-small"))

Nested virtualization

Daytona provides nested virtualization for Linux VM sandboxes. Nested virtualization exposes KVM (/dev/kvm) inside the guest, so the sandbox can run its own virtual machines with hardware acceleration.

from daytona import Daytona, CreateSandboxFromSnapshotParams

daytona = Daytona()
sandbox = daytona.create(
    CreateSandboxFromSnapshotParams(
        snapshot="daytona-vm-small",
        kvm=True,
    )
)

Filesystem snapshot

A filesystem snapshot, also called a cold snapshot, saves the filesystem of a stopped Linux sandbox. Both sandbox classes support filesystem snapshots. A snapshot without the include memory option is a filesystem snapshot.

from daytona import Daytona, CreateSandboxFromSnapshotParams

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

# Write a file to the filesystem
sandbox.fs.upload_file(b"done", "setup.log")

# A filesystem snapshot requires a stopped sandbox
sandbox.stop()
sandbox.create_snapshot("my-snapshot")

# A sandbox created from the snapshot starts with the same filesystem
new_sandbox = daytona.create(CreateSandboxFromSnapshotParams(snapshot="my-snapshot"))
content = new_sandbox.fs.download_file("setup.log")
print(content.decode())  # done

Memory snapshot

A memory snapshot, also called a hot snapshot, saves the filesystem and memory of a started Linux VM sandbox. A sandbox created from a memory snapshot starts with its processes already running. Container sandboxes do not support memory snapshots.

curl 'https://app.daytona.io/api/sandbox/{sandboxIdOrName}/snapshot' \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data '{
  "name": "my-vm-snapshot",
  "includeMemory": true
}'

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.

Linux sandboxes preserve their filesystem across stop and start, archive, and filesystem snapshots created from a sandbox. An ephemeral sandbox is deleted on stop, so its filesystem is not kept. The sandbox classes differ in where the preserved filesystem is stored.

from daytona import Daytona

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

# Write a file to the filesystem
sandbox.fs.upload_file(b"done", "setup.log")

# Stop clears memory and keeps the filesystem
sandbox.stop()

# Start boots the sandbox from its filesystem
sandbox.start()
content = sandbox.fs.download_file("setup.log")
print(content.decode())  # done

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.

Linux VM sandboxes preserve their memory across pause and resume, memory snapshots created from a sandbox, and forks. Memory state is cleared on every stop. The sandbox classes differ in whether memory can be preserved without keeping the sandbox running:

from daytona import Daytona, CreateSandboxFromSnapshotParams, SessionExecuteRequest

daytona = Daytona()
sandbox = daytona.create(CreateSandboxFromSnapshotParams(snapshot="daytona-vm-small"))

# Start a process that runs in the background
sandbox.process.create_session("keepalive")
response = sandbox.process.execute_session_command(
    "keepalive",
    SessionExecuteRequest(command="sleep 3600", run_async=True),
)

# Pause keeps the filesystem and memory
sandbox.pause()

# Start resumes every process from the point where the sandbox paused
sandbox.start()
command = sandbox.process.get_session_command("keepalive", response.cmd_id)
print(command.exit_code)  # None: the process is still running

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.

Wait for state

Wait until a sandbox reaches the started or stopped state.

sandbox.wait_for_sandbox_start(timeout=60)
sandbox.wait_for_sandbox_stop(timeout=60)

Stop / start

Stop a sandbox. The sandbox moves to the stopped state when shutdown completes. While a stop is in progress, the sandbox is in the stopping state and does not accept new requests.

sandbox.stop()

sandbox.start()

Pause / resume

Pause and resume a sandbox.

Fork

Fork a sandbox.

Delete

Delete a sandbox.

1. Go to Daytona Sandboxes ↗
2. Click Delete next to the sandbox you want to delete

sandbox.delete()

# Block until the sandbox is deleted
sandbox.delete(timeout=60, wait=True)

Timeouts

Daytona stops, pauses, archives, or deletes a sandbox when a timeout elapses. Each timeout is set in minutes. Zero disables auto-stop, auto-pause, and wall-clock TTL. Zero does not disable auto-archive or auto-delete: auto-archive set to zero uses the maximum interval of 30 days, and auto-delete set to zero deletes the sandbox as soon as it stops. To disable auto-delete, set it to -1.

Auto-pause

The auto-pause interval sets the amount of time after which an idle VM sandbox is automatically paused. Auto-pause applies only to VM sandboxes and is mutually exclusive with the auto-stop interval: at most one of the two intervals may be non-zero. Ephemeral sandboxes cannot have auto-pause enabled.

The interval is set in minutes:

• 0: disables the auto-pause functionality
• if neither auto-pause nor auto-stop is set, non-ephemeral sandbox classes that support pausing default to an auto-pause interval of 60 minutes with auto-stop disabled

The sandbox pauses after no new events occur for the specified interval. Events include sandbox state changes and interactions with the sandbox through the SDK. Interactions through sandbox previews do not reset the timer.

Wall-clock TTL

The wall-clock TTL (time-to-live) sets a hard upper bound on how long a sandbox may exist. Unlike the auto-delete interval, which counts time only while the sandbox is stopped, TTL runs as wall-clock time from creation (or from the moment you last set it) and destroys the sandbox in any state: started, stopped, paused, or archived.

Set ttl_minutes when creating a sandbox, or update it later. The value is in minutes:

• 0: disables the TTL
• if not set, the sandbox has no TTL deadline

Calling set_ttl after creation resets the deadline from the current moment. Use wall-clock TTL for agent sessions, CI jobs, and any sandbox that must not outlive a fixed deadline.

sandbox = daytona.create(CreateSandboxFromSnapshotParams(
    snapshot="daytona-vm-small",
    ttl_minutes=120,
))

# Reset the deadline to 60 minutes from now
sandbox.set_ttl(60)