Sandboxes

A sandbox is a hardware-isolated virtual machine with its own kernel, filesystem, network stack, and allocated vCPU, RAM, and disk. Sandboxes are ephemeral by default, support persistence, with isolation enforced by the hypervisor.

Sandboxes run as Linux (default), Windows, macOS, or GPU-accelerated virtual machines. Every sandbox moves through a lifecycle and can have several different states. While the sandbox is running, it exposes a toolbox for code, command, and process execution, sessions, filesystem and git operations, computer use, language server protocol support, and log streaming.

Use sandboxes to run code written by an agent, build and test software, train or serve a model on a dedicated GPU, drive desktop through screenshots and input events, or spin up thousands of identical environments for autonomous, evaluation, and reinforcement learning workflows.

Create sandboxes

Daytona provides methods to create sandboxes from the dashboard or programmatically.

1. Go to Daytona Sandboxes ↗
2. Click Create
3. Select Linux sandbox, Windows sandbox, GPU sandbox, or macOS sandbox
4. Click Create

from daytona import Daytona

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

Linux sandboxes

Linux sandboxes are Firecracker microVMs that run their own Linux kernel, and they are the default sandbox type. A Linux sandbox boots from an image that you import from a container registry, build from a Dockerfile, or capture from another sandbox. It can also start from a snapshot of another Linux sandbox. Each sandbox runs on an amd64 or arm64 CPU.

from daytona import Daytona

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

Windows sandboxes

Windows sandboxes are virtual machines running Windows Server 2022. A Windows sandbox starts from a prepared Windows base image, or from a snapshot of another Windows sandbox. Commands run in PowerShell, and the desktop is reached over the remote desktop protocol.

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

macOS sandboxes

macOS sandboxes are virtual machines running macOS on Apple silicon Mac computers. A macOS sandbox starts from a macOS base image and gets half of the Mac's cores and memory.

from daytona import Daytona

daytona = Daytona()
sandbox = daytona.v2.create_macos("base-macos")

GPU sandboxes

GPU sandboxes have one or more dedicated NVIDIA or AMD GPUs attached for workloads that require GPU acceleration, model inference, training, fine-tuning, and reinforcement learning. A GPU sandbox is ephemeral and can be saved as a checkpoint that includes its processes, memory, and GPU memory, and resumed in a new GPU sandbox.

• NVIDIA H100
• NVIDIA H200
• NVIDIA B200
• NVIDIA B300
• NVIDIA RTX Pro 6000
• NVIDIA RTX 4090
• NVIDIA RTX 5090
• AMD Instinct MI355X

curl 'https://api.daytona.com/sandboxes/gpu' \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data '{"image": "pytorch", "gpu_host": 1}'

Resources

Sandboxes have 0.125 vCPU, 1024MiB memory, and 512MiB disk by default. A sandbox may guarantee at most 16 vCPUs, 32GiB memory, and 256GiB disk.

from daytona import Daytona
from daytona.v2 import Resources

daytona = Daytona()
sandbox = daytona.v2.create(
    # memory and disk are GiB: 4 maps to mem_mib=4096, 20 to scratch_mib=20480
    resources=Resources(cpu=2, memory=4, disk=20),
)

Hardware virtualization

Server processors include instructions for running virtual machines directly on the hardware. A virtual machine monitor uses these instructions to create a guest with its own virtual processors, memory, and devices. The processor rejects any access from a guest to host memory or to another guest's memory. Linux, Windows, and macOS sandboxes run as virtual machines, each on the virtual machine monitor that its operating system needs.

Linux exposes the processor's virtualization through the Kernel-based Virtual Machine (KVM). Linux sandboxes run on Firecracker, a virtual machine monitor built to run many small, short-lived virtual machines on one host. Firecracker provides only the devices a server needs: virtual disks, a network card, and a serial console. Each Linux sandbox runs as one Firecracker process on a host, in its own network namespace, with its own virtual processors and memory.

Windows sandboxes also use KVM, but Firecracker does not support Windows guests. Windows sandboxes run on Cloud Hypervisor, a virtual machine monitor that also keeps its device model small but can start an operating system from firmware. Each Windows sandbox runs as one Cloud Hypervisor process on a host, in its own network namespace, with its own virtual processors and memory. Cloud Hypervisor provides each Windows sandbox with the following:

• UEFI firmware, which loads the Windows boot manager from the sandbox's disk
• Hyper-V enlightenments: interfaces Windows uses to run efficiently as a guest
• Virtual disks and a virtual network card, for which the base image carries Windows drivers
• A serial console for management, and no graphics card

macOS sandboxes run on Macs, because Apple's license allows macOS virtual machines only on Apple hardware. Apple silicon includes hardware support for virtual machines, which macOS exposes through Apple's Virtualization framework. Each macOS sandbox runs as its own virtual machine on its Mac, with its own virtual processors, memory, disk, and network card.

Lifecycle

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

