Related Pages

Related topics: Sandboxes: Core Compute Primitive, Volumes, Snapshots & Data Persistence, Deployment, Runners & Platform Operations

Overview & System Architecture

What is Daytona?

Daytona is an open-source, secure, and elastic infrastructure platform for running AI-generated code. The project delivers fully composable virtual computers—called sandboxes—that developers and AI agents can manage programmatically. A sandbox is a short-lived or persistent compute environment with its own filesystem, process space, and language toolchain, designed to safely execute untrusted or agent-generated code at scale.

The platform is exposed through multiple first-party SDKs (TypeScript, Python, Go, Ruby, Java), a CLI with a Model Context Protocol (MCP) server, a REST API, a web dashboard, and an observability stack. The most recent release, v0.187.0, includes dashboard limits/classes tabs, Android and linked sandbox documentation, and a debug metrics server exposed by the proxy.

Community issue #100 repeatedly asks for a clearer elevator pitch. In short: Daytona gives any AI agent or developer a remote, isolated, programmable Linux box with files, processes, Git, LSP, and preview URLs—on demand. Source: libs/sdk-typescript/README.md

Core Capabilities

Each SDK exposes a uniform surface area for sandbox control. Source: libs/sdk-typescript/README.md

System Architecture

Daytona is a distributed system composed of a centralized control plane and a fleet of runners that materialize sandboxes on demand. The CLI, SDKs, and MCP server all talk to a single API; runners provision and supervise sandboxes; the proxy exposes preview URLs; and the daemon runs inside each sandbox as a local agent.

flowchart LR
    User[Developer / AI Agent] -->|SDK / CLI| CLI[Daytona CLI + MCP Server]
    User -->|HTTP| API[Daytona API]
    User -->|Web UI| Dashboard[Dashboard]

    API --> Runner[Runner]
    Runner --> Daemon[Sandbox Daemon]
    Daemon --> FS[(Filesystem / Volumes)]

    Sandbox[Sandbox Process] -->|Preview URL| Proxy[Proxy]
    Proxy --> User

    API --> OTEL[OpenTelemetry / Grafana]
    Runner --> OTEL

Key architectural properties:

• Stateless API and stateful runners. The API handles authentication, scheduling, and metadata; runners own the lifecycle of each sandbox process. Source: libs/sdk-go/README.md (best-practice defer sandbox.Delete pattern).
• Daemon-per-sandbox. Each sandbox runs a local daemon that mediates file, process, Git, and LSP operations, so SDK calls translate into local syscalls rather than direct container manipulation. Source: libs/sdk-typescript/README.md.
• Proxy for previews. The proxy component terminates preview URLs (e.g. https://<port>-<id>.proxy.daytona.works) and is the same component that now exposes a debug metrics server as of v0.187.0.
• Observability first-class. Service-level CPU, memory, and disk metrics are exported via OpenTelemetry and visualized in Grafana. Source: examples/otel-dashboards/grafana/README.md.
• Toolbox API. A lower-level API (the "toolbox") exposes fine-grained computer-use primitives such as press_hotkey, scroll, take_compressed_screenshot, and start_computer_use. Source: libs/toolbox-api-client-python/README.md.

SDKs, CLI, and AI Agent Integrations

Daytona ships official SDKs in five languages. All SDKs share a consistent configuration model based on DAYTONA_API_KEY, DAYTONA_API_URL, and DAYTONA_TARGET (region). Source: libs/sdk-python/README.md, libs/sdk-ruby/README.md

import { Daytona, Image } from '@daytona/sdk';
const daytona = new Daytona();
const sandbox = await daytona.create({ image: Image.debianSlim('3.12') });

The CLI bundles an MCP server so any MCP-compatible agent (Claude Desktop, Claude Code, Cursor, Windsurf) can call sandbox create/destroy, process.exec, file operations, and preview-link generation as native tools. Source: apps/cli/mcp/README.md

The guides/ directory contains end-to-end reference integrations with several agent frameworks:

• CopilotKit — generative-UI coding agent where every tool call renders as a card in the chat. Source: guides/typescript/copilotkit/generative-ui-coding-agent/README.md
• OpenAI Codex SDK — codex-sdk-agent package. Source: guides/typescript/openai/codex-sdk/agent/package.json
• Anthropic Claude Agent SDK — single- and multi-agent variants that build and preview a Lunar Lander game on a Daytona preview URL. Source: guides/typescript/anthropic/multi-agent-claude-sdk/README.md
• AgentKit (Inngest) — autonomous coding agent with dev-server orchestration. Source: guides/typescript/agentkit-inngest/coding-agent/anthropic/README.md
• Mastra — coding agent with semantic-recall memory backed by LibSQLVector. Source: guides/typescript/mastra/coding-agent/openai/README.md
• LangGraph — Python plan-and-execute state machine with per-step retry and persistent interpreter context. Source: guides/python/langgraph/plan-and-execute-data-agent/README.md
• Flue — TDD-driven bug-fix orchestrator that opens real GitHub pull requests from inside a sandbox. Source: guides/typescript/flue/README.md

Deployment and Known Limitations

Daytona can be self-hosted on Kubernetes. Community issue #4232 reports that on containerd-based Kubernetes clusters, the runner sometimes cannot connect to the API, which suggests that the runner's bootstrap and TLS configuration must be carefully aligned with the container runtime in those environments.

Two other long-standing feature requests highlight current architectural limits around Volumes and storage:

• #3413 — Direct file upload/download for volumes without an attached sandbox.
• #3340 — Read-only volume mounts so consumer sandboxes (e.g. AI agents) can read shared datasets without mutation risk.
• #2486 — Mounting external remote storage (e.g. S3) so users can bring their own object stores instead of relying solely on Daytona-managed persistence.

These issues indicate that the current architecture treats Volumes as in-band filesystem resources attached to a running sandbox, and that detached and remote-storage paths are still evolving.

See Also

• Sandboxes and Lifecycle
• Volumes and Snapshots
• SDK Reference (TypeScript / Python / Go / Ruby / Java)
• MCP Server and AI Agent Integrations
• Self-Hosting on Kubernetes
• Observability with OpenTelemetry and Grafana

Related Pages

Related topics: Overview & System Architecture, Volumes, Snapshots & Data Persistence, Deployment, Runners & Platform Operations

Sandboxes: Core Compute Primitive

Overview and Purpose

Sandboxes are the central compute primitive of Daytona. The repository's top-level documentation defines Daytona as "an open-source, secure and elastic infrastructure for running AI-generated code" and describes sandboxes as "full composable computers" that retain state across operations. Source: README.md

A sandbox encapsulates an isolated, stateful execution environment that exposes a filesystem, a process runtime, a Git client, Language Server Protocol (LSP) support, and code-execution capabilities behind a single API. The same README categorizes these capabilities under four pillars: Platform (governance), Sandboxes (the primitive itself), Agent tools (programmatic capabilities), and Human tools (remote sessions). Source: README.md

The primitive is intentionally designed to be agent-first. Each guide demonstrates that a single sandbox can be created on demand, populated with code, executed, and torn down — typically by a host-side agent framework such as LangGraph, LangChain, Mastra, Google ADK, or the Claude Agent SDK. Source: guides/python/langgraph/plan-and-execute-data-agent/README.md, guides/typescript/mastra/coding-agent/openai/README.md, guides/typescript/anthropic/multi-agent-claude-sdk/README.md

Lifecycle and Creation Patterns

The official SDKs (TypeScript, Python, Go, Ruby) all expose a uniform create() entry point that returns a Sandbox handle. Three canonical creation patterns are documented across the SDKs:

1. From a base image — instantiate a sandbox from a prebuilt image such as debianSlim('3.12') and optionally tune resources (CPU, memory, disk). Source: libs/sdk-typescript/README.md, libs/sdk-python/README.md, libs/sdk-ruby/README.md
2. Ephemeral sandboxes — pass ephemeral: true together with an autoStopInterval so the sandbox is automatically deleted once stopped. Source: libs/sdk-typescript/README.md, libs/sdk-python/README.md, libs/sdk-ruby/README.md
3. From a snapshot — restore a sandbox from a named snapshot, optionally selecting a default language runtime. Source: libs/sdk-typescript/README.md, libs/sdk-python/README.md, libs/sdk-ruby/README.md

Cleanup is enforced by the SDK contracts. The Go SDK documentation explicitly recommends wrapping usage in defer sandbox.Delete(ctx) to guarantee resource cleanup, and the LangGraph plan-and-execute guide guarantees cleanup via a dedicated graph node that runs even on failure paths. Source: libs/sdk-go/README.md, guides/python/langgraph/plan-and-execute-data-agent/README.md

stateDiagram-v2
    [*] --> Created : create() / image|snapshot
    Created --> Running : start
    Running --> Stopped : stop
    Stopped --> Archived : archive
    Stopped --> Running : start
    Stopped --> [*] : delete (ephemeral)
    Archived --> [*] : delete
    Running --> [*] : autoStopInterval (ephemeral)

Capabilities Exposed to Agents

A sandbox handle exposes a consistent capability surface across SDKs. The TypeScript SDK README summarizes it as: "sandbox management, file system operations, Git operations, language server protocol support, process and code execution, and computer use." Source: libs/sdk-typescript/README.md

The Mastra coding-agent guide demonstrates that an agent can run an entire development workflow — scaffolding files, installing packages, executing tests, and exposing a dev server — entirely through these surface methods. Source: guides/typescript/mastra/coding-agent/openai/README.md

The dspy-rlms guide goes further by showing that a sandbox can host a broker HTTP server on a fixed port (default 3000) that bridges host-side custom tools into the interpreter context, allowing the LLM to call arbitrary Python functions that execute outside the sandbox while appearing as local functions to generated code. Source: guides/python/dspy-rlms/README.md

Configuration and Integration Surfaces

All SDKs are configured through the same three environment variables: DAYTONA_API_KEY (issued from the Daytona Dashboard), DAYTONA_API_URL (control-plane endpoint), and DAYTONA_TARGET (region selector, e.g. us, eu). Source: libs/sdk-typescript/README.md, libs/sdk-ruby/README.md

The CLI ships a Model Context Protocol (MCP) server that exposes sandbox management, command execution, file operations, and preview-link generation to MCP-compatible agents (Claude Desktop, Claude Code, Cursor, Windsurf). Source: apps/cli/mcp/README.md

Community-Relevant Limitations

Two recurring community pain points are observable in the issue tracker. The first cluster relates to Volumes, the persistent storage layer that sits beside sandboxes. Users have asked for direct file upload/download without an attached sandbox (#3413), read-only mounts for safe data sharing between consumer sandboxes (#3340), and the ability to mount external object stores such as S3 directly (#2486). These requests all share a common shape: the sandbox primitive itself is the access surface for volume data, and detaching that access is a recurring ask. Source: community context — issues #3413, #3340, #2486

A second cluster is operational: self-hosted Kubernetes runners failing to connect to the API on containerd-based clusters (#4232), and onboarding confusion stemming from the README's compressed "3 commands" framing (#100). Both reinforce the same lesson — once a sandbox is provisioned through the SDK, lifecycle and connectivity are the most common failure modes. Source: community context — issues #4232, #100

See Also

• Snapshots: Persistent Environment Capture
• Volumes: Persistent Storage
• Daytona MCP Server
• API Keys and Authentication

Related Pages

Related topics: Sandboxes: Core Compute Primitive, Deployment, Runners & Platform Operations

Volumes, Snapshots & Data Persistence

Overview

Daytona exposes three distinct persistence primitives that work together to give sandboxes state across the agent lifecycle. A Sandbox is an isolated, full composable computer that runs workloads; a Volume is a piece of persistent storage decoupled from any single sandbox that can be mounted into one; and a Snapshot is a pre-built image (with cached files, packages, and tooling) used to provision new sandboxes quickly. The top-level project README frames Daytona as "an open-source, secure and elastic infrastructure for running AI-generated code" in which "stateful environment snapshots enable persistent agent operations across sessions", making the trio the foundation of long-running agent architectures (Source: README.md). The API layer implements each primitive as a separate entity, controller, and service — for example, dedicated volume.controller.ts, volume.service.ts, and volume.manager.ts files under apps/api/src/sandbox/ (Source: apps/api/src/sandbox/controllers/volume.controller.ts, apps/api/src/sandbox/services/volume.service.ts, apps/api/src/sandbox/managers/volume.manager.ts).

Volume Management

Volumes are first-class resources with their own DTO and entity definitions. A volume is created with a name and can later be mounted into one or more sandboxes, providing data that outlives any individual compute instance. The Go SDK exposes the full volume API surface through VolumeService methods: List(ctx), Get(ctx, name), Create(ctx, name), and Delete(ctx, volume) (Source: libs/sdk-go/README.md). Equivalent operations are surfaced through the Python, TypeScript, and Ruby SDKs, all of which document a volumes example for programmatic use. The persisted shape of a volume is captured by volume.entity.ts and its companion DTOs create-volume.dto.ts and volume.dto.ts (Source: apps/api/src/sandbox/entities/volume.entity.ts, apps/api/src/sandbox/dto/create-volume.dto.ts, apps/api/src/sandbox/dto/volume.dto.ts).

The intended workflow is: create a volume once, mount it into sandboxes that need shared data, and delete it only when no consumers remain. The community has highlighted three limitations in the current model that the project tracks as open issues: detached access (direct upload/download to a volume without an attached sandbox, tracked in #3413), read-only mounts for "consumer" sandboxes such as AI agents (#3340), and mounting external remote storage like S3 buckets (#2486). Until those ship, volumes are only reachable through the filesystem of a running sandbox, and they are always mounted read-write inside that sandbox.

Snapshot Management

Snapshots represent the pre-baked half of the persistence story: an image, plus all the packages, source files, and configuration that should be present the moment a sandbox starts. They avoid the cost of reinstalling dependencies on every sandbox creation. The Go SDK snapshot service offers Get(ctx, nameOrID), Create(ctx, params, timeout) (which returns the snapshot, a streaming log channel, and an error), and Delete(ctx, snapshot) (Source: libs/sdk-go/README.md). The Create method closes the log channel when the build finishes, enabling real-time build output — a pattern demonstrated by the snapshots/withlogstreaming example. Consumer SDKs expose the same CreateSandboxFromSnapshotParams(snapshot=...) constructor, letting callers spin up a sandbox in a single API call (Source: libs/sdk-python/README.md, libs/sdk-ruby/README.md, libs/sdk-typescript/README.md).

The snapshot lifecycle is complementary to volumes: a snapshot defines what a fresh sandbox looks like, while a volume provides data that should exist regardless of which sandbox is running. Long-running recursive-agent workflows, for example, often start from a snapshot and then attach a volume to keep agent state between iterations (Source: guides/python/recursive-language-models/README.md).

Persistence Patterns & Lifecycle

Daytona combines the primitives above with two lifecycle controls that shape how state is retained. Ephemeral sandboxes are created with ephemeral: true and autoStopInterval so they self-destruct when stopped, which is useful for short-lived jobs that still need snapshot-based fast start (Source: libs/sdk-python/README.md, libs/sdk-ruby/README.md, libs/sdk-typescript/README.md). Long-lived workloads mount a volume to retain data across sandbox restarts. The planning agent in plan-and-execute-data-agent/README.md illustrates the latter pattern, explicitly deleting the sandbox in a cleanup node regardless of success — a recommended practice also repeated in the Go SDK's "Best Practices" section, which advocates defer sandbox.Delete(ctx) (Source: guides/python/langgraph/plan-and-execute-data-agent/README.md, libs/sdk-go/README.md).

On the server side, persistence is governed by the expand-and-contract migration pattern in apps/api/src/migrations/README.md, which runs additive changes in pre-deploy/ before API rollout and breaking changes in post-deploy/ after, allowing the volume and snapshot entity schemas to evolve without downtime (Source: apps/api/src/migrations/README.md).

State Persistence Comparison

See Also

• Sandboxes & Workspace Configuration — resource sizing and environment setup
• Snapshots — deeper coverage of snapshot build and streaming APIs
• SDK Reference — Volumes and Snapshots — language-specific code samples
• Self-Hosted Deployment — K8s runner and storage provisioning (related to #4232)
• Agent Guides — end-to-end examples that combine volumes, snapshots, and ephemeral sandboxes

Related Pages

Related topics: Overview & System Architecture, Sandboxes: Core Compute Primitive, Volumes, Snapshots & Data Persistence

Deployment, Runners & Platform Operations

Overview

Daytona is an open-source, secure, and elastic infrastructure for running AI-generated code. It exposes sandboxes as "full composable computers" that can be managed programmatically through the API, SDKs, and CLI (README.md). To host the platform, Daytona supports two primary deployment topologies: a self-contained Docker Compose stack for local or single-node use, and a Kubernetes (Helm) chart for production-grade, multi-node deployments. Both topologies share a common runtime component called the Runner, which is the worker that actually materializes sandboxes on a host.

This page documents the deployment surfaces, the runner lifecycle and packaging, and the platform-level operational concerns (observability, MCP integration, and known self-hosting caveats surfaced by the community).

Deployment Topologies

Docker Compose (Local / Single-Node)

The Docker Compose manifest at docker/docker-compose.yaml is the canonical local deployment entry point. It wires up the core services (API server, database, object storage, runner, and supporting daemons) so a developer can stand up the full platform with a single docker compose up. The repository README treats it as the default way to "run Daytona" for evaluation and development, complementing the hosted Dashboard at app.daytona.io (README.md). It is the right starting point when you need a reproducible local cluster without Kubernetes.

Kubernetes (Helm / Production)

For production and multi-node deployments, Daytona ships a Helm chart under charts/daytona-preview/. The chart is described by Chart.yaml and is parameterized through values.yaml, exposing knobs for image tags, resource limits, persistence, ingress, and the runner. The "preview" naming indicates an evolving API; values may change between minor releases, so treat values.yaml as the source of truth rather than any pinned example. The chart is the deployment surface most affected by community-reported issues — for example, issue #4232 documents cases where a self-hosted Runner fails to connect to the API on containerd-based Kubernetes clusters, typically because the Runner's outbound path to the API is blocked by NetworkPolicy or by a misconfigured apiUrl in the chart values.

The Runner

Role and Entry Point

The Runner is the agent that turns a sandbox request into a running container/VM on a host. Its binary is built from apps/runner/cmd/runner/main.go, which boots the runner service, registers it with the control plane, and begins polling for work. From a deployment perspective, the Runner is the only component that needs to be installed *on every host that should be capable of hosting sandboxes* — the rest of the platform is centralized.

Packaging and Lifecycle

The Runner is distributed as a Debian package so it can be installed alongside a container runtime on standard Linux hosts. The package metadata lives in apps/runner/packaging/deb/DEBIAN/control (name, version, architecture, dependencies) and the post-install hook in apps/runner/packaging/deb/DEBIAN/postinst handles service registration and any one-time host setup. Once installed, the Runner runs as a long-lived system service managed by systemd, defined in apps/runner/packaging/systemd/daytona-runner.service. This service file declares the unit's dependencies, restart policy, and environment, and is what the postinst script enables and starts.

flowchart LR
    User[User / SDK / CLI] --> API[Daytona API]
    API -->|dispatch sandbox job| Runner[Daytona Runner]
    Runner -->|containerd / docker| Host[Host Runtime]
    Host --> Sandbox[Sandbox]
    API --> Storage[(Object Store)]
    API --> DB[(Database)]

A typical install sequence on a self-hosted node is: install the .deb → postinst registers the systemd unit → edit the unit's environment to point at the API (DAYTONA_API_URL, DAYTONA_API_KEY) → systemctl enable --now daytona-runner. On Kubernetes, the same binary is wrapped in a DaemonSet so every node runs a Runner.

Platform Operations

Observability

Daytona emits OpenTelemetry metrics, and the repository ships reference dashboards under examples/otel-dashboards/grafana/. The Grafana README lists widgets for sandbox count, per-service CPU/memory/disk utilization, top consumers, and a combined resource-pressure score. Recent release v0.187.0 adds an exposed debug metrics server on the proxy (#5012), making it easier to scrape platform-level signals without a full OTel pipeline.

MCP and Agent Integration

Operationally, the platform is also exposed to AI agents through the Daytona MCP Server (apps/cli/mcp/README.md). After daytona login, operators initialize the server into Claude Desktop, Cursor, or Windsurf with daytona mcp init, which wires sandbox management, command execution, filesystem operations, and preview-link generation into the agent's tool palette. This is a deployment-adjacent concern: the MCP server must be able to reach the same API endpoint as the SDKs and CLI.

Community-Reported Failure Modes

Two recurring themes from community issues shape how you should operate Daytona:

• Self-hosted runner connectivity (issue #4232): on containerd clusters the Runner often fails to dial the API. Validate apiUrl, NetworkPolicy egress, and the Runner's tls settings before assuming a binary bug.
• Volumes and external storage (issues #3413, #3340, #2486): users consistently want direct volume access, read-only mounts, and external object-store (e.g. S3) mounts. Until these ship, day-to-day operations should treat Volumes as sandbox-attached only, and plan around snapshots for persistence.

See Also

• Sandboxes, Snapshots & Volumes
• API, SDKs & CLI Reference
• Configuration & Environment Variables
• Observability & Telemetry

Doramagic Pitfall Log

Found 7 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Capability evidence risk - Capability evidence risk requires verification.

1. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | github_repo:753490180 | https://github.com/daytonaio/daytona

2. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | github_repo:753490180 | https://github.com/daytonaio/daytona

3. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | github_repo:753490180 | https://github.com/daytonaio/daytona

4. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | github_repo:753490180 | https://github.com/daytonaio/daytona

5. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | cevd_43f2dcb000cd4c41bb01cae9aec0f048 | https://github.com/daytonaio/daytona/issues/5013

6. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | github_repo:753490180 | https://github.com/daytonaio/daytona

7. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | github_repo:753490180 | https://github.com/daytonaio/daytona

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using daytona with real data or production workflows.

• CLI snapshot create with --context fails with "error checking bucket exi - github / github_issue
• v0.187.0 - github / github_release
• v0.186.0 - github / github_release
• v0.185.0 - github / github_release
• v0.184.0 - github / github_release
• v0.183.0 - github / github_release
• v0.182.0 - github / github_release
• v0.181.0 - github / github_release
• v0.180.0 - github / github_release
• v0.179.0 - github / github_release
• v0.178.0 - github / github_release
• Capability evidence risk requires verification - GitHub / issue