# https://github.com/daytonaio/daytona Project Manual

Generated at: 2026-06-11 18:30:29 UTC

## Table of Contents

- [Overview & System Architecture](#page-overview)
- [Sandboxes: Core Compute Primitive](#page-sandboxes)
- [Volumes, Snapshots & Data Persistence](#page-storage)
- [Deployment, Runners & Platform Operations](#page-deployment)

<a id='page-overview'></a>

## Overview & System Architecture

### Related Pages

Related topics: [Sandboxes: Core Compute Primitive](#page-sandboxes), [Volumes, Snapshots & Data Persistence](#page-storage), [Deployment, Runners & Platform Operations](#page-deployment)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [libs/sdk-typescript/README.md](https://github.com/daytonaio/daytona/blob/main/libs/sdk-typescript/README.md)
- [libs/sdk-python/README.md](https://github.com/daytonaio/daytona/blob/main/libs/sdk-python/README.md)
- [libs/sdk-go/README.md](https://github.com/daytonaio/daytona/blob/main/libs/sdk-go/README.md)
- [libs/sdk-ruby/README.md](https://github.com/daytonaio/daytona/blob/main/libs/sdk-ruby/README.md)
- [libs/sdk-java/README.md](https://github.com/daytonaio/daytona/blob/main/libs/sdk-java/README.md)
- [libs/toolbox-api-client-python/README.md](https://github.com/daytonaio/daytona/blob/main/libs/toolbox-api-client-python/README.md)
- [apps/cli/mcp/README.md](https://github.com/daytonaio/daytona/blob/main/apps/cli/mcp/README.md)
- [examples/otel-dashboards/grafana/README.md](https://github.com/daytonaio/daytona/blob/main/examples/otel-dashboards/grafana/README.md)
- [guides/typescript/flue/README.md](https://github.com/daytonaio/daytona/blob/main/guides/typescript/flue/README.md)
- [guides/typescript/copilotkit/generative-ui-coding-agent/README.md](https://github.com/daytonaio/daytona/blob/main/guides/typescript/copilotkit/generative-ui-coding-agent/README.md)
</details>

# 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](https://github.com/daytonaio/daytona/issues/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](https://github.com/daytonaio/daytona/blob/main/libs/sdk-typescript/README.md)

## Core Capabilities

Each SDK exposes a uniform surface area for sandbox control. Source: [libs/sdk-typescript/README.md](https://github.com/daytonaio/daytona/blob/main/libs/sdk-typescript/README.md)

| Capability | Description |
|---|---|
| Sandbox management | Create, start, stop, delete, snapshot ephemeral or persistent sandboxes |
| Filesystem operations | Upload, download, list, mkdir, read/write files inside a sandbox |
| Git operations | Clone, status, branches, commits inside a sandbox |
| Process / command execution | Run shell commands, scripts, or streaming code interpreter sessions |
| LSP support | Language Server Protocol completions, references, and symbols |
| Computer use | Mouse/keyboard/screenshot primitives for GUI-driving agents |
| Volumes | Persistent volumes mountable into sandboxes (see Limitations) |
| Snapshots | Pre-built sandbox images for fast cold starts |

## 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.

```mermaid
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](https://github.com/daytonaio/daytona/blob/main/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](https://github.com/daytonaio/daytona/blob/main/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](https://github.com/daytonaio/daytona/blob/main/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](https://github.com/daytonaio/daytona/blob/main/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](https://github.com/daytonaio/daytona/blob/main/libs/sdk-python/README.md), [libs/sdk-ruby/README.md](https://github.com/daytonaio/daytona/blob/main/libs/sdk-ruby/README.md)

```typescript
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](https://github.com/daytonaio/daytona/blob/main/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](https://github.com/daytonaio/daytona/blob/main/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](https://github.com/daytonaio/daytona/blob/main/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](https://github.com/daytonaio/daytona/blob/main/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](https://github.com/daytonaio/daytona/blob/main/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](https://github.com/daytonaio/daytona/blob/main/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](https://github.com/daytonaio/daytona/blob/main/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](https://github.com/daytonaio/daytona/blob/main/guides/typescript/flue/README.md)

## Deployment and Known Limitations

Daytona can be self-hosted on Kubernetes. Community issue [#4232](https://github.com/daytonaio/daytona/issues/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

---

<a id='page-sandboxes'></a>

## Sandboxes: Core Compute Primitive

### Related Pages

Related topics: [Overview & System Architecture](#page-overview), [Volumes, Snapshots & Data Persistence](#page-storage), [Deployment, Runners & Platform Operations](#page-deployment)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/daytonaio/daytona/blob/main/README.md)
- [libs/sdk-typescript/README.md](https://github.com/daytonaio/daytona/blob/main/libs/sdk-typescript/README.md)
- [libs/sdk-python/README.md](https://github.com/daytonaio/daytona/blob/main/libs/sdk-python/README.md)
- [libs/sdk-go/README.md](https://github.com/daytonaio/daytona/blob/main/libs/sdk-go/README.md)
- [libs/sdk-ruby/README.md](https://github.com/daytonaio/daytona/blob/main/libs/sdk-ruby/README.md)
- [apps/cli/mcp/README.md](https://github.com/daytonaio/daytona/blob/main/apps/cli/mcp/README.md)
- [guides/python/dspy-rlms/README.md](https://github.com/daytonaio/daytona/blob/main/guides/python/dspy-rlms/README.md)
- [guides/python/langgraph/plan-and-execute-data-agent/README.md](https://github.com/daytonaio/daytona/blob/main/guides/python/langgraph/plan-and-execute-data-agent/README.md)
- [guides/typescript/mastra/coding-agent/openai/README.md](https://github.com/daytonaio/daytona/blob/main/guides/typescript/mastra/coding-agent/openai/README.md)
- [guides/typescript/anthropic/multi-agent-claude-sdk/README.md](https://github.com/daytonaio/daytona/blob/main/guides/typescript/anthropic/multi-agent-claude-sdk/README.md)
</details>

# 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]()

```mermaid
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]()

| Capability | Typical methods (TypeScript SDK) | Example source |
| --- | --- | --- |
| Process / code execution | `sandbox.process.exec(command)` | [libs/sdk-typescript/README.md]() |
| Filesystem | upload, download, list directories | [libs/sdk-go/README.md]() |
| Git | `sandbox.git.clone(url, path)`, `branches`, `add` | [libs/sdk-ruby/README.md]() |
| LSP | `sandbox.create_lsp_server(languageId, path)`, `did_open`, `document_symbols`, `completions` | [libs/sdk-ruby/README.md]() |
| Preview URLs | auto-generated `*.proxy.daytona.works` links for hosted processes | [guides/typescript/anthropic/multi-agent-claude-sdk/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](#)

---

<a id='page-storage'></a>

## Volumes, Snapshots & Data Persistence

### Related Pages

Related topics: [Sandboxes: Core Compute Primitive](#page-sandboxes), [Deployment, Runners & Platform Operations](#page-deployment)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/daytonaio/daytona/blob/main/README.md)
- [libs/sdk-go/README.md](https://github.com/daytonaio/daytona/blob/main/libs/sdk-go/README.md)
- [libs/sdk-ruby/README.md](https://github.com/daytonaio/daytona/blob/main/libs/sdk-ruby/README.md)
- [libs/sdk-typescript/README.md](https://github.com/daytonaio/daytona/blob/main/libs/sdk-typescript/README.md)
- [libs/sdk-python/README.md](https://github.com/daytonaio/daytona/blob/main/libs/sdk-python/README.md)
- [apps/api/src/sandbox/controllers/volume.controller.ts](https://github.com/daytonaio/daytona/blob/main/apps/api/src/sandbox/controllers/volume.controller.ts)
- [apps/api/src/sandbox/services/volume.service.ts](https://github.com/daytonaio/daytona/blob/main/apps/api/src/sandbox/services/volume.service.ts)
- [apps/api/src/sandbox/managers/volume.manager.ts](https://github.com/daytonaio/daytona/blob/main/apps/api/src/sandbox/managers/volume.manager.ts)
- [apps/api/src/sandbox/dto/create-volume.dto.ts](https://github.com/daytonaio/daytona/blob/main/apps/api/src/sandbox/dto/create-volume.dto.ts)
- [apps/api/src/sandbox/dto/volume.dto.ts](https://github.com/daytonaio/daytona/blob/main/apps/api/src/sandbox/dto/volume.dto.ts)
- [apps/api/src/sandbox/entities/volume.entity.ts](https://github.com/daytonaio/daytona/blob/main/apps/api/src/sandbox/entities/volume.entity.ts)
- [apps/api/src/sandbox/entities/snapshot.entity.ts](https://github.com/daytonaio/daytona/blob/main/apps/api/src/sandbox/entities/snapshot.entity.ts)
- [apps/api/src/migrations/README.md](https://github.com/daytonaio/daytona/blob/main/apps/api/src/migrations/README.md)
- [guides/python/langgraph/plan-and-execute-data-agent/README.md](https://github.com/daytonaio/daytona/blob/main/guides/python/langgraph/plan-and-execute-data-agent/README.md)
- [guides/python/recursive-language-models/README.md](https://github.com/daytonaio/daytona/blob/main/guides/python/recursive-language-models/README.md)
- [guides/typescript/anthropic/multi-agent-claude-sdk/README.md](https://github.com/daytonaio/daytona/blob/main/guides/typescript/anthropic/multi-agent-claude-sdk/README.md)
</details>

# 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

| Primitive | Lifetime | Typical Use | Mutability |
|---|---|---|---|
| Snapshot | Persistent, versioned image | Fast sandbox provisioning | Immutable once built |
| Volume | Persistent, named storage | Shared data across sandboxes | Read-write by default |
| Ephemeral sandbox | Until stopped + auto-stop interval | Short-lived agent runs | Re-created from snapshot |

## See Also

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

---

<a id='page-deployment'></a>

## Deployment, Runners & Platform Operations

### Related Pages

Related topics: [Overview & System Architecture](#page-overview), [Sandboxes: Core Compute Primitive](#page-sandboxes), [Volumes, Snapshots & Data Persistence](#page-storage)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [docker/docker-compose.yaml](https://github.com/daytonaio/daytona/blob/main/docker/docker-compose.yaml)
- [charts/daytona-preview/Chart.yaml](https://github.com/daytonaio/daytona/blob/main/charts/daytona-preview/Chart.yaml)
- [charts/daytona-preview/values.yaml](https://github.com/daytonaio/daytona/blob/main/charts/daytona-preview/values.yaml)
- [apps/runner/cmd/runner/main.go](https://github.com/daytonaio/daytona/blob/main/apps/runner/cmd/runner/main.go)
- [apps/runner/packaging/systemd/daytona-runner.service](https://github.com/daytonaio/daytona/blob/main/apps/runner/packaging/systemd/daytona-runner.service)
- [apps/runner/packaging/deb/DEBIAN/control](https://github.com/daytonaio/daytona/blob/main/apps/runner/packaging/deb/DEBIAN/control)
- [apps/runner/packaging/deb/DEBIAN/postinst](https://github.com/daytonaio/daytona/blob/main/apps/runner/packaging/deb/DEBIAN/postinst)
- [README.md](https://github.com/daytonaio/daytona/blob/main/README.md)
- [examples/otel-dashboards/grafana/README.md](https://github.com/daytonaio/daytona/blob/main/examples/otel-dashboards/grafana/README.md)
- [apps/cli/mcp/README.md](https://github.com/daytonaio/daytona/blob/main/apps/cli/mcp/README.md)
</details>

# 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](https://github.com/daytonaio/daytona/blob/main/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](https://github.com/daytonaio/daytona/blob/main/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.

```mermaid
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](https://github.com/daytonaio/daytona/pull/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](https://github.com/daytonaio/daytona/blob/main/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](/wiki/sandboxes-snapshots-volumes)
- [API, SDKs & CLI Reference](/wiki/api-sdks-cli)
- [Configuration & Environment Variables](/wiki/configuration)
- [Observability & Telemetry](/wiki/observability)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Pitfall Log

Project: daytonaio/daytona

Summary: 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
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested 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
- Evidence strength: source_linked
- 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.
- Suggested 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
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested 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
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested 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
- Evidence strength: source_linked
- 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.
- Suggested 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
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested 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
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: evidence.maintainer_signals | github_repo:753490180 | https://github.com/daytonaio/daytona

<!-- canonical_name: daytonaio/daytona; human_manual_source: deepwiki_human_wiki -->