See the lifecycle of Linux, Windows, GPU, and macOS sandboxes.

Operations

Daytona provides methods to manage existing sandboxes. Sandbox operations find sandboxes, read their current state and configuration, and update their metadata. They do not change the state of a sandbox or touch anything running inside it. To stop, pause, fork, or delete a sandbox, see lifecycle. To run commands or work with files inside a sandbox, use the toolbox.

List sandboxes

List sandboxes in the project, page by page. Unfiltered lists read the region-local database, so new sandboxes appear at once. To filter by name, state, labels, or resources, use search.

from daytona import Daytona

daytona = Daytona()
page = daytona.v2.list()
for sandbox in page.items:
    print(sandbox.id, sandbox.name, sandbox.state)

Iterate over all sandboxes

Iterate over every sandbox in the project without handling page cursors. The iterator fetches the next page when the current one is exhausted and stops when the server returns no cursor.

from daytona import Daytona

daytona = Daytona()
for sandbox in daytona.v2.iter():
    print(sandbox.id, sandbox.name, sandbox.state)

Search sandboxes

Search sandboxes across every region. Search reads a central index that is eventually consistent: a create, update, or delete becomes searchable about 2 to 3 seconds after it is committed, so a sandbox created a moment ago may be missing. To read your own writes, use list without filters or get. Filters combine with AND, and deleted sandboxes stay in the results until retention removes them unless you filter by state.

from daytona import Daytona

daytona = Daytona()

# Free text over name and image, or an exact sandbox id
page = daytona.v2.search(q="my-sandbox")
for sandbox in page.items:
    print(sandbox.id, sandbox.name, sandbox.state)

Get a sandbox

Get a sandbox by its ID. The response includes the current state, resources, labels, and lifecycle settings. Get reads the control plane directly, so it reflects changes immediately, unlike search.

from daytona import Daytona

daytona = Daytona()

# Fetch the sandbox from the control plane
sandbox = daytona.v2.get("{sandboxId}")
print(sandbox.state, sandbox.cpu, sandbox.memory, sandbox.disk)

Find sandboxes by name

Find sandboxes by the name they were created with. Names are not unique, so the result is a list, newest first, and it is empty when no sandbox matches. The lookup reads the control plane directly, so a sandbox created a moment ago is found, unlike with search.

The name is stored as the name label. Replacing a sandbox's labels without it removes the sandbox from name lookups.

from daytona import Daytona

daytona = Daytona()

# Reuse a named sandbox, or create it when none exists
found = daytona.v2.find_by_name("my-sandbox")
sandbox = found[0] if found else daytona.v2.create(name="my-sandbox")

Create an access token

Create a short-lived access token for one sandbox. The token reaches the sandbox toolbox, SSH, desktop, and private preview ports, and can stop, pause, or delete the sandbox, limited to the operations and ports you grant. Give it to a collaborator, a CI job, or a browser instead of a project API key.

The token lasts one hour by default and at most 24 hours. It cannot be refreshed, revoked, or used to create other credentials. Create a new token when it expires.

# Grant file system and SSH access for 15 minutes
token = sandbox.create_access_token(operations=["toolbox:fs", "ssh"], ttl_secs=900)
print(token.access_token, token.expires_at)

Update labels

Update a sandbox's labels. Labels are key-value strings for organizing sandboxes, and you can filter by them when you list or search. An update replaces the full label set; omitted labels are removed. A sandbox holds at most 100 labels, each key and value at most 512 bytes.

from daytona import Daytona

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

# Replace the full label set
labels = sandbox.set_labels(labels={"team": "research"})
print(labels)

Logs

Read the serial console log of a sandbox. For a running sandbox the log is read live from its runner; for a sandbox in any other state the persisted log is returned. macOS sandboxes do not serve serial console or entrypoint logs.

# Serial console log of the microVM
daytona sandbox logs {sandboxId}

Entrypoint logs

Read the log of the sandbox entrypoint process as text. For a running sandbox the log is read live; for a sandbox in any other state the persisted log is returned. To page through the log or follow it, read the entrypoint process through the toolbox.

print(sandbox.entrypoint_logs())

Build logs

Read the output of the image build behind a sandbox. A sandbox has a build log when its image is built from a Dockerfile, including a build that failed before the sandbox was placed; a sandbox created from a registry image has none. When the sandbox reuses an image built earlier, the log is the output of that original build.

Following the log streams output while the build runs and ends when the build finishes. Stopping the reader does not stop the build. To read the log of an image without a sandbox, see image build logs.

from daytona import Daytona
from daytona.v2 import ImageBuilder

daytona = Daytona()
sandbox = daytona.v2.create_from_build(ImageBuilder.from_dockerfile("FROM python:3.12-slim"))

# Output retained so far, as text
print(sandbox.build_logs())

# Stream output until the build finishes
result = sandbox.follow_build_logs(on_logs=lambda chunk: print(chunk, end=""))
print(result.status, result.reason)