0%

OpenSandbox 学习 01:快速入门

AI Agent 正在把大模型的应用范围从对话扩展到实际工作。编程助手会修改代码、运行测试,数据分析助手会读取表格、执行 Python,浏览器助手会打开网页、填写表单。这些任务往往需要反复尝试:Agent 先执行一个操作,再根据结果决定下一步。要完成这样的工作,除了模型,还需要一套能运行程序、保存文件、返回执行结果的环境。

执行环境也带来了新的边界问题。Agent 可能生成有错误的代码,安装相互冲突的依赖,或者让一个进程长时间占用资源。如果多个任务和业务服务共用环境,一次试错就可能影响其他任务。沙箱的价值由此变得具体:为任务提供独立的工作环境,约束它能使用的资源和访问范围,并在任务结束后回收环境。隔离做到什么程度,则取决于底层运行时和部署配置。

AI 时代的 Sandbox

Docker 已经提供了容器、文件系统和资源限制,Kubernetes 则进一步解决了集群中的调度与容器管理。这些能力构成了沙箱的基础。不过,把它们接入 Agent 应用,还需要组织一套面向任务的使用流程。以数据分析为例,应用需要创建环境、等待环境可用、传入数据、执行脚本、收集输出、取回报告,最后清理资源。直接使用 Docker 或 Kubernetes 可以完成这些步骤,但应用需要自己处理相应的接口调用、状态检查和错误反馈。

OpenSandbox 把这些常见需求整理成一套沙箱服务:底层通过 Docker 或 Kubernetes 管理执行环境,上层通过统一的 API 和多语言 SDK 提供环境创建、命令执行、文件操作和生命周期管理。它的意义在于补齐容器基础设施与 Agent 应用之间的这一层,让开发者可以围绕“给任务一个环境,在里面完成工作”编写程序,减少每个应用重复维护执行环境的工作。

本文从本机 Docker 部署开始,用一个订单统计任务走完这条流程:把 CSV 和 Python 脚本上传到沙箱,计算不同品类的销售额,再把 JSON 报告带回本机。这个例子不依赖模型服务,便于先看清执行环境本身的工作方式;跑通之后,再沿着请求路径理解 SDK、管理服务和沙箱内部程序的分工。

项目与组件

核心架构

从整体上看,OpenSandbox 把 Agent 应用与底层执行环境连接起来。应用通过客户端接口发起操作,管理服务负责创建和回收沙箱,底层的 Docker 或 Kubernetes 提供运行环境;每个沙箱内部还有执行服务,负责接收命令、操作文件,并把结果返回给应用。

这里有两类职责。环境管理关心的是“任务在哪里运行”,任务执行关心的是“在环境里做什么”。创建一个沙箱和在沙箱中运行一段 Python,分别由不同的服务处理,整体关系如下:

1
2
3
4
5
环境管理路径
业务应用 → 客户端接口 → 管理服务 → Docker / Kubernetes → 沙箱

任务执行路径(本文的直连方式)
业务应用 → 客户端接口 → 沙箱内执行服务 → 任务进程 / 任务文件

一次任务会先经过环境管理这条路径:应用申请沙箱,管理服务调用运行时创建环境,再向客户端提供访问地址。环境可用后,命令和文件请求就发往沙箱的执行端点。本例采用直连方式,执行请求直接到达沙箱内部的服务;其他部署也可以通过网关路由这些请求。

这样的分工让管理服务专注于环境的创建、状态和回收,具体任务则在各自的沙箱内部执行。应用通过同一套客户端接口使用两类能力,无需自行拼接底层容器管理与任务执行的完整流程。

沙箱里既可以运行单个脚本,也可以运行完整的 Agent 程序。例如,将 Claude Code 启动在沙箱内,它就能在这个环境里调用模型、读写文件和执行命令;也可以让 Agent 运行在外部,仅把需要执行的任务交给沙箱。本文先用一个 Python 脚本演示沙箱的基本操作。

本文的组件

把这套架构放到本文的本机 Docker 部署中,各个位置就对应到下面这些具体组件。此时,一个沙箱就是一个 Docker 容器,客户端程序和管理服务都运行在宿主机上。

架构位置 组件 本文中的位置与职责
应用接入 Python SDK 由宿主机上的 main.py 调用,把创建、命令和文件操作转换为 API 请求
环境管理 管理服务(Lifecycle Server) 宿主机上的 FastAPI 服务,管理沙箱生命周期,调用运行时并返回访问地址
底层运行时 Docker 本机 Docker Engine,创建容器,提供进程、文件系统和资源限制
沙箱执行 execd 每个容器内部的 Go 程序,接收命令和文件请求,在沙箱内部完成操作

管理服务在项目中称为 Lifecycle Server,其中“生命周期”指一个环境从创建、使用到删除的过程。本文统一称它为“管理服务”。execd 则是沙箱中的执行服务:真正接到请求并运行 python /tmp/summarize.py 的就是它。认识了这两个角色,后面就可以沿着 “管理服务创建环境、execd 执行任务” 的路径阅读源码。

网络访问也有独立的组件配合这套架构:Ingress 负责外部请求进入沙箱时的路由,Egress 负责沙箱出站流量的策略控制。它们在部署到集群或需要限制网络访问时很有用。本文使用本机直连,也没有设置出站网络策略,因此不需要启动这两个组件。

本地部署

环境准备

本文在 Linux 上验证,使用 Docker Engine 28.5.1 和 uv 0.9.7。管理服务使用 Python 3.10.12,示例客户端使用 Python 3.12.12;项目要求 Python 3.10 或更高版本。

先确认当前用户能访问 Docker daemon,并且 uv 可用:

1
2
3
docker version
uv --version
python3 --version

docker version 应当同时显示 Client 和 Server。只有 Client 信息、随后出现连接错误时,需要先启动 Docker,或处理当前用户访问 Docker socket 的权限。macOS 和 Windows 可以使用 Docker Desktop,Windows 下的命令建议在 WSL2 中执行;下文的运行记录来自 Linux,不代表已经验证过所有桌面环境。

本文把管理 API 放在 127.0.0.1:18080。官方配置示例使用 8080,这里换一个端口,是为了方便与本机已有服务共存。管理服务、SDK 和 Docker daemon 均在同一台机器上,是后续地址配置的前提。

源码与依赖

本文对照的源码提交是 f500745f36d6。管理服务和 Python SDK 都从这个版本安装,execd 使用该版本 Docker 配置示例中的 opensandbox/execd:v1.1.0 镜像。文中的源码片段来自这个提交,实际执行结果记录在 ai_demo/opensandbox-quickstart/verification.json 中。下文涉及的源码与示例文件位置,均以仓库根目录为起点。

获取源码,并切换到本文对照的提交:

1
2
3
git clone https://github.com/opensandbox-group/OpenSandbox.git
cd OpenSandbox
git checkout f500745f36d6bfb0e9290324a7b125ac29428b98

将本文配套示例放到仓库根目录的 ai_demo/opensandbox-quickstart/ 下,主要文件如下:

1
2
3
4
5
6
7
8
9
ai_demo/opensandbox-quickstart/
├── prepare.py # 生成本地认证配置
├── sandbox.toml # 管理服务配置
├── pyproject.toml # 客户端依赖,指向本仓库 SDK
├── uv.lock # 客户端依赖锁文件
├── orders.csv # 五笔示例订单
├── summarize.py # 上传到沙箱运行的统计脚本
├── main.py # 在宿主机运行的调用程序
└── verification.json # 本文的实测记录

以下命令都从仓库根目录执行。分别安装管理服务和示例客户端的依赖:

1
2
uv sync --project server --locked --no-dev
uv sync --project ai_demo/opensandbox-quickstart --locked

这会建立两个独立的 Python 虚拟环境。示例的 pyproject.toml 通过本地路径引用 sdks/sandbox/python,因此后面阅读的 SDK 源码,就是示例实际调用的实现。

接着拉取示例需要的两个镜像:

1
2
docker pull python:3.12-slim
docker pull opensandbox/execd:v1.1.0
  • Docker 用 python:3.12-slim 创建沙箱容器,容器里自带 Python。
  • 管理服务从 opensandbox/execd:v1.1.0 中取出 execd 和启动脚本,再复制到这个沙箱容器里。

最终,Python 和 execd 都在同一个沙箱容器中:execd 接收执行请求,再调用 Python 运行统计脚本。 镜像与容器的关系,以及运行时的调用路径如下:

1
2
3
4
5
6
7
8
9
10
11
12
13
python:3.12-slim
|
| Docker creates container
v
+--------------------------------------+
| Sandbox container |
| Python runtime |
| execd + bootstrap.sh | <-- Management Service copies -- opensandbox/execd:v1.1.0
+--------------------------------------+

main.py + Python SDK -- lifecycle --> Management Service -- Docker API --> Docker Engine
|
+-- commands / files --> execd (inside sandbox) --> Python process

图中的 Management Service 表示管理服务。客户端和管理服务运行在宿主机各自的 Python 虚拟环境中;执行统计任务的 Python 进程则运行在沙箱容器里。

管理服务配置

启动前需要准备两部分配置:.env 保存认证密钥和客户端连接地址,sandbox.toml 设置服务监听地址、运行时和沙箱网络。先运行配套脚本,生成 .env:

1
python3 ai_demo/opensandbox-quickstart/prepare.py

它生成一段随机密钥,并保存到示例目录下的 .env。这个文件不会被 Git 跟踪,脚本也不会把密钥打印到终端;再次运行时会保留已有配置。

文件里有三个变量:

变量 使用方 含义
OPENSANDBOX_SERVER_API_KEY 管理服务 管理服务接受的认证密钥
OPEN_SANDBOX_API_KEY Python SDK 客户端发送的同一段密钥
OPEN_SANDBOX_DOMAIN Python SDK 本例为 127.0.0.1:18080,不带 http://

前两个变量的拼写不同,值需要相同。它们用于 OpenSandbox 自身的认证,与模型服务的密钥没有关系。SDK 的协议默认是 HTTP,因此这里的 domain 只填主机和端口。

认证信息准备好后,再看管理服务配置。配套的 sandbox.toml 中,核心配置如下,完整文件还包含本地存储路径:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
[server]
host = "127.0.0.1"
port = 18080
max_sandbox_timeout_seconds = 3600

[runtime]
type = "docker"
execd_image = "opensandbox/execd:v1.1.0"

[docker]
network_mode = "bridge"
publish_host = "127.0.0.1"
port_range_min = 40000
port_range_max = 60000

[ingress]
mode = "direct"

server.host 决定管理 API 监听在哪里,docker.publish_host 决定沙箱端口发布在哪里。它们是两项独立设置,本例都绑定到本机回环地址。Docker 的 bridge 网络让多个沙箱能够复用相同的容器内端口,再映射到不同的宿主机端口。

管理服务启动

在第一个终端中加载环境变量,并启动管理服务:

1
2
3
4
5
6
set -a
source ai_demo/opensandbox-quickstart/.env
set +a

uv run --project server --no-dev opensandbox-server \
--config ai_demo/opensandbox-quickstart/sandbox.toml

set -a 会让加载的变量被后续进程继承。这个终端保持运行,看到 Application startup complete 和 http://127.0.0.1:18080 后,再打开第二个终端,回到同一个仓库根目录:

1
curl -fsS http://127.0.0.1:18080/health

本次返回:

1
{"status":"healthy"}

这说明管理服务已经启动,但还没有证明沙箱能执行命令。/health 本身也不要求 API Key,接下来仍要用真实的沙箱任务验证 Docker、execd 和文件接口。

订单统计示例

输入与产物

我们准备了五笔订单,按“数量 × 单价”计算销售额:

1
2
3
4
5
6
order_id,category,quantity,unit_price
A001,books,2,39.90
A002,coffee,3,25.00
A003,books,1,59.00
A004,stationery,5,8.50
A005,coffee,2,30.00

任务的输入是这份 CSV 和统计脚本,产物是 report.json。统计脚本只使用 Python 标准库,因此沙箱启动后不用再安装依赖。统计脚本位于 ai_demo/opensandbox-quickstart/summarize.py,其中计算和报告生成的主要部分是:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
totals: dict[str, Decimal] = defaultdict(Decimal)
order_count = 0
with Path("/tmp/orders.csv").open(encoding="utf-8", newline="") as source:
for row in csv.DictReader(source):
totals[row["category"]] += int(row["quantity"]) * Decimal(row["unit_price"])
order_count += 1

report = {
"order_count": order_count,
"total_amount": str(sum(totals.values(), Decimal("0.00"))),
"by_category": {
category: str(amount) for category, amount in sorted(totals.items())
},
}

计算完成后,脚本把报告写到沙箱里的 /tmp/report.json。注意,这个 /tmp 属于容器,和宿主机的 /tmp 不是同一个目录;示例通过文件 API 显式传入输入、取回输出,没有挂载宿主机目录。

客户端流程

客户端程序位于 ai_demo/opensandbox-quickstart/main.py,在宿主机上负责串起整个任务。创建沙箱时,它指定 Python 镜像、资源限制和存活时间:

1
2
3
4
5
6
7
8
9
sandbox = await Sandbox.create(
"python:3.12-slim",
connection_config=ConnectionConfig(
domain=os.environ.get("OPEN_SANDBOX_DOMAIN", "127.0.0.1:18080"),
),
resource={"cpu": "1", "memory": "512Mi"},
timeout=timedelta(minutes=5),
ready_timeout=timedelta(seconds=60),
)

这里有两个时间概念。timeout 是远端沙箱的存活时长,本例五分钟后到期;ready_timeout 是 SDK 等待端点和健康检查就绪的预算,本例为六十秒。单个 HTTP 请求还受 ConnectionConfig.request_timeout 约束。把它们分开,才能判断超时发生在创建请求、就绪检查,还是沙箱生命周期。

随后,客户端把两个本地文件的内容写入沙箱:

1
2
3
4
5
6
7
8
9
10
await sandbox.files.write_files(
[
WriteEntry(
path=f"/tmp/{name}",
data=(DEMO_DIR / name).read_text(encoding="utf-8"),
mode=644,
)
for name in ("orders.csv", "summarize.py")
]
)

文件到位后,执行脚本并读取报告:

1
2
execution = await sandbox.commands.run("python /tmp/summarize.py")
content = await sandbox.files.read_file("/tmp/report.json")

实际结果

在第二个终端中,从仓库根目录执行:

1
2
3
4
5
6
set -a
source ai_demo/opensandbox-quickstart/.env
set +a

uv run --project ai_demo/opensandbox-quickstart \
python ai_demo/opensandbox-quickstart/main.py

本次运行输出如下。每次创建得到的沙箱 ID 都会不同:

1
2
3
4
5
6
7
8
9
10
11
12
sandbox: 6165fe04-0d41-4fa2-8a4a-4a3a09c2e1e2
{
"order_count": 5,
"total_amount": "316.30",
"by_category": {
"books": "138.80",
"coffee": "135.00",
"stationery": "42.50"
}
}
verified: output/report.json
sandbox destroyed

再查看保存到本机的报告:

1
cat ai_demo/opensandbox-quickstart/output/report.json

输入确实传进了容器,容器里的 Python 读取了输入并生成文件,客户端又把这个文件读了回来。示例还逐项比较了报告内容,因此 verified 表示结果与预期相符。

资源清理

报告需要在删除沙箱之前取回,因为它最初只存在于容器的文件系统中。示例用 finally 保证即使上传、执行或校验失败,也会尝试清理:

1
2
finally:
await sandbox.destroy()

这个方法的实现位于 sdks/sandbox/python/src/opensandbox/sandbox.py,核心逻辑是下面这几行,省略了文档字符串:

1
2
3
4
5
async def destroy(self) -> None:
try:
await self.kill()
finally:
await self.close()

kill() 终止远端沙箱,close() 只释放本地连接。退出 async with sandbox 也只会调用 close()。本文的一次性任务使用 destroy(),同时完成沙箱删除和连接清理。

请求背后的实现

到这里,已经有了一条完整的使用路径。接下来沿着刚才的几次调用看源码,就能理解这些能力分别放在哪一层,以及为什么普通 Python 镜像也能接收命令和文件请求。

管理服务

Sandbox.create() 首先调用管理 API。管理服务的创建路由位于 server/opensandbox_server/api/lifecycle.py,负责请求校验和规范化,然后把工作交给 sandbox_service.create_sandbox(request),不会在路由函数里直接操作 Docker。

server/opensandbox_server/services/factory.py 中的工厂函数根据 runtime.type 选择服务实现,注册关系如下:

1
2
3
4
implementations = {
"docker": DockerSandboxService,
"kubernetes": KubernetesSandboxService,
}

本例配置的是 docker,所以进入 DockerSandboxService。它检查参数、准备资源限制、创建和启动容器,并在指定了到期时间时安排回收。这里也能看出【统一 API】的具体含义:客户端调用管理接口,管理服务再把请求交给相应的运行时实现;不同运行时的功能支持范围仍需单独确认。

在本例的 Docker 部署中,管理服务启动容器后返回 Running 状态。此时容器里的 execd 可能还没准备好接收请求,因此 SDK 会继续做健康检查,确认它能够响应后,才返回可用的沙箱对象。

普通镜像与 execd

python:3.12-slim 原本没有 OpenSandbox 的 HTTP 服务。它之所以能接受 commands.run(),是因为管理服务在启动沙箱之前,把执行所需的程序安装进了容器。

负责这一步的是 DockerRuntimeMixin,源码位于 server/opensandbox_server/services/docker/runtime.py。_prepare_sandbox_runtime() 开头的两行是:

1
2
self._copy_execd_to_container(container, sandbox_id, platform)
self._install_bootstrap_script(container, sandbox_id, platform)

第一步从配置的 execd 镜像中提取程序,并放入目标容器的 /opt/opensandbox/;第二步安装同一镜像中的 bootstrap.sh。

创建容器时,server/opensandbox_server/services/docker/container_ops.py 中的容器操作代码把 Linux 容器的入口设置为这个启动脚本。于是一个沙箱里既有用户镜像提供的 Python,也有 OpenSandbox 提供的 execd。启动脚本负责拉起执行服务和配置的入口命令,而订单统计脚本是在之后收到命令请求时才运行。

沙箱里的 execd 来自 execd_image 指定的镜像。修改 components/execd/ 下的源码后,需要重新构建镜像,并更新这项配置,修改才会在新建的沙箱中生效。

沙箱连接

容器启动后,宿主机上的 SDK 需要连接到容器里的 execd,才能上传文件、执行命令。execd 默认监听容器内的 44772 端口,本例由 Docker 将它映射到宿主机的一个端口,供 SDK 访问。

SDK 会向管理服务查询 execd 的访问地址,再用这个地址发送命令和文件请求。这里涉及两个地址:

  • 管理服务的 127.0.0.1:18080:用于创建、查询和删除沙箱。
  • execd 的访问地址:由管理服务返回,用于操作沙箱里的命令和文件。

这也体现在 sdks/sandbox/python/src/opensandbox/sandbox.py 的 Sandbox._create_with_flow() 中。下面两行分别创建文件和命令操作的客户端,传入的都是同一个 execd_endpoint,也就是刚查到的 execd 地址:

1
2
filesystem_service=factory.create_filesystem_service(execd_endpoint),
command_service=factory.create_command_service(execd_endpoint),

拿到地址后,SDK 还会请求 execd 的 /ping 接口,等待它能够正常响应。默认情况下,Sandbox.create() 完成这些检查后才返回,接下来就可以调用 sandbox.files 和 sandbox.commands。

如果创建成功后一直等不到沙箱可用,除了查看容器日志,还要确认 SDK 能访问管理服务返回的 execd 地址。只检查管理服务的 18080 端口是否通畅是不够的。

执行与文件接口

地址确定后,commands.run() 会请求 execd 的命令接口。Go 侧的路由注册位于 components/execd/pkg/web/router.go,其中为 /command 路由组设置了处理函数:

1
command.POST("", withCode(func(c *controller.CodeInterpretingController) { c.RunCommand() }))

对应的 RunCommand() 位于 components/execd/pkg/web/controller/command.go,负责校验请求、调用执行器,并把输出和完成或错误事件写回响应。前台命令使用 SSE,也就是在一个 HTTP 响应中持续发送事件;SDK 再把这些事件整理成 logs.stdout、logs.stderr、error 等字段。

这解释了示例为什么要分别看输出和执行状态。stdout 是程序打印的内容,stderr 是错误输出流,两者都不能独自代表最终成功与否。对于需要长时间展示进度的任务,SDK 还支持输出回调;本文任务很短,直接读取收集后的结果即可。

文件操作同样落在 execd。路由中的 /files/upload 和 /files/download 分别处理上传和下载。因此 write_files() 是把文件内容传到沙箱,read_file() 是把沙箱文件读回调用方;它们不会自动共享宿主机目录,也不会替应用永久保存产物。

执行环境的边界

理解了组件分工,也就更容易判断哪些事情需要应用自己安排。

  • 运行依赖由镜像提供。 本例只用标准库,所以普通 Python 镜像就够了。如果任务需要 pandas、浏览器或系统工具,应选择或构建相应镜像;OpenSandbox 不会根据脚本自动推断并补齐所有依赖。
  • 沙箱内的 Agent 也需要模型配置。 如果将 Claude Code 等 Agent 程序运行在沙箱里,需要为它配置模型服务地址、认证信息,并确保沙箱能够访问模型服务。OpenSandbox 提供运行环境,模型请求由沙箱里的 Agent 发起。
  • 持久化需要明确设计。 本例在删除前把报告带回本机。需要长期保存的数据,可以由应用写入对象存储,或在合适的场景使用卷挂载,不能依赖临时容器一直存在。
  • 网络权限需要单独设置。 本例使用 bridge 网络,没有配置 network_policy,因此没有启用 Egress 策略限制,不能把“运行在沙箱里”理解为“默认禁止联网”。

本例使用普通 Docker 容器,与宿主机共享内核。CPU、内存限制和容器文件系统提供了执行边界,但不等于虚拟机隔离。面向不可信代码的部署,还需要结合威胁模型选择安全运行时、网络策略和宿主机权限。

故障定位

发生问题时,可以按“管理服务 → 容器创建 → execd 端点 → 任务内容”的顺序缩小范围。每一层的成功,只说明这一层已经工作。

现象 优先检查的位置
/health 无法访问 管理服务终端日志、18080 是否被占用、配置路径是否正确
创建请求返回 401 两个终端是否加载同一份 .env,管理服务与 SDK 的密钥值是否一致
镜像拉取失败 宿主机能否手动 docker pull,Docker daemon 的代理和镜像仓库连接
创建沙箱失败 管理服务日志中的 Docker 错误、当前用户的 Docker 访问权限、资源是否充足
就绪检查超时 容器是否仍在运行、execd 日志、返回的宿主机映射端口是否可达
execution.error 有值 logs.stderr、脚本和依赖,随后检查执行错误及退出码
本机找不到报告 客户端是否完成 read_file() 和本地写入,是否在读取前删除了沙箱

容器尚在运行时,可以用下面的命令查看状态和日志:

1
2
docker ps -a --filter 'name=sandbox-'
docker logs sandbox-<实际的沙箱ID>

如果要从另一台电脑运行 SDK,需要重新安排网络地址。本文的 127.0.0.1 只适用于本机调用;把 OPEN_SANDBOX_DOMAIN 改成远端地址,也不会同时改变管理服务返回的沙箱端点。远程部署应同时设计管理 API 和执行端点的可达性,再考虑 Ingress 等接入方式。

示例结束后,在启动管理服务的终端按 Ctrl+C 即可停止管理服务。正常任务已经通过 destroy() 删除沙箱,本机报告仍保留在 ai_demo/opensandbox-quickstart/output/。如果客户端被强制结束而来不及清理,应检查遗留沙箱,不要把退出客户端或停止管理服务当成主动删除远端环境的替代操作。

小结

Agent 要完成实际任务,需要能够运行程序、操作文件并返回结果的工作环境。Docker 和 Kubernetes 提供了底层运行能力,OpenSandbox 则在此之上组织沙箱的创建、使用和回收,通过 API 与 SDK 将这些能力交给应用。

本文通过本机 Docker 部署和一份订单表,走完了“创建沙箱、上传输入、执行脚本、取回报告、清理环境”的完整流程。沿着这次调用阅读源码,可以看到清晰的组件分工:SDK 组织客户端操作,管理服务管理环境,Docker 创建并运行容器,execd 在容器内部处理命令和文件请求。环境管理与任务执行各自有独立的请求路径,连接关闭与远端沙箱删除也有不同的含义。理解这些关系后,部署、使用和排查问题就能对应到具体的一层。