OpenSandbox 开源沙箱

需安装Node 插件

在 OpenSandbox 服务（Docker 或 Kubernetes）上运行沙箱。命令、文件和终端走 OpenSandbox 的 HTTP 接口。

安装

shell

abx provider install alibaba-agent-sandbox/awesome-providers//opensandbox --allow-unpinned --yes
python -m agent_sandbox.providers install registry:opensandbox --yes

使用

python

await Sandbox.create(provider="opensandbox", template="base")

需要. 一个能访问的 OpenSandbox 服务，默认 http://127.0.0.1:8080。

能力 10 项能力

沙箱

创建、连接、列出、销毁sandbox.lifecycle

调整存活时间sandbox.timeout

暂停与恢复sandbox.pause

执行

运行命令exec.run

流式输出exec.stream

进程列表与信号process.manage

交互终端pty

文件

读写、目录、重命名files.rw

目录监听files.watch · 不支持

上传下载 URLfiles.transfer · 不支持

代码

代码解释器code.interpret · 不支持

模板

读取模板templates.read · 不支持

构建模板templates.build · 不支持

网络与存储

端口访问 URLports.url

自定义域名ports.domain · 不支持

挂载存储storage.mount · 不支持

VPC 网络network.vpc · 不支持

会话

沙箱内命名命令sessions

调用这些能力会直接返回 E8004。

配置项

密钥只从该提供方自己的环境变量读取，不会转发极速版的密钥。

名称	环境变量	说明
`base_url`	`ABX_OPENSANDBOX_BASE_URL`	OpenSandbox 服务地址，例如 https://opensandbox.example.com（可带 /v1 后缀）。默认 http://127.0.0.1:8080
`api_key` 密钥	`ABX_OPENSANDBOX_API_KEY` `OPEN_SANDBOX_API_KEY`	API 密钥，以 OPEN-SANDBOX-API-KEY 请求头发送
`domain`	`ABX_OPENSANDBOX_DOMAIN` `OPEN_SANDBOX_DOMAIN`	服务的 host[:port]，base_url 的替代写法（与 protocol 配合使用）
`protocol`	`ABX_OPENSANDBOX_PROTOCOL` `OPEN_SANDBOX_PROTOCOL`	与 domain 配合使用的协议 · 默认值: `http`
`use_server_proxy`	`ABX_OPENSANDBOX_USE_SERVER_PROXY` `OPEN_SANDBOX_USE_SERVER_PROXY`	通过生命周期服务的代理访问沙箱（沙箱主机端口无法直连时使用） · 默认值: `false`
`default_image`	`ABX_OPENSANDBOX_DEFAULT_IMAGE`	模板为通用默认值 'base' 时使用的镜像 · 默认值: `python:3.12-slim`
`image_aliases`	`ABX_OPENSANDBOX_IMAGE_ALIASES`	模板短名称，以逗号分隔的 name=image 键值对 · 默认值: `code=opensandbox/code-interpreter:v1.1.0`
`entrypoint`	`ABX_OPENSANDBOX_ENTRYPOINT`	调用方未设置入口时使用的命令。默认值让通用镜像保持运行，以便 execd 提供执行和文件服务。为在 9000 端口提供服务的生成镜像设置为 "python3 commands.py"。除非改成其他命令，code-interpreter 镜像仍使用自己的运行时脚本。 · 默认值: `tail -f /dev/null`
`ready_timeout`	`ABX_OPENSANDBOX_READY_TIMEOUT`	等待新沙箱运行且 execd 响应的秒数 · 默认值: `60`
`registry_username`	`ABX_OPENSANDBOX_REGISTRY_USERNAME`	私有镜像仓库用户名（image.auth）
`registry_password` 密钥	`ABX_OPENSANDBOX_REGISTRY_PASSWORD`	私有镜像仓库密码
`network_policy`	`ABX_OPENSANDBOX_NETWORK_POLICY`	应用于每个新沙箱的 JSON 网络策略，如 {"defaultAction":"deny","egress":[{"action":"allow","target":"pypi.org"}]}
`platform`	`ABX_OPENSANDBOX_PLATFORM`	新沙箱的目标平台：linux/amd64、linux/arm64、windows/amd64 或 windows/arm64
`secure_access`	`ABX_OPENSANDBOX_SECURE_ACCESS`	请求安全访问（仅 Kubernetes 网关部署） · 默认值: `false`

文档

目录提供方，id 是 opensandbox。不是随 SDK 编译进去的。类型 node：一个 ES 模块（provider.mjs，无 npm 依赖），导出 create(kit)，宿主在进程内调用它的 EPP/1 方法（kit.epp.infra）。CLI 直接使用它，Python 以及之后的 Node、Go、Java SDK 通过本机引擎（abx provider engine serve）使用它。node provider.mjs 仍可在 stdio 上提供 EPP/1，供其他宿主使用。需要 node 在 PATH 里。

总说明：工作原理 · 安装

安装和调用

abx provider install alibaba-agent-sandbox/awesome-providers//opensandbox --allow-unpinned --yes   # 或 Python：python -m agent_sandbox.providers install registry:opensandbox --yes（索引上线后）
abx --provider opensandbox create

from agent_sandbox import Sandbox

sb = await Sandbox.create(provider="opensandbox", template="base", timeout=300)
print((await sb.commands.run("echo ok", timeout=30)).stdout)
await sb.kill()

template="base" 使用镜像 python:3.12-slim，入口是 tail -f /dev/null。带 : 或 / 的模板名按镜像 URI 使用。

配置

项	环境变量	默认
生命周期地址，不带 `/v1`	`ABX_OPENSANDBOX_BASE_URL`，别名 `OPENSANDBOX_BASE_URL`	`http://127.0.0.1:8080`
请求头 `OPEN-SANDBOX-API-KEY`	`ABX_OPENSANDBOX_API_KEY`，别名 `OPEN_SANDBOX_API_KEY`、`OPENSANDBOX_API_KEY`	不设置

也可以放在 provider_options 里。清单继承了 sandbox_api_key 和 sandbox_base_url，但适配器只有在通用键的值和 ABX_SANDBOX_API_KEY 不同时才采用它。极速版密钥不会被送去。

请求留在插件进程

插件模块（在宿主进程内）直接打 OpenSandbox 的 HTTP（生命周期）和 execd（命令的 SSE、文件、终端的 WebSocket）。终端需要 Node 22+ 的全局 WebSocket。另一个解释器里的 Sandbox.connect 会再向生命周期 API 取 execd 地址，然后执行命令；不依赖创建进程留在内存里的会话。

能力	引擎对后端
`sandbox.lifecycle`	`POST` / `GET` / `DELETE /v1/sandboxes`
`sandbox.timeout`	`POST /v1/sandboxes/{id}/renew-expiration`
`sandbox.pause`	`POST …/pause` 和 `…/resume`
`exec.run`、`exec.stream`	execd `POST /command`（SSE）
`process.manage`	没有进程接口。列表读 `/proc`，信号用 `kill`。`commands.send_input` 是 `E8004`
`pty`	`POST /pty`，WebSocket `/pty/{id}/ws`
`files.rw`	execd `/files` 和 `/directories`
`ports.url`	`GET /v1/sandboxes/{id}/endpoints/{port}`

会抛出 E8004 的调用

files.watch、files.transfer、templates.read、templates.build、ports.domain、storage.mount、network.vpc、sessions、code.interpret。

POST /code 只有带 Jupyter 的 code-interpreter 镜像才有。默认的 python:3.12-slim 没有，所以代码解释器不声明。POST /session 那种有状态 shell 也没接。

实测

2026-10-14，本机 OpenSandbox 1.1.1（127.0.0.1:8080，Docker，opensandbox/execd:latest）：创建、列表、删除、续期、暂停后恢复、命令、流式输出、/proc 进程列表、终端 echo $((40+2))、文件往返、端口 URL 都有真实返回。另一个解释器里的 Sandbox.connect 再执行 echo fresh-exec-ok 也返回了。同一天的能力对照表在 SDK 文档 python-sdk/docs/zh/design/provider-opensandbox-mapping.md。

English

Catalog provider, id opensandbox, kind node: an ES module (provider.mjs, no npm dependencies) that exports create(kit); the host calls its EPP/1 methods in process (kit.epp.infra). The CLI uses it directly; the Python SDK and the Node, Go and Java SDKs use it through the local engine (abx provider engine serve). node provider.mjs still serves EPP/1 on stdio for other hosts. node must be on PATH.

abx provider install alibaba-agent-sandbox/awesome-providers//opensandbox --allow-unpinned --yes   # or, Python only once the index is live: python -m agent_sandbox.providers install registry:opensandbox --yes

template="base" is the image python:3.12-slim with entrypoint tail -f /dev/null. A template name that contains : or / is used as an image URI.

Setting	Environment	Default
Lifecycle origin, no `/v1`	`ABX_OPENSANDBOX_BASE_URL`, also `OPENSANDBOX_BASE_URL`	`http://127.0.0.1:8080`
Header `OPEN-SANDBOX-API-KEY`	`ABX_OPENSANDBOX_API_KEY`, also `OPEN_SANDBOX_API_KEY`, `OPENSANDBOX_API_KEY`	unset

The plugin module (in the host process) talks to the OpenSandbox lifecycle API and to each sandbox's execd (command SSE, files, the terminal WebSocket). The terminal needs the global WebSocket of Node 22+. Sandbox.connect in a second interpreter asks the lifecycle API for the execd address and can run a command; it does not need the session object kept by the process that created the sandbox.

Declared: sandbox.lifecycle, sandbox.timeout, sandbox.pause, exec.run, exec.stream, process.manage, pty, files.rw, ports.url. commands.send_input is E8004 because /command has no stdin. code.interpret is E8004 because POST /code exists only on a Jupyter image.

On 2026-10-14 a local OpenSandbox 1.1.1 returned real results for create, list, kill, renew, pause/resume, exec, streaming, a /proc process list, a PTY echo, a file round-trip, and a port URL. Sandbox.connect in a second interpreter also ran echo fresh-exec-ok. The capability table is python-sdk/docs/en/design/provider-opensandbox-mapping.md.