daytona

什么是 Daytona

Daytona 为 AI Agent 提供完全可组合的计算机——沙箱。每个沙箱都是一个隔离的运行时环境，拥有自己的内核、文件系统、网络栈，以及专用的 vCPU、RAM 和磁盘。Agent 可以在沙箱内安装软件包、运行服务器、编译代码和管理进程。

沙箱基于符合 OCI 标准的镜像或快照构建。任何能在 Linux 上运行的语言或工具都可使用。

**范围：**此技能涵盖 Daytona Cloud（app.daytona.io）。

开始之前

编写任何 Daytona 代码之前，请先确认设置：

1. 是否已安装 SDK？ 检查用户所用语言对应的 Daytona SDK 是否已安装（例如，运行 pip show daytona，或检查 package.json 中是否包含 @daytona/sdk）。如果未安装，请安装。
2. 是否已设置 API 密钥？ 检查 Shell 环境或环境文件中的 DAYTONA_API_KEY。如果未设置，请告知用户需要 API 密钥，并指引他们前往 Daytona Dashboard > API Keys 创建密钥。

SDK 基础 — Python

安装

pip install daytona

创建客户端和沙箱

from daytona import Daytona

# Uses DAYTONA_API_KEY env var
daytona = Daytona()

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

from daytona import Daytona, CreateSandboxFromImageParams, Image, Resources

daytona = Daytona()

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

执行命令

exec 和 code_run 均会返回一个 ExecuteResponse，其中包含 .result（标准输出）和 .exit_code。 code_run 会在沙箱的语言运行时中执行（通过 language= 参数在创建时设置，默认为 "python"）。支持：python、typescript、javascript。

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

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

文件操作

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

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

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

沙箱生命周期

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

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

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

# Permanently remove
sandbox.delete()

使用 DaytonaError 封装 Daytona 调用以处理错误。对于异步操作，请使用 AsyncDaytona（异步上下文管理器）。完整的 Python SDK 参考请参阅 python-sdk/README.md。

SDK 基础 — TypeScript

TypeScript SDK（@daytona/sdk）与 Python API 相对应。主要区别：使用 executeCommand 代替 exec，使用 codeRun 代替 code_run，文件操作使用 uploadFile/downloadFile/listFiles，使用 DaytonaError 处理错误。使用 npm install @daytona/sdk 安装。

完整的 TypeScript SDK 参考和示例请参阅 typescript-sdk/README.md。

常见模式

自定义环境和快照

当用户需要在沙箱中使用特定软件包、工具或自定义 OS 时，可使用 Image 构建器定义自定义镜像。如果用户要创建多个采用相同配置的沙箱，可建议构建一个快照——快照会将依赖项预装到可复用的模板中，让后续沙箱启动更快，并且预先安装好所有内容。

**注意：**快照基于镜像定义构建，而不是从实时沙箱状态创建。你无法对正在运行的沙箱创建快照来捕获其当前文件系统。

使用 Image 构建器定义镜像：

from daytona import Image

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

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

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

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

import { Image } from '@daytona/sdk'

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

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

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

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

直接从镜像创建一次性沙箱：

from daytona import Daytona, CreateSandboxFromImageParams, Image

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

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

或者构建快照以供重复使用（如果要创建多个采用相同配置的沙箱，建议使用此方式）：

from daytona import Daytona, CreateSandboxFromSnapshotParams, CreateSnapshotParams, Image

daytona = Daytona()

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

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

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

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

完整的 Image 构建器 API 请参阅 ./references/<lang>-sdk/declarative-builder.md。快照管理请参阅 ./references/<lang>-sdk/snapshots.md。

长时间运行任务模式

from daytona import Daytona

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

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

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

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

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

预览 URL

沙箱通过预览 URL 提供 HTTP 服务。默认情况下，预览需要使用令牌进行身份验证；在创建沙箱时设置 public=True（Python）/ public: true（TypeScript）后，预览也可公开访问。

• 令牌身份验证 — 返回 .url 和 .token（通过 x-daytona-preview-token 标头发送）
  • Python：sandbox.get_preview_link(port) | TypeScript：sandbox.getPreviewLink(port) | Go：sandbox.GetPreviewLink(port) | Ruby：sandbox.get_preview_link(port)
• 签名 URL（可分享） — 令牌嵌入 URL 中，无需标头
  • Python：sandbox.create_signed_preview_url(port, expires_in_seconds=3600) | TypeScript：sandbox.getSignedPreviewUrl(port, 3600) | Go：sandbox.GetSignedPreviewLink(port, 3600) | Ruby：sandbox.create_signed_preview_url(port, expires_in_seconds: 3600)

详情请参阅 ./references/<lang>-sdk/preview.md。

沙箱限制与约束

约束	默认值	最大值
每个沙箱的 vCPU	1	4
每个沙箱的 RAM	1 GB	8 GB
每个沙箱的磁盘	3 GiB	10 GB

总额度（所有沙箱的 vCPU/RAM/磁盘总量）取决于组织等级：

等级	vCPU	RAM	存储	要求
等级 1	10	10 GiB	30 GiB	已验证邮箱
等级 2	100	200 GiB	300 GiB	信用卡 + $25 充值 + 已关联 GitHub
等级 3	250	500 GiB	2000 GiB	企业邮箱 + $500 充值
等级 4	500	1000 GiB	5000 GiB	每 30 天充值 $2000

资源状态的影响：

• 运行中的沙箱会占用 vCPU + RAM + 磁盘额度
• 已停止的沙箱仅占用磁盘额度
• 已归档的沙箱不占用额度（数据存储在冷存储中）

网络访问限制

等级 1 和等级 2 的组织受到网络访问限制。 沙箱只能访问必要服务的白名单（软件包注册表、Git 托管平台、AI API、CDN 等）。此限制无法在沙箱级别覆盖——即使设置 networkAllowList，如果组织属于等级 1/2，也不会生效。

等级 3 和等级 4 默认可不受限制地访问互联网，并可选用每个沙箱独立的防火墙控制。

如果代码需要访问任意 URL（外部 API、自定义服务等），则需要等级 3 及以上。可在 Daytona Dashboard > Limits 查看你的等级。

所有等级均可访问的必要服务包括：npm/PyPI/apt 注册表、GitHub/GitLab/Bitbucket、Docker 注册表、主要 AI API（Anthropic、OpenAI、Google AI 等）、S3、Google Cloud Storage，以及常见开发工具（Vercel、Supabase、Clerk、Sentry 等）。完整列表请参阅 network-limits.md。找不到所需服务？请在 daytonaio/sandbox-network-whitelist 提交申请。

可在 Daytona Dashboard > Limits 查看用量。完整详情请参阅 limits.md。

快速决策树

我需要……	从这里开始
在隔离环境中运行代码/命令	先阅读上文的 SDK 基础内容，然后查看 ./references/<lang>-sdk/process-code-execution.md
加快沙箱启动速度	./references/<lang>-sdk/snapshots.md — 根据镜像定义构建快照，并从快照创建新沙箱
在多次沙箱运行之间保留数据	./references/<lang>-sdk/volumes.md — 挂载持久存储，使其在沙箱删除后仍然保留
构建自定义环境（指定操作系统、软件包、依赖项）	./references/<lang>-sdk/declarative-builder.md — 使用 Image 构建器定义自定义沙箱镜像
控制沙箱可访问的网络内容	./references/<lang>-sdk/network-limits.md — 每个沙箱独立的防火墙规则（不受限制的访问需要等级 3 及以上）
在沙箱中使用浏览器或图形界面	./references/<lang>-sdk/computer-use-guide.md + ./references/<lang>-sdk/vnc-access.md
运行有状态的 Python 解释器（多次调用之间保留变量）	./references/python-sdk/sync/code-interpreter.md 或 ./references/typescript-sdk/code-interpreter.md
存储和检索对象（兼容 S3）	./references/<lang>-sdk/object-storage.md（Python 同步/异步、TypeScript、Ruby）
通过 SSH 连接正在运行的沙箱	./references/<lang>-sdk/ssh-access.md

将 <lang>-sdk 替换为：python-sdk、typescript-sdk、java-sdk、go-sdk 或 ruby-sdk。

SDK 索引

Python SDK（主要）

文件	描述
python-sdk/README.md	安装、快速入门、配置
python-sdk/sync/daytona.md	Daytona 客户端 — 创建、列出、删除沙盒
python-sdk/sync/sandbox.md	沙盒实例 — 生命周期、资源、标签
python-sdk/sync/process.md	执行命令、运行代码
python-sdk/sync/file-system.md	文件操作 — 读取、写入、上传、下载
python-sdk/sync/git.md	Git 操作 — 克隆、提交、推送、状态
python-sdk/sync/snapshot.md	快照管理
python-sdk/sync/volume.md	卷管理
python-sdk/sync/code-interpreter.md	有状态 Python 解释器
python-sdk/sync/computer-use.md	桌面自动化（鼠标/键盘/屏幕）
python-sdk/sync/lsp-server.md	语言服务器协议
python-sdk/sync/object-storage.md	兼容 S3 的对象存储
python-sdk/errors.md	错误类型
python-sdk/image.md	自定义镜像定义

异步版本与同步 API 相对应：python-sdk/async/。

TypeScript SDK

扁平结构（不像 Python 那样区分同步/异步）：typescript-sdk/README.md。文件：daytona.md、sandbox.md、process.md、file-system.md、git.md、snapshot.md、volume.md、code-interpreter.md、computer-use.md、lsp-server.md、object-storage.md、execute-response.md、pty-handle.md、errors.md、image.md。

Java SDK、Go SDK 和 Ruby SDK

它们都遵循相同的模式。Java 采用与 TypeScript 相同的扁平结构：java-sdk/README.md。Go 使用紧凑的单文件结构：go-sdk/README.md。Ruby 采用与 TypeScript 相同的结构：ruby-sdk/README.md。

功能指南（按 SDK 划分）

每个 SDK 文件夹都包含相同的一组功能指南，并附有特定语言的示例。查找指南时，请使用 ./references/<lang>-sdk/<filename>（例如，./references/python-sdk/sandboxes.md、./references/typescript-sdk/snapshots.md）。

文件名	主题
sandboxes.md	沙盒生命周期 — 创建、启动、停止、归档、删除
process-code-execution.md	运行命令和代码、有状态解释器
file-system-operations.md	读取、写入、上传、下载文件
git-operations.md	克隆、提交、推送、状态
snapshots.md	根据镜像定义构建可复用的沙盒模板
volumes.md	在多个沙盒之间持久存储
ssh-access.md	通过 SSH 连接沙盒
vnc-access.md	用于桌面沙盒的 VNC
computer-use-guide.md	桌面自动化（鼠标/键盘/屏幕）
declarative-builder.md	使用 Image builder 构建自定义沙盒镜像
log-streaming.md	流式传输沙盒日志
network-limits.md	网络防火墙控制
language-server-protocol.md	类似 IDE 的功能（自动补全、诊断）
preview.md	已公开端口的预览 URL
pty.md	PTY/终端支持
regions.md	可用区域
vpn-connections.md	VPN 连接

平台参考

文件	描述
limits.md	资源限制、速率限制、套餐要求
organizations.md	团队管理、成员角色
billing.md	用量跟踪、定价
audit-logs.md	审计日志记录
linked-accounts.md	GitHub/GitLab 账号关联
web-terminal.md	基于浏览器的终端访问
webhooks.md	Webhook 事件
mcp.md	MCP 集成
cli.md	CLI 命令参考

API 参考

所有 Daytona 端点（沙盒、快照、卷、工具箱操作等）的原始 REST API 文档：api/README.md。