# https://github.com/daytonaio/daytona 项目说明书

生成时间：2026-06-11 18:16:15 UTC

## 目录

- [平台概览与多面架构](#page-1)
- [沙箱生命周期、快照与持久化卷](#page-2)
- [部署模式与自托管运维](#page-3)
- [SDK、CLI、API 表面与扩展集成](#page-4)

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

## 平台概览与多面架构

### 相关页面

相关主题：[沙箱生命周期、快照与持久化卷](#page-2), [部署模式与自托管运维](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [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/toolbox-api-client-python/README.md](https://github.com/daytonaio/daytona/blob/main/libs/toolbox-api-client-python/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)
- [guides/typescript/flue/README.md](https://github.com/daytonaio/daytona/blob/main/guides/typescript/flue/README.md)
- [guides/python/recursive-language-models/README.md](https://github.com/daytonaio/daytona/blob/main/guides/python/recursive-language-models/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/agentkit-inngest/coding-agent/anthropic/README.md](https://github.com/daytonaio/daytona/blob/main/guides/typescript/agentkit-inngest/coding-agent/anthropic/README.md)
- [examples/otel-dashboards/grafana/README.md](https://github.com/daytonaio/daytona/blob/main/examples/otel-dashboards/grafana/README.md)
- [package.json](https://github.com/daytonaio/daytona/blob/main/package.json)
</details>

# 平台概览与多面架构

## 1. 平台定位与核心价值

Daytona 是一个面向"AI 生成代码"场景的开源、安全、弹性基础设施，其核心抽象被称为 **Sandbox（沙箱）**——即"可组合的完整计算机"。根据 TypeScript SDK 的官方说明，Daytona 提供"an open-source, secure and elastic infrastructure for running AI-generated code"，并以"full composable computers"作为对外卖点（资料来源：[libs/sdk-typescript/README.md](https://github.com/daytonaio/daytona/blob/main/libs/sdk-typescript/README.md)）。

围绕 Sandbox 这一中心，平台向开发者暴露统一的编程接口：沙箱生命周期管理、文件系统操作、Git 操作、语言服务器协议（LSP）、进程与代码执行、以及 Computer Use（桌面级控制）能力。Python SDK 在文档中也明确列出了同样的能力面（资料来源：[libs/sdk-python/README.md](https://github.com/daytonaio/daytona/blob/main/libs/sdk-python/README.md)）。

社区中 #100 号 Issue 反映出"读完首页仍不知道软件解决了什么问题"的痛点，可以从两个角度归纳其价值定位：

- **对 AI Agent 提供隔离执行环境**：所有命令、文件、进程都发生在沙箱内，宿主机器始终保持干净（Flue 指南原文："Cloning, dependency installation, and test runs happen entirely inside Daytona, so your host stays clean"，资料来源：[guides/typescript/flue/README.md](https://github.com/daytonaio/daytona/blob/main/guides/typescript/flue/README.md)）。
- **对应用开发者暴露一致的 API**：以 SDK 形式封装底层差异，让多语言、多框架的 Agent 系统可以共享同一套基础设施。

## 2. 多语言 SDK 体系

平台在四个主流语言上提供官方 SDK，能力面保持一致，但 API 风格遵循各语言习惯。下表给出对照：

| 语言 | 包名 / 安装方式 | 关键能力 | 资料来源 |
|------|----------------|---------|----------|
| TypeScript | `@daytona/sdk`（npm / yarn） | 沙箱、文件系统、Git、LSP、Computer Use | [libs/sdk-typescript/README.md](https://github.com/daytonaio/daytona/blob/main/libs/sdk-typescript/README.md) |
| Python | `daytona`（pip / Poetry） | 同上，含 `code_interpreter` 长连接 | [libs/sdk-python/README.md](https://github.com/daytonaio/daytona/blob/main/libs/sdk-python/README.md) |
| Go | `daytona`（go get） | 同步 `client.Create`、`Process.ExecuteCommand` | [libs/sdk-go/README.md](https://github.com/daytonaio/daytona/blob/main/libs/sdk-go/README.md) |
| Ruby | `daytona`（gem） | 与 TS / Python 对齐的 `Daytona::CreateSandboxFromImageParams` | [libs/sdk-ruby/README.md](https://github.com/daytonaio/daytona/blob/main/libs/sdk-ruby/README.md) |

所有 SDK 都通过三类环境变量完成认证与区域切换：`DAYTONA_API_KEY`、`DAYTONA_API_URL`、`DAYTONA_TARGET`（以 TypeScript README 为代表，资料来源：[libs/sdk-typescript/README.md](https://github.com/daytonaio/daytona/blob/main/libs/sdk-typescript/README.md)）。Go SDK 的示例目录还涵盖了 `sandbox`、`filesystem`、`git_operations`、`code_interpreter`、`lsp_usage`、`pty_interactive`、`snapshots`、`volumes` 等典型场景（资料来源：[libs/sdk-go/README.md](https://github.com/daytonaio/daytona/blob/main/libs/sdk-go/README.md)）。

## 3. 集成与扩展生态

Sandbox 本身是一个"被调用方"，真正发挥价值的方式是嵌入到各种 Agent 框架与协作工具中。仓库 `guides/` 目录沉淀了大量端到端示例：

- **CopilotKit Generative-UI Coding Agent**：在聊天流中以"生成式 UI"形式渲染 shell、文件编辑、目录列表与 `<iframe>` 预览（资料来源：[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)）。
- **AgentKit + Inngest 编码 Agent**：展示 Inngest 作为编排层、Daytona 作为执行层的"全自动开发"工作流，自动启动 dev server 并产出预览链接（资料来源：[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)）。
- **Flue TDD 修复 Agent**：强调"技能驱动（Skill-driven）"——TDD 工作流写在 `.agents/skills/bug-fix/SKILL.md` 中，可以不改代码而调整行为（资料来源：[guides/typescript/flue/README.md](https://github.com/daytonaio/daytona/blob/main/guides/typescript/flue/README.md)）。
- **Recursive Language Models（RLM）**：递归式架构——每个子 Agent 在自己的 Daytona 沙箱中运行，便于横向扩展（资料来源：[guides/python/recursive-language-models/README.md](https://github.com/daytonaio/daytona/blob/main/guides/python/recursive-language-models/README.md)）。
- **LangGraph Plan-and-Execute**：六节点状态机演示规划、逐步执行、单步重试与最终清理（资料来源：[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)）。

下图展示了"AI Agent ↔ Daytona 平台 ↔ 沙箱执行"的多面协作关系：

```mermaid
flowchart LR
    subgraph Clients["客户端入口"]
        A1[TypeScript SDK]
        A2[Python SDK]
        A3[Go / Ruby SDK]
    end
    subgraph Platform["Daytona 平台"]
        P1[API & Toolbox]
        P2[Runner / Proxy / Daemon]
        P3[Snapshot Manager]
        P4[Volumes & Storage]
    end
    subgraph Agents["Agent 框架"]
        G1[CopilotKit]
        G2[AgentKit + Inngest]
        G3[LangGraph]
        G4[Flue]
        G5[Recursive LM]
    end
    A1 --> P1
    A2 --> P1
    A3 --> P1
    G1 --> A2
    G2 --> A1
    G3 --> A2
    G4 --> A1
    G5 --> A2
    P1 --> P2 --> P4
    P1 --> P3
```

## 4. 可观测性与运维入口

仓库不仅包含运行逻辑，也提供了现成的运维面板示例。`examples/otel-dashboards/grafana/README.md` 定义了一套 Grafana 仪表盘，覆盖 **Resource Overview、CPU Details、Memory Details** 等多张面板：沙箱总数、关键服务计数、CPU / 内存 / 磁盘利用率时序、Top 消耗者、资源压力评分等。面板默认采样窗口包括 `1m / 5m / 10m / 30m / 1h`，可按实时性需求切换（资料来源：[examples/otel-dashboards/grafana/README.md](https://github.com/daytonaio/daytona/blob/main/examples/otel-dashboards/grafana/README.md)）。

在发布管理上，根目录 `package.json` 使用 **Nx + Yarn 4.13** 作为 monorepo 调度器，并启用 `lint-staged` 与 Storybook / Vitest / tsc 等组合校验管线（资料来源：[package.json](https://github.com/daytonaio/daytona/blob/main/package.json)）。最新版本 v0.187.0（2026-06-11）显示 dashboard 限制分级、代理调试指标服务等能力持续在迭代。

## 5. 已知约束与社区共识

与平台多面性相对的，是社区中明确提出的功能缺口：

- **Volume 的分离访问**：当前 Volume 必须通过已挂载的 Sandbox 访问，社区呼吁直接经 API / CLI / SDK 上传下载（参考 Issue #3413）。
- **只读挂载（RO Mounts）**：多个 Agent 作为"消费者"读取共享脚本与数据集时，需要安全的只读模式（参考 Issue #3340）。
- **外部远端存储接入**：希望把 S3 等外部存储直接挂入沙箱，绕开 Daytona 内置存储（参考 Issue #2486）。
- **自托管 Kubernetes 部署**：在 containerd 集群中，Runner 仍可能出现无法连接 API 的问题（参考 Issue #4232）。

上述议题说明：在"Sandbox 即核心"的多面架构已经稳固的同时，**存储与部署边界**仍是下一阶段扩展的重点。

## See Also

- [README.md](https://github.com/daytonaio/daytona/blob/main/README.md) — 项目总入口
- [libs/toolbox-api-client-python/README.md](https://github.com/daytonaio/daytona/blob/main/libs/toolbox-api-client-python/README.md) — Computer Use 与低级 API 索引
- [examples/otel-dashboards/grafana/README.md](https://github.com/daytonaio/daytona/blob/main/examples/otel-dashboards/grafana/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) — Generative UI 集成示例

---

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

## 沙箱生命周期、快照与持久化卷

### 相关页面

相关主题：[平台概览与多面架构](#page-1), [部署模式与自托管运维](#page-3), [SDK、CLI、API 表面与扩展集成](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [apps/api/src/sandbox/managers/sandbox.manager.ts](https://github.com/daytonaio/daytona/blob/main/apps/api/src/sandbox/managers/sandbox.manager.ts)
- [apps/api/src/sandbox/managers/snapshot.manager.ts](https://github.com/daytonaio/daytona/blob/main/apps/api/src/sandbox/managers/snapshot.manager.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/services/sandbox.service.ts](https://github.com/daytonaio/daytona/blob/main/apps/api/src/sandbox/services/sandbox.service.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/entities/volume.entity.ts](https://github.com/daytonaio/daytona/blob/main/apps/api/src/sandbox/entities/volume.entity.ts)
- [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)
</details>

# 沙箱生命周期、快照与持久化卷

## 概述

Daytona 是一个面向 AI 生成代码运行场景的开源基础设施，核心抽象是「可组合的计算单元」——沙箱（Sandbox）。沙箱既可作为一次性执行环境，也可在快照（Snapshot）的基础上复用，并通过持久化卷（Volume）跨生命周期保留数据。围绕这一抽象，平台提供了三类核心能力：沙箱的完整生命周期管理、基于快照的快速预置（pre-warm）、以及独立于沙箱实例的持久化卷挂载。

`资料来源：[apps/api/src/sandbox/managers/sandbox.manager.ts]()`、`[apps/api/src/sandbox/managers/snapshot.manager.ts]()`、`[apps/api/src/sandbox/managers/volume.manager.ts]()`

## 沙箱生命周期

沙箱的生命周期由 `SandboxManager` 统一驱动，主要状态包括：创建（Create）、运行（Start/Running）、停止（Stopped）、删除（Deleted）。SDK 在调用层屏蔽了底层的构建差异，对外暴露统一的 `create` / `start` / `stop` / `delete` 语义。

### 创建方式

SDK 提供多种创建入口，覆盖从空白镜像到快照恢复的典型路径：

| 创建方式 | TypeScript | Python | Go | Ruby |
|---|---|---|---|---|
| 从基础镜像 | `Image.debianSlim('3.12')` | `Image.debian_slim("3.12")` | 见 `examples/fromimage` | `Image.debian_slim('3.12')` |
| 自定义资源 | `resources: { cpu, memory, disk }` | `Resources(cpu, memory, disk)` | 通过 `params` | `Resources.new(cpu, memory, disk)` |
| 从快照恢复 | `snapshot: 'my-snapshot-name'` | `snapshot="my-snapshot-name"` | `examples/snapshots/simple` | `snapshot: 'my-snapshot-name'` |
| 临时沙箱 | `ephemeral: true, autoStopInterval: 5` | `ephemeral=True, auto_stop_interval=5` | 同步支持 | `ephemeral: true, auto_stop_interval: 5` |

`资料来源：[libs/sdk-typescript/README.md:30-60]()`、`[libs/sdk-python/README.md:30-60]()`、`[libs/sdk-go/README.md:80-110]()`、`[libs/sdk-ruby/README.md:20-50]()`

### 临时沙箱与自动停止

临时沙箱（Ephemeral Sandbox）会在停止后被自动删除，适合短生命周期的 AI Agent 任务。`autoStopInterval`（默认单位为分钟）控制空闲超时。社区中关于「减少使用成本」与「任务完成后即时清理」的需求正是通过这一机制满足的。

`资料来源：[libs/sdk-python/README.md:38-44]()`、`[libs/sdk-typescript/README.md:48-52]()`

### 资源回收最佳实践

Go SDK 文档明确建议在 `Create` 后立刻使用 `defer sandbox.Delete(ctx)`，以确保异常路径下也能释放底层资源。这一模式可推广到所有语言 SDK。

`资料来源：[libs/sdk-go/README.md:112-128]()`

## 快照系统

快照（Snapshot）是 Daytona 预置环境的核心机制。`SnapshotManager` 负责镜像构建、注册与基于快照的快速启动，常见工作流包括：构建自定义运行时 → 注册为快照 → 在毫秒级时间内拉起沙箱。

### 快照创建

Go SDK 提供了两个示例：`examples/snapshots/simple` 演示基础快照操作；`examples/snapshots/withlogstreaming/snapshot_with_logs.go` 演示通过日志流实时观察快照构建过程。TypeScript / Python / Ruby SDK 则通过 `snapshot` 字段在创建时直接引用已注册快照名称。

`资料来源：[libs/sdk-go/README.md:88-100]()`、`[libs/sdk-python/README.md:48-55]()`

### 快照的应用场景

- **AI 代理的运行环境预热**：在沙箱中安装依赖、配置工具链后保存为快照，后续 Agent 任务可直接挂载运行。
- **可复现的基准环境**：将评测用的固定环境封装为快照，保证实验一致性。
- **多语言开发环境**：根据 `language` 字段加载对应语言工具链的快照。

`资料来源：[libs/sdk-typescript/README.md:54-60]()`、`[apps/api/src/sandbox/managers/snapshot.manager.ts]()`

## 持久化卷

持久化卷（Volume）独立于沙箱实例存在，由 `VolumeManager` 与 `VolumeService` 协作管理，实体定义见 `volume.entity.ts`。卷可以在沙箱之间共享，适合放置需要长期保留或被多个任务消费的数据集、模型权重、产物文件等。

### 挂载与访问

Go SDK 的 `examples/volumes` 示例覆盖了卷的创建、挂载与生命周期管理。卷以挂载点（mount path）的形式注入到沙箱文件系统，沙箱在运行期可读写其内容。

`资料来源：[libs/sdk-go/README.md:96-98]()`、`[apps/api/src/sandbox/managers/volume.manager.ts]()`

### 已知限制与社区诉求

社区中围绕卷展开的高频请求反映出当前实现的边界：

- **直接访问受限**：[#3413](https://github.com/daytonaio/daytona/issues/3413) 提出在沙箱未运行时（Detached）仍需上传/下载文件的需求。
- **只读挂载缺失**：[#3340](https://github.com/daytonaio/daytona/issues/3340) 希望为「消费者」沙箱提供 RO 卷模式，以安全共享脚本与数据集。
- **外部存储集成**：[#2486](https://github.com/daytonaio/daytona/issues/2486) 要求将 S3 等外部对象存储挂载进沙箱，避免应用层再管理一份持久化数据。

这些问题表明 Daytona 卷正从「沙箱附属存储」演进为「一等数据资源」，未来 API / CLI / SDK 需要为脱离实例的卷操作补充完整接口。

`资料来源：[apps/api/src/sandbox/services/volume.service.ts]()`、`[apps/api/src/sandbox/entities/volume.entity.ts]()`

## 架构关系

```mermaid
flowchart LR
    User[用户/Agent] -->|create/start/stop/delete| SM[SandboxManager]
    SM -->|provision| Runner[Runner / 容器运行时]
    Snap[SnapshotManager] -->|预置镜像| SM
    Vol[VolumeManager] -->|挂载/卸载| SM
    VolService[VolumeService] --> Vol
    Vol[(Volume 实体)] --> VolService
    Runner -->|挂载点| FS[(沙箱文件系统)]
```

## 总结

沙箱、快照与持久化卷共同构成 Daytona 的三大数据平面：**沙箱**定义运行时边界，**快照**加速环境预热，**卷**承载跨实例的持久数据。SDK 在 API 层把这三者封装为一致的 `create` / `mount` / `snapshot` 语义，而 `*Manager` 与 `*Service` 则是后端控制面的中枢。理解它们的职责边界，是构建可复用、低成本 AI 代码执行流水线的关键。

`资料来源：[apps/api/src/sandbox/services/sandbox.service.ts]()`、`[apps/api/src/sandbox/managers/sandbox.manager.ts]()`

## See Also

- [Daytona TypeScript SDK](https://github.com/daytonaio/daytona/blob/main/libs/sdk-typescript/README.md)
- [Daytona Python SDK](https://github.com/daytonaio/daytona/blob/main/libs/sdk-python/README.md)
- [Daytona Go SDK](https://github.com/daytonaio/daytona/blob/main/libs/sdk-go/README.md)
- [Daytona Ruby SDK](https://github.com/daytonaio/daytona/blob/main/libs/sdk-ruby/README.md)
- Issue #3413：卷的离线文件传输
- Issue #3340：只读卷挂载
- Issue #2486：外部对象存储挂载

---

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

## 部署模式与自托管运维

### 相关页面

相关主题：[平台概览与多面架构](#page-1), [沙箱生命周期、快照与持久化卷](#page-2)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [libs/sdk-python/README.md](https://github.com/daytonaio/daytona/blob/main/libs/sdk-python/README.md)
- [libs/sdk-typescript/README.md](https://github.com/daytonaio/daytona/blob/main/libs/sdk-typescript/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/toolbox-api-client-python/README.md](https://github.com/daytonaio/daytona/blob/main/libs/toolbox-api-client-python/README.md)
- [examples/otel-dashboards/grafana/README.md](https://github.com/daytonaio/daytona/blob/main/examples/otel-dashboards/grafana/README.md)
- [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)
- [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)
- [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)
</details>

# 部署模式与自托管运维

## 概述

Daytona 提供"托管云服务"与"自托管"两种部署形态。托管模式由官方 Dashboard（`app.daytona.io`）统一提供 API 与运行时；自托管模式则允许用户在自有 Kubernetes 集群中部署 API、Runner、Proxy 等核心组件，并可对接对象存储、镜像仓库等外部基础设施。资料来源：[libs/sdk-typescript/README.md](https://github.com/daytonaio/daytona/blob/main/libs/sdk-typescript/README.md)、[libs/sdk-go/README.md](https://github.com/daytonaio/daytona/blob/main/libs/sdk-go/README.md)。

## 客户端配置与环境变量

无论托管或自托管，SDK 客户端都通过环境变量与 Daytona 控制面通信。下表汇总了仓库中各官方 SDK 公开说明的常用变量：

| 变量名 | 用途 | 资料来源 |
|--------|------|----------|
| `DAYTONA_API_KEY` | API 鉴权密钥 | [libs/sdk-typescript/README.md](https://github.com/daytonaio/daytona/blob/main/libs/sdk-typescript/README.md) |
| `DAYTONA_API_URL` | 自定义 API 端点（自托管需覆盖） | [libs/sdk-typescript/README.md](https://github.com/daytonaio/daytona/blob/main/libs/sdk-typescript/README.md) |
| `DAYTONA_TARGET` | 区域（region）选择 | [libs/sdk-typescript/README.md](https://github.com/daytonaio/daytona/blob/main/libs/sdk-typescript/README.md) |

API 密钥应通过 Daytona Dashboard 生成；自托管部署时运维者通常将 `DAYTONA_API_URL` 指向自有 API 网关。资料来源：[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)。Toolbox API 客户端默认基址为 `http://localhost:22221`，用于沙箱内的工具调用。资料来源：[libs/toolbox-api-client-python/README.md](https://github.com/daytonaio/daytona/blob/main/libs/toolbox-api-client-python/README.md)。

## 可观测性与资源监控

仓库提供基于 OpenTelemetry 与 Grafana 的运维仪表盘样例，覆盖资源使用趋势、阈值告警与多服务聚合。资料来源：[examples/otel-dashboards/grafana/README.md](https://github.com/daytonaio/daytona/blob/main/examples/otel-dashboards/grafana/README.md)。

典型观测维度包括：CPU/内存/磁盘利用率（按服务与时间序列）、资源压力评分（融合三类指标的加权分）、以及"临界服务数量"（超过阈值的实例数）。仪表盘推荐时间窗口为 1m、5m、10m、30m、1h，运维者可根据告警粒度选用。资料来源：[examples/otel-dashboards/grafana/README.md](https://github.com/daytonaio/daytona/blob/main/examples/otel-dashboards/grafana/README.md)。

## 沙箱生命周期与资源治理

自托管运维需要显式管理"创建—执行—销毁"链路。各语言 SDK 的最佳实践保持一致：

1. 通过 `DAYTONA_API_KEY` 完成认证后调用 `create()`；
2. 显式指定 `Resources(cpu, memory, disk)` 控制配额；
3. 任务结束后 `defer` 或在 `finally` 中调用 `Delete()` 释放资源。

资料来源：[libs/sdk-go/README.md](https://github.com/daytonaio/daytona/blob/main/libs/sdk-go/README.md)（Best Practices / Resource Cleanup）、[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)。

对于"短生命周期"工作负载（如 Agent 任务），可通过 `ephemeral: true` + `autoStopInterval` 让沙箱在停止后自动销毁，降低自托管集群的稳态负载。资料来源：[libs/sdk-python/README.md](https://github.com/daytonaio/daytona/blob/main/libs/sdk-python/README.md)（Create an ephemeral sandbox）、[libs/sdk-ruby/README.md](https://github.com/daytonaio/daytona/blob/main/libs/sdk-ruby/README.md)。

## 已知问题与社区关注

社区中与自托管部署直接相关的高频议题：

- **#4232 K8s Self-Hosted Deployment Issues**：在基于 containerd 的 Kubernetes 集群上，Runner 无法连接 API。v0.187.0 Release Notes 未显式关闭该问题，运维者升级前应优先核查网络策略与证书配置。资料来源：社区 Issue #4232。
- **#2486 外部对象存储挂载**：用户希望将 S3 等外部存储直接挂载到沙箱，影响自托管存储后端选型。资料来源：社区 Issue #2486。
- **#3340 只读卷挂载（Read-Only Volume）**：让"消费方"沙箱只读访问共享数据集，是多租户自托管场景下的常见安全需求。资料来源：社区 Issue #3340。
- **#3413 Volume 直传/直下**：当前卷操作必须依附活动沙箱，社区希望提供"分离式"访问。资料来源：社区 Issue #3413。

最新版本 v0.187.0（2026-06-11）在 Proxy 侧暴露了 debug 指标端口（PR #5012），有助于自托管场景下的排障。资料来源：Release Notes v0.187.0、PR #5012。

## See Also

- [libs/sdk-typescript/README.md](https://github.com/daytonaio/daytona/blob/main/libs/sdk-typescript/README.md)
- [examples/otel-dashboards/grafana/README.md](https://github.com/daytonaio/daytona/blob/main/examples/otel-dashboards/grafana/README.md)
- [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)
- [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)

---

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

## SDK、CLI、API 表面与扩展集成

### 相关页面

相关主题：[平台概览与多面架构](#page-1), [沙箱生命周期、快照与持久化卷](#page-2), [部署模式与自托管运维](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/daytonaio/daytona/blob/main/README.md)
- [package.json](https://github.com/daytonaio/daytona/blob/main/package.json)
- [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/toolbox-api-client-python/README.md](https://github.com/daytonaio/daytona/blob/main/libs/toolbox-api-client-python/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)
- [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)
- [guides/typescript/anthropic/single-claude-agent-sdk/README.md](https://github.com/daytonaio/daytona/blob/main/guides/typescript/anthropic/single-claude-agent-sdk/README.md)
- [guides/typescript/openai/codex-sdk/agent/package.json](https://github.com/daytonaio/daytona/blob/main/guides/typescript/openai/codex-sdk/agent/package.json)
- [guides/typescript/vercel-ai-sdk/multi-language-benchmark-agent/README.md](https://github.com/daytonaio/daytona/blob/main/guides/typescript/vercel-ai-sdk/multi-language-benchmark-agent/README.md)
- [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)
- [guides/typescript/ai-data-analyst/openai/README.md](https://github.com/daytonaio/daytona/blob/main/guides/typescript/ai-data-analyst/openai/README.md)
- [guides/typescript/flue/README.md](https://github.com/daytonaio/daytona/blob/main/guides/typescript/flue/README.md)
</details>

# SDK、CLI、API 表面与扩展集成

## 1. 概述

Daytona 是一个面向 AI 生成代码运行场景的开源、安全、弹性基础设施，其对外暴露的程序化访问由三层表面组成：官方多语言 SDK、HTTP API 客户端（含 Toolbox），以及围绕沙箱（Sandbox）能力的 CLI 与 AI Agent 扩展集成。仓库根目录的 [README.md](https://github.com/daytonaio/daytona/blob/main/README.md) 描述了项目的整体定位与贡献入口，而 [package.json](https://github.com/daytonaio/daytona/blob/main/package.json) 中的 workspaces（`apps/*`、`libs/*`、`examples/*`、`guides/*`）表明 SDK、API 客户端与示例指南同源演化、共享构建与 lint 流水线。

社区反复提到的"不理解 Daytona 是什么、CLI 能做什么"（[#100](https://github.com/daytonaio/daytona/issues/100)）正是本页需要回答的核心问题：CLI 提供本地入口，SDK 提供编程入口，API 客户端与 Toolbox 提供底层 HTTP/协议入口，而 `guides/` 下的大量集成示例则把上述表面接到具体 AI 框架上。

## 2. 多语言 SDK 表面

### 2.1 TypeScript SDK

[`libs/sdk-typescript/README.md`](https://github.com/daytonaio/daytona/blob/main/libs/sdk-typescript/README.md) 描述了通过 `import { Daytona, Image } from '@daytona/sdk'` 入口创建沙箱的范式。典型用法包括：

```typescript
const sandbox = await daytona.create({
    image: Image.debianSlim('3.12'),
    resources: { cpu: 2, memory: 4, disk: 8 }
});
```

SDK 提供文件系统操作、Git 操作、LSP、进程执行与 Computer Use 五大子模块；通过 `DAYTONA_API_KEY`、`DAYTONA_API_URL`、`DAYTONA_TARGET` 等环境变量或配置对象驱动认证。

### 2.2 Python SDK

[`libs/sdk-python/README.md`](https://github.com/daytonaio/daytona/blob/main/libs/sdk-python/README.md) 同样覆盖沙箱生命周期、文件系统、Git、LSP 与执行能力。其内部采用 async/sync 双轨实现：`src/daytona/_sync/` 由 `_async/` 通过 `scripts/` 中的脚本生成，开发者不应直接修改同步代码。

### 2.3 Go 与 Ruby SDK

[`libs/sdk-go/README.md`](https://github.com/daytonaio/daytona/blob/main/libs/sdk-go/README.md) 通过 `go run examples/...` 形式给出 sandbox、filesystem、git_operations、fromimage、code_interpreter、lsp_usage、pty_interactive、snapshots、volumes 等示例；README 强调用 `defer sandbox.Delete(ctx)` 做资源清理，并检查 `result.ExitCode`。

[`libs/sdk-ruby/README.md`](https://github.com/daytonaio/daytona/blob/main/libs/sdk-ruby/README.md) 给出 `Daytona::Daytona.new`、`CreateSandboxFromImageParams`、`Resources`、`CreateSandboxFromSnapshotParams` 等 DSL 入口，并支持 `ephemeral: true` + `auto_stop_interval: 5` 创建短暂沙箱。

## 3. API 客户端与 Toolbox API

[`libs/toolbox-api-client-python/README.md`](https://github.com/daytonaio/daytona/blob/main/libs/toolbox-api-client-python/README.md) 暴露了一组独立于 Daytona Core API 的 Computer Use HTTP 接口，路径前缀 `http://localhost:22221`。下表摘自该 README，覆盖鼠标、键盘、进程与截图等能力。

| Class | Method | HTTP 路径 | 说明 |
| --- | --- | --- | --- |
| ComputerUseApi | click | POST /computeruse/mouse/click | 鼠标点击 |
| ComputerUseApi | press_key | POST /computeruse/keyboard/key | 按键 |
| ComputerUseApi | take_compressed_screenshot | GET /computeruse/screenshot/compressed | 压缩截屏 |
| ComputerUseApi | start_computer_use | POST /computeruse/start | 启动 Computer Use 进程 |

Toolbox 是 GUI/桌面自动化场景的补充表面，常与 TypeScript SDK 中的 Computer Use 模块协同使用。

## 4. 扩展集成生态（AI Agent 指南）

`guides/typescript/` 下的多个子项目演示了把 SDK 表面接入不同 Agent 框架的范式，构成"扩展集成"层：

- **CopilotKit Generative-UI**：`guides/typescript/copilotkit/generative-ui-coding-agent/README.md` 展示以 Daytona Sandbox 为后端的 CopilotKit Agent，将 shell、文件、目录、grep 与托管进程以 Generative-UI 卡片渲染。
- **Anthropic Claude Agent SDK**：`guides/typescript/anthropic/multi-agent-claude-sdk/README.md` 与 `single-claude-agent-sdk/README.md` 演示通过 `<developer_task>` 标签委派任务的 Project Manager + Developer 双 Agent 模式。
- **OpenAI Codex SDK**：`guides/typescript/openai/codex-sdk/agent/package.json` 声明 `@openai/codex-sdk ^0.77.0` 与 `tsx`，作为最小代码生成 Agent 模板。
- **Vercel AI SDK**：`guides/typescript/vercel-ai-sdk/multi-language-benchmark-agent/README.md` 通过 `runCode / runCommand / writeFile / readFile / downloadFile` 五个互不重叠的工具实现多语言基准测试。
- **AgentKit + Inngest**：`guides/typescript/agentkit-inngest/coding-agent/anthropic/README.md` 演示在 Daytona 中自动创建 Web 应用、启动 dev server 并返回预览链接。
- **AI 数据分析师**：`guides/typescript/ai-data-analyst/openai/README.md` 将 sandbox 作为代码执行沙箱，结合 `gpt-5.1`/`gpt-4o` 生成可视化图表。
- **Flue TDD Agent**：`guides/typescript/flue/README.md` 把 TDD 流程编码为 markdown skill，并通过 `gh` 在 sandbox 内推送真实 PR。

```mermaid
flowchart LR
    A[CLI / 终端用户] --> B[Daytona Core API]
    C1[TypeScript SDK] --> B
    C2[Python SDK] --> B
    C3[Go SDK] --> B
    C4[Ruby SDK] --> B
    B --> D[Sandbox / Volume / Snapshot]
    E1[Toolbox API: Computer Use] --> D
    G1[CopilotKit / Claude / Codex / Vercel AI / AgentKit / Flue] --> C1
    G1 --> D
```

## 5. 失败模式与最佳实践

- **凭据缺失**：所有 SDK 均要求 `DAYTONA_API_KEY`；缺少时调用会在创建沙箱阶段失败。
- **资源泄露**：Go SDK README 明确要求 `defer sandbox.Delete(ctx)`，TypeScript/Python 等价用法为 `try/finally` 或上下文退出后调用 `delete()`。
- **自托管连通性**：社区 [#4232](https://github.com/daytonaio/daytona/issues/4232) 报告 K8s 自托管下 Runner 与 API 在 containerd 集群中无法连通，部署时需检查网络策略与 DaemonSet 配置。
- **存储边界**：当前 Volume 仅在 Sandbox 挂载时可用，社区 [#3413](https://github.com/daytonaio/daytona/issues/3413) 与 [#3340](https://github.com/daytonaio/daytona/issues/3340) 提出"分离访问"与"只读挂载"诉求；[#2486](https://github.com/daytonaio/daytona/issues/2486) 提议挂载 S3 等外部存储——这些限制在 API 表面层面目前尚未体现。

## See Also

- [Sandboxes 概览与生命周期](./sandboxes.md)
- [Volume 与 Snapshot 持久化](./volumes-and-snapshots.md)
- [自托管与 K8s 部署](./self-hosting.md)
- [Computer Use 与 Toolbox API](./computer-use-toolbox.md)

---

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

---

## Doramagic 踩坑日志

项目：daytonaio/daytona

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。

## 1. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:753490180 | https://github.com/daytonaio/daytona | README/documentation is current enough for a first validation pass.

## 2. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:753490180 | https://github.com/daytonaio/daytona | last_activity_observed missing

## 3. 安全/权限坑 · 下游验证发现风险项

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:753490180 | https://github.com/daytonaio/daytona | no_demo; severity=medium

## 4. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:753490180 | https://github.com/daytonaio/daytona | no_demo; severity=medium

## 5. 安全/权限坑 · 来源证据：CLI snapshot create with --context fails with "error checking bucket existence: Access Denied" after push-access ListBu…

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：CLI snapshot create with --context fails with "error checking bucket existence: Access Denied" after push-access ListBucket scoping (#4966)
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_43f2dcb000cd4c41bb01cae9aec0f048 | https://github.com/daytonaio/daytona/issues/5013 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

## 6. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:753490180 | https://github.com/daytonaio/daytona | issue_or_pr_quality=unknown

## 7. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:753490180 | https://github.com/daytonaio/daytona | release_recency=unknown

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