daytona

What is Daytona

Daytona provides full composable computers — sandboxes — for AI agents. Each sandbox is an isolated runtime environment with its own kernel, filesystem, network stack, and dedicated vCPU, RAM, and disk. Agents can install packages, run servers, compile code, and manage processes inside sandboxes.

Sandboxes are built from OCI-compliant images or snapshots. Any language or tool that runs on Linux works.

Scope: This skill covers Daytona Cloud (app.daytona.io). For self-hosted Daytona OSS deployment, see ./references/platform/oss-deployment.md.

Before You Start

Before writing any Daytona code, verify setup:

1. SDK installed? Check that the Daytona SDK is installed for the user's language (e.g. pip show daytona or check package.json for @daytonaio/sdk). If not, install it.
2. API key set? Check DAYTONA_API_KEY in the shell environment or in environment files. If not set, tell the user they need an API key and point them to Daytona Dashboard > API Keys to create one.

SDK Essentials — Python

Installation

pip install daytona

Create client and sandbox

from daytona import Daytona

# Uses DAYTONA_API_KEY env var
daytona = Daytona()

# Create a sandbox with defaults (1 vCPU, 1GB RAM, 3GB disk)
sandbox = daytona.create()

from daytona import Daytona, CreateSandboxFromImageParams, Image, Resources

daytona = Daytona()

# Create with a custom image, name, and resources
sandbox = daytona.create(CreateSandboxFromImageParams(
    image=Image.debian_slim("3.12"),
    name="my-sandbox",
    resources=Resources(cpu=2, memory=4, disk=8),
))

Execute commands

Both exec and code_run return an ExecuteResponse with .result (stdout) and .exit_code. code_run executes in the sandbox's language runtime (set at creation via language= param, defaults to "python"). Supported: python, typescript, javascript.

# Run a shell command
response = sandbox.process.exec("echo 'Hello, World!'")
print(response.result)     # "Hello, World!"
print(response.exit_code)  # 0

# Run Python code (stateless)
response = sandbox.process.code_run('''
import json
data = {"key": "value"}
print(json.dumps(data, indent=2))
''')
print(response.result)
print(response.exit_code)  # 0 on success, non-zero on error

File operations

# Write a file
sandbox.fs.upload_file(b"Hello, Daytona!", "/home/daytona/data.txt")

# Read a file
content = sandbox.fs.download_file("/home/daytona/data.txt")
print(content.decode())

# List files
files = sandbox.fs.list_files("workspace")
for f in files:
    print(f"{f.name} ({'dir' if f.is_dir else f.size})")

Sandbox lifecycle

# Pause and resume later
sandbox.stop()          # frees CPU/RAM, keeps disk
sandbox.start()         # ready to use again

# Long-term storage (must be stopped first)
sandbox.stop()
sandbox.archive()       # cold storage, no quota impact

# Resume a previous sandbox by ID or name
sandbox = daytona.get("sandbox-id-or-name")
sandbox.start()

# Permanently remove
sandbox.delete()

Wrap Daytona calls with DaytonaError for error handling. For async, use AsyncDaytona (async context manager). For full Python SDK reference, see python-sdk/README.md.

SDK Essentials — TypeScript

The TypeScript SDK (@daytonaio/sdk) mirrors the Python API. Key differences: executeCommand instead of exec, codeRun instead of code_run, uploadFile/downloadFile/listFiles for file ops, DaytonaError for error handling. Install with npm install @daytonaio/sdk.

For full TypeScript SDK reference and examples, see typescript-sdk/README.md.

Common Patterns

Custom environments and snapshots

When the user needs specific packages, tools, or a custom OS in their sandbox, define a custom image with the Image builder. If the user will create multiple sandboxes with the same setup, offer to build a snapshot — snapshots bake dependencies into a reusable template so subsequent sandboxes start quickly with everything pre-installed.

Note: Snapshots are built from image definitions, not from live sandbox state. You cannot snapshot a running sandbox to capture its current filesystem.

Define images with the Image builder:

from daytona import Image

# Debian with Python packages
image = Image.debian_slim("3.12").pip_install(["pandas", "numpy", "scikit-learn"])

# With system packages and shell commands
image = (Image.debian_slim("3.12")
    .run_commands("apt-get update && apt-get install -y curl git",
                   "curl -fsSL https://deb.nodesource.com/setup_20.x | bash -")
    .pip_install(["flask"])
    .env({"APP_ENV": "production"}))

# From a Dockerfile
image = Image.from_dockerfile("./Dockerfile")

# From a registry image directly
image = Image.base("node:20-slim")

import { Image } from '@daytonaio/sdk'

const image = Image.debianSlim('3.12').pipInstall(['pandas', 'numpy', 'scikit-learn'])

const image = Image.debianSlim('3.12')
    .runCommands('apt-get update && apt-get install -y curl git',
                 'curl -fsSL https://deb.nodesource.com/setup_20.x | bash -')
    .pipInstall(['flask'])
    .env({ APP_ENV: 'production' })

const image = Image.fromDockerfile('./Dockerfile')

const image = Image.base('node:20-slim')

Create a one-off sandbox directly from an image:

from daytona import Daytona, CreateSandboxFromImageParams, Image

daytona = Daytona()
image = Image.debian_slim("3.12").pip_install(["flask"])
sandbox = daytona.create(CreateSandboxFromImageParams(image=image))

const sandbox = await daytona.create({ image })

Or build a snapshot for reuse (recommended if creating multiple sandboxes with the same setup):

from daytona import Daytona, CreateSandboxFromSnapshotParams, CreateSnapshotParams, Image

daytona = Daytona()

# One-time: build a snapshot
image = Image.debian_slim("3.12").pip_install(["pandas", "numpy", "scikit-learn"])
snapshot = daytona.snapshot.create(CreateSnapshotParams(
    name="data-science",
    image=image,
))

# Every time after: fast start from snapshot
sandbox = daytona.create(CreateSandboxFromSnapshotParams(
    snapshot=snapshot.name,
))
response = sandbox.process.code_run("import pandas; print(pandas.__version__)")

const snapshot = await daytona.snapshot.create({
    name: 'data-science',
    image: Image.debianSlim('3.12').pipInstall(['pandas', 'numpy', 'scikit-learn']),
})

const sandbox = await daytona.create({ snapshot: snapshot.name })

For the full Image builder API, see ./references/<lang>-sdk/declarative-builder.md. For snapshot management, see ./references/<lang>-sdk/snapshots.md.

Long-running task pattern

from daytona import Daytona

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

# ... clone repo, install deps, etc.

# Start a test suite in the background
sandbox.process.exec("nohup pytest --tb=short > /home/daytona/test.log 2>&1 &")

# Check progress later
response = sandbox.process.exec("tail -5 /home/daytona/test.log")
print(response.result)

# Download the full report when done
report = sandbox.fs.download_file("/home/daytona/test.log")

Preview URLs

Sandboxes expose HTTP services via preview URLs. Previews are token-authenticated by default, or public if public=True (Python) / public: true (TypeScript) at sandbox creation.

• Token-authenticated — returns .url and .token (send as x-daytona-preview-token header)
  • Python: sandbox.get_preview_link(port) | TypeScript: sandbox.getPreviewLink(port) | Go: sandbox.GetPreviewLink(port) | Ruby: sandbox.get_preview_link(port)
• Signed URL (shareable) — token embedded in URL, no headers needed
  • Python: sandbox.create_signed_preview_url(port, expires_in_seconds=3600) | TypeScript: sandbox.getSignedPreviewUrl(port, 3600) | Go: sandbox.GetSignedPreviewLink(port, 3600) | Ruby: sandbox.create_signed_preview_url(port, expires_in_seconds: 3600)

For details, see ./references/<lang>-sdk/preview.md.

Sandbox Limits & Constraints

Aggregate limits (total vCPU/RAM/disk across all sandboxes) depend on your organization tier:

Resource state impact:

• Running sandboxes count against vCPU + RAM + disk
• Stopped sandboxes count only against disk
• Archived sandboxes have no quota impact (data in cold storage)

Network access restrictions

Tier 1 & Tier 2 organizations have restricted network access. Sandboxes can only reach a whitelist of essential services (package registries, Git hosts, AI APIs, CDNs, etc.). This restriction cannot be overridden at the sandbox level — even setting networkAllowList won't help if your org is Tier 1/2.

Tier 3 & Tier 4 get full unrestricted internet access by default, with optional per-sandbox firewall controls.

If your code needs to reach arbitrary URLs (external APIs, custom services, etc.), you need Tier 3+. Check your tier at Daytona Dashboard > Limits.

Essential services available on all tiers include: npm/PyPI/apt registries, GitHub/GitLab/Bitbucket, Docker registries, major AI APIs (Anthropic, OpenAI, Google AI, etc.), S3, Google Cloud Storage, and common dev tools (Vercel, Supabase, Clerk, Sentry, etc.). For the full list, see network-limits.md. Missing a service? Submit a request at daytonaio/sandbox-network-whitelist.

View your usage at Daytona Dashboard > Limits. For full details, see limits.md.

Quick Decision Tree

Replace <lang>-sdk with: python-sdk, typescript-sdk, go-sdk, or ruby-sdk.

SDK Index

Python SDK (primary)

Async versions mirror the sync API: python-sdk/async/.

TypeScript SDK

Flat structure (no sync/async split like Python): typescript-sdk/README.md. Files: daytona.md, sandbox.md, process.md, file-system.md, git.md, snapshot.md, volume.md, code-interpreter.md, computer-use.md, lsp-server.md, object-storage.md, execute-response.md, pty-handle.md, errors.md, image.md.

Go SDK & Ruby SDK

Both follow the same patterns. Go uses a compact single-file structure: go-sdk/README.md. Ruby mirrors TypeScript: ruby-sdk/README.md.

Feature Guides (per-SDK)

Each SDK folder contains the same set of feature guides with language-specific examples. To find a guide, use ./references/<lang>-sdk/<filename> (e.g., ./references/python-sdk/sandboxes.md, ./references/typescript-sdk/snapshots.md).

Platform Reference

API Reference

Raw REST API documentation for all Daytona endpoints (sandboxes, snapshots, volumes, toolbox operations, etc.): api/README.md.