Skip to main content

​
Overview

Sandboxes are the core primitive in Daytona - isolated, containerized execution environments where AI-generated code runs securely. Each sandbox provides a complete development environment with its own filesystem, process space, and network isolation.

​
What is a Sandbox?

A Daytona Sandbox is a lightweight, isolated container instance that provides:
  • Complete Isolation: Separate filesystem, process space, and network namespace
  • Resource Allocation: Configurable CPU, memory, GPU, and disk quotas
  • Persistent State: Sandboxes can be stopped and restarted without losing data
  • Network Control: Granular network access policies and egress filtering
  • OCI Compatibility: Built on any OCI/Docker image
Sandboxes are designed for sub-90ms creation time, enabling rapid iteration and massive parallelization for AI workflows.

​
Sandbox Lifecycle

Sandboxes transition through various states during their lifecycle:

​
Sandbox States

StateDescription
creatingSandbox is being initialized
pending_buildWaiting for snapshot build to begin
building_snapshotBuilding snapshot from source
pulling_snapshotPulling snapshot image from registry
startedSandbox is running and ready
stoppedSandbox is stopped but preserved
startingSandbox is being started
stoppingSandbox is being stopped
archivedSandbox is archived to storage
restoringSandbox is being restored from archive
resizingSandbox resources are being adjusted
destroyingSandbox is being deleted
destroyedSandbox has been removed
errorSandbox encountered an error
build_failedSnapshot build failed
unknownSandbox state is unknown

​
Sandbox Configuration

​
Resource Allocation

Sandboxes support configurable resource quotas: 
from daytona import Daytona, DaytonaConfig, CreateSandboxParams

daytona = Daytona(DaytonaConfig(api_key="YOUR_API_KEY"))

sandbox = daytona.create(CreateSandboxParams(
    language="python",
    cpu=2.0,      # 2 CPU cores
    memory=4.0,   # 4 GB RAM
    gpu=1.0,      # 1 GPU
    disk=10.0     # 10 GB disk
))

# Create with custom resources
sandbox = daytona.create(CreateSandboxParams(
    language="python",
    cpu=4.0,
    memory=8.0
))

​
Network Configuration

Control network access with fine-grained policies:
  • Network Block All: Completely isolate the sandbox from external networks
  • Network Allow List: Specify CIDR ranges for allowed network access
  • Public HTTP Preview: Enable public access to sandbox HTTP ports
# Create sandbox with restricted network
sandbox = daytona.create(CreateSandboxParams(
    language="python",
    network_block_all=True,
    network_allow_list="10.0.0.0/8,172.16.0.0/12"
))
By default, sandboxes have network access. Use network_block_all=True for maximum isolation when running untrusted code.

​
Environment Variables

Pass configuration and secrets via environment variables: 
sandbox = daytona.create(CreateSandboxParams(
    language="python",
    env={
        "DATABASE_URL": "postgresql://...",
        "API_KEY": "secret-key"
    }
))

​
Labels

Organize sandboxes with custom labels: 
sandbox = daytona.create(CreateSandboxParams(
    language="python",
    labels={
        "project": "ml-training",
        "team": "data-science",
        "environment": "production"
    }
))

​
Sandbox Automation

​
Auto-Stop

Automatically stop sandboxes after a period of inactivity: 
sandbox = daytona.create(CreateSandboxParams(
    language="python",
    auto_stop_interval=30  # Stop after 30 minutes of inactivity
))

​
Auto-Archive

Archive stopped sandboxes to reduce costs: 
sandbox = daytona.create(CreateSandboxParams(
    language="python",
    auto_archive_interval=60  # Archive after 60 minutes
))

​
Auto-Delete

Automatically clean up sandboxes: 
sandbox = daytona.create(CreateSandboxParams(
    language="python",
    auto_delete_interval=120  # Delete after 120 minutes
))
Set auto_delete_interval=0 to delete immediately upon stopping. Use -1 to disable auto-deletion.

​
Sandbox Operations

​
Starting and Stopping

# Stop a running sandbox
sandbox.stop()

# Start a stopped sandbox
sandbox.start()

# Restart a sandbox
sandbox.restart()

​
Resizing

Dynamically adjust sandbox resources: 
# Resize sandbox resources
sandbox.resize(
    cpu=4.0,
    memory=8.0
)

​
Deletion

# Delete a sandbox
daytona.delete(sandbox)

​
Use Cases

​
AI Code Execution

Run AI-generated code in isolated environments: 
# Create sandbox for AI-generated code
sandbox = daytona.create(CreateSandboxParams(
    language="python",
    network_block_all=True  # Isolate from network
))

# Execute AI-generated code safely
response = sandbox.process.code_run(ai_generated_code)
print(response.result)

# Clean up
daytona.delete(sandbox)

​
Development Environments

Create on-demand development workspaces: 
# Create development environment
sandbox = daytona.create(CreateSandboxParams(
    language="python",
    snapshot="my-dev-snapshot",
    volumes=[{
        "volume_id": "project-data",
        "mount_path": "/workspace"
    }]
))

​
Testing and CI/CD

Run tests in isolated, reproducible environments: 
# Create test environment
sandbox = daytona.create(CreateSandboxParams(
    language="python",
    snapshot="test-environment",
    auto_delete_interval=0  # Delete immediately after tests
))

# Run tests
test_result = sandbox.process.code_run("pytest tests/")

# Cleanup happens automatically

​
Agent Workspaces

Provide persistent workspaces for AI agents: 
# Create agent workspace
agent_sandbox = daytona.create(CreateSandboxParams(
    language="python",
    name="agent-workspace",
    labels={"agent": "code-assistant"},
    auto_stop_interval=60
))

# Agent executes commands
result = agent_sandbox.process.execute_command("git clone ...")

​
Best Practices

  1. Resource Allocation: Start with conservative resource quotas and scale up as needed
  2. Network Isolation: Always use network_block_all=True when running untrusted code
  3. Cleanup: Use auto-delete intervals to prevent resource waste
  4. Snapshots: Create snapshots of configured environments for faster startup
  5. Labels: Tag sandboxes with metadata for organization and cost tracking
  6. Volumes: Use volumes for persistent data that should survive sandbox deletion

​
Next Steps

Snapshots

Learn about creating and managing snapshots

Volumes

Understand persistent storage with volumes

Architecture

Explore Daytona’s system architecture

Security

Learn about isolation and security

Build docs developers (and LLMs) love

Get started for freeTalk to us