app-platform-sandbox

Sandbox 技能

为 AI Agent 和测试工作流提供隔离的执行环境。

理念

Lambda/Functions: Fast cold start, 15-min limit, stateless, per-ms billing
App Platform Sandbox: 30s cold start (or instant with pool), unlimited duration, stateful, per-hour billing

Sweet spot: Long-running, stateful, iterative workflows where agents need to
install packages, run code, check results, modify, repeat.

快速决策

┌─────────────────────────────────────────────────────────────┐
│         Need isolated execution environment?                 │
└─────────────────────────────────────────────────────────────┘
                            │
              Is this for debugging an EXISTING app?
                            │
            ┌───────────────┴───────────────┐
            │                               │
           YES                              NO
            │                               │
            ▼                               ▼
   ┌─────────────────┐           ┌─────────────────┐
   │ troubleshooting │           │ Need real-time  │
   │ skill           │           │ streaming or    │
   │                 │           │ port exposure?  │
   │ Sandbox.get_    │           │                 │
   │ from_id()       │           └────────┬────────┘
   └─────────────────┘                    │
                          ┌───────────────┴───────────────┐
                          │                               │
                         YES                              NO
                          │                               │
                          ▼                               ▼
                 ┌─────────────────┐           ┌─────────────────┐
                 │ SERVICE MODE    │           │ Is low latency  │
                 │ exec_stream()   │           │ critical?       │
                 │ expose_port()   │           │                 │
                 └─────────────────┘           └────────┬────────┘
                                                        │
                                        ┌───────────────┴───────────────┐
                                        │                               │
                                       YES                              NO
                                        │                               │
                                        ▼                               ▼
                               ┌─────────────────┐           ┌─────────────────┐
                               │ HOT POOL        │           │ COLD SANDBOX    │
                               │ SandboxManager  │           │ Sandbox.create()│
                               │ ~50ms acquire   │           │ ~30s startup    │
                               └─────────────────┘           └─────────────────┘

---

前置条件

# Verify doctl is installed and authenticated
doctl auth whoami

# Install the SDK (choose one)
uv pip install do-app-sandbox
# OR
pip install do-app-sandbox

# For Spaces support (large file transfers)
pip install "do-app-sandbox[spaces]"

要求：

• Python 3.10.12+
• 已安装并完成身份验证的 doctl CLI
• 拥有 App Platform 访问权限的 DigitalOcean 账户

---

快速开始：冷沙箱

创建单个沙箱，启动时间约为 30 秒：

from do_app_sandbox import Sandbox

# Create sandbox with Python image
sandbox = Sandbox.create(
    image="python",           # or "node"
    name="my-sandbox",
    region="nyc",
    instance_size="apps-s-1vcpu-1gb"
)

# Execute code
result = sandbox.exec("python3 -c 'import sys; print(sys.version)'")
print(result.stdout)

# File operations
sandbox.filesystem.write_file("/tmp/script.py", "print('hello')")
result = sandbox.exec("python3 /tmp/script.py")

# Clean up
sandbox.delete()

完整指南：参见 cold-sandbox.md

---

快速开始：热池

预热沙箱，可立即获取：

import asyncio
from do_app_sandbox import SandboxManager, PoolConfig

async def main():
    # 1. Configure pool
    manager = SandboxManager(
        pools={"python": PoolConfig(target_ready=3)},
    )

    # 2. Start and warm up (blocks until pool is ready)
    await manager.start()
    await manager.warm_up(timeout=180)

    # 3. Acquire instantly (~500ms from pool vs 30s cold start)
    sandbox = await manager.acquire(image="python")
    result = sandbox.exec("python3 -c 'print(2+2)'")
    print(result.stdout)

    # 4. Delete when done - YOUR responsibility!
    sandbox.delete()

    # 5. Shutdown (cleans up pool, not acquired sandboxes)
    await manager.shutdown()

asyncio.run(main())

所有权模型： 调用 acquire() 获取沙箱后，该沙箱便归你所有。用完后务必调用 sandbox.delete()。shutdown() 只会清理仍在池中的沙箱。

完整指南：参见 hot-pool.md

---

快速参考：何时使用沙箱

场景	建议
AI 代码解释器	热池（即时响应）
多步 Agent 工作流	单个沙箱（状态在同一沙箱内持续保留）
一次性脚本测试	冷沙箱（简单）
CI 集成测试	冷沙箱（每个作业一个）
短任务（< 30s）	可考虑使用 Lambda
高并发（1000+）	可考虑使用 Lambda

---

快速参考：可用镜像

镜像	Registry	用途
python	ghcr.io/bikramkgupta/sandbox-python	Python 3.13、uv、pip
node	ghcr.io/bikramkgupta/sandbox-node	Node.js 24、nvm

工作目录：/home/sandbox/app（带有 /app 符号链接）。端口：8080（用户应用）、9090（健康检查）。

支持自定义镜像——任何具备 HTTP 服务器功能的 Docker 镜像均可。

---

快速参考：SDK 方法

方法	用途
Sandbox.create(image, mode=...)	创建沙箱（WORKER 或 SERVICE 模式）
Sandbox.get_from_id()	连接到现有应用
sandbox.exec(cmd)	运行 shell 命令
sandbox.exec_stream(cmd)	流式输出（SERVICE 模式）
sandbox.expose_port(port)	获取端口的公共 URL（SERVICE 模式）
sandbox.hibernate()	创建快照并删除，以节省成本
Sandbox.wake(hibernated)	恢复休眠的沙箱
sandbox.filesystem.read_file()	读取文件内容
sandbox.filesystem.write_file()	写入文件
sandbox.delete()	删除沙箱（用完后务必调用）
SandboxManager(pools={...})	配置热池
manager.start()	启动后台池管理
manager.warm_up(timeout)	阻塞至池达到目标数量（异步）
manager.acquire(image=...)	从池中获取沙箱（异步）
manager.acquire_with_snapshot()	获取带有预配置状态的沙箱
manager.shutdown()	拆除池（仅清理池中的沙箱）

---

参考文件

• cold-sandbox.md — 单个沙箱的生命周期、文件操作、清理
• hot-pool.md — 池管理、规模设置、成本优化
• service-mode.md — 流式输出、端口公开、AI Agent 模式
• use-cases.md — AI Agent 模式、测试模式
• positioning.md — Lambda 与 Sandbox 的选择指南

---

成本考量

Sandbox billing: ~$0.01-0.03/hour per container (apps-s-1vcpu-1gb)

Hot Pool trade-off:
- Pool of 5 sandboxes running 8 hours = ~$0.80-2.40/day
- Eliminates 30s cold start per request
- Worth it for interactive AI agents, not for batch jobs

---

与其他技能集成

方向	技能	时机
→	troubleshooting	调试现有沙箱（使用 Sandbox.get_from_id()）
→	designer	在应用规范中包含兼容沙箱的 worker
←	deployment	沙箱是独立运行的，不属于主应用部署的一部分