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

Persistent

A persistent Linux sandbox keeps its disk on network storage instead of on its host, so it can shut down and boot again on another host in its region. A stopped sandbox keeps its filesystem, and its processes end. A paused sandbox also keeps its memory, and resumes with its processes where they left off. A stopped sandbox is archived after an interval: its disk moves to object storage, and the next start restores it first. See lifecycle for stop, start, pause, resume, fork, and archive.

curl 'https://api.daytona.com/sandboxes' \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data '{"persistent": true}'

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 sandbox moves to deleting, then deleted. Only data on a volume or in other storage outside the sandbox remains.

from daytona import Daytona

daytona = Daytona()
sandbox = daytona.v2.create("python-3.12", 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. 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

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

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

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 until it is deleted. A persistent Linux sandbox also keeps its filesystem across stop and start, pause and resume, and archive. Filesystem snapshots keep the filesystem beyond the sandbox, and new sandboxes boot from them.

from daytona import Daytona

daytona = Daytona()
sandbox = daytona.v2.get("{sandboxId}")

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

# Stop ends the processes and keeps the filesystem
sandbox.stop()
sandbox.wait(until="stopped")

# Start boots the sandbox from its filesystem
sandbox.start()
print(sandbox.fs.read_text("setup.log"))  # 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.

A Linux sandbox keeps its memory while it runs. A persistent Linux sandbox also keeps its memory across pause and resume and forks. Memory snapshots keep memory beyond the sandbox. Memory is cleared on every stop.

from daytona import Daytona

daytona = Daytona()
sandbox = daytona.v2.get("{sandboxId}")

# Start a server that runs in the background
sandbox.process.start("python3 -m http.server 8000")

# Pause saves the memory and processes
sandbox.pause()
sandbox.wait(until="paused")

# Resume continues the server from the point where the sandbox paused
sandbox.resume()

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. A persistent Linux sandbox also supports stop / start, pause / resume, fork, and archive.

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_for_state(["started"], timeout=60)

Stop / start

Stop a persistent Linux sandbox to shut down its virtual machine and keep its disk. Processes do not survive a stop. Start boots the sandbox from the same disk, and restores an archived disk first.

from daytona import Daytona

daytona = Daytona()
sandbox = daytona.v2.get("{sandboxId}")

# Shut down the virtual machine and keep the disk
sandbox.stop()
sandbox.wait(until="stopped")

# Boot from the same disk and wait until the sandbox is started
sandbox.start(timeout=120)

# Stop a sandbox by ID, without fetching it first
daytona.v2.stop("{sandboxId}")

# Start a stopped sandbox by ID
daytona.v2.start("{sandboxId}", timeout=120)

Pause / resume

Pause a running persistent Linux sandbox to save its memory and processes and shut down its virtual machine. Resume continues the sandbox from the saved memory, with its processes running. A sandbox with attached volumes cannot be paused.

from daytona import Daytona

daytona = Daytona()
sandbox = daytona.v2.get("{sandboxId}")

# Save the memory and processes, then shut down the virtual machine
sandbox.pause()
sandbox.wait(until="paused")

# Continue from the saved memory and wait until the sandbox is started
sandbox.resume(timeout=120)

# Pause a sandbox by ID, without fetching it first
daytona.v2.pause("{sandboxId}")

# Resume a paused sandbox by ID
daytona.v2.resume("{sandboxId}", timeout=120)

Fork

Fork a persistent Linux sandbox to copy it into a new, independent sandbox in the same region. By default, a fork copies the memory and the disk, and continues the running processes of the source. A disk-only fork clones the disk, and the new sandbox boots fresh. A fork of a stopped sandbox is always disk-only.

Only a fork of a running sandbox starts by itself. A memory fork of a paused sandbox stays paused, and a disk-only fork of a paused or stopped sandbox stays stopped. Resume or start these forks to run them.

from daytona import Daytona

daytona = Daytona()
sandbox = daytona.v2.get("{sandboxId}")

# Copy the memory and disk, and wait until the fork settles
fork = sandbox.fork(name="my-sandbox-fork", timeout=120)

# Copy only the disk; the fork boots fresh
disk_fork = sandbox.fork(memory=False)

Archive

Archive a stopped persistent Linux sandbox to move its disk to object storage. A stopped sandbox is archived automatically when its archive interval elapses, and archive moves it at once. The next start restores the disk before the sandbox boots. Archiving is not available in every region, and a sandbox with attached volumes is not archived.

from daytona import Daytona

daytona = Daytona()
sandbox = daytona.v2.get("{sandboxId}")

# Archive needs a stopped sandbox
sandbox.stop()
sandbox.wait(until="stopped")

# Move the disk to object storage now
sandbox.archive()

# Archive a stopped sandbox by ID, without fetching it first
daytona.v2.archive("{sandboxId}")

# Archive the sandbox 1 hour after it stops
sandbox.update_lifecycle_policy(archive_interval_seconds=3600)

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 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, or stops or pauses a persistent one. 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. A persistent sandbox can also stop or pause. 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 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, or to pause for a persistent sandbox.

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

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

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)