OpenSandbox

InstallNode plugin

Run sandboxes on an OpenSandbox server (Docker or Kubernetes). Commands, files and a terminal work over the OpenSandbox HTTP API.

Install

shell

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

Use

python

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

Needs. A reachable OpenSandbox server. Default http://127.0.0.1:8080.

Capabilities 10 capabilities

Sandbox

Create, connect, list, killsandbox.lifecycle

Change lifetimesandbox.timeout

Pause and resumesandbox.pause

Execution

Run a commandexec.run

Stream outputexec.stream

List and signal processesprocess.manage

Interactive terminalpty

Files

Read, write, directories, renamefiles.rw

Watch a directoryfiles.watch · Not supported

Upload and download URLsfiles.transfer · Not supported

Code

Code interpretercode.interpret · Not supported

Templates

Read templatestemplates.read · Not supported

Build templatestemplates.build · Not supported

Network and storage

Port URLsports.url

Custom domainsports.domain · Not supported

Mount storagestorage.mount · Not supported

VPC networkingnetwork.vpc · Not supported

Sessions

Named commands in the sandboxsessions

Calling these returns E8004 immediately.

Configuration

Secrets are read only from the provider's own environment variables. The Express key is never forwarded.

Name	Environment variables	Description
`base_url`	`ABX_OPENSANDBOX_BASE_URL`	OpenSandbox server root, e.g. https://opensandbox.example.com (a trailing /v1 is accepted). Default http://127.0.0.1:8080
`api_key` Secret	`ABX_OPENSANDBOX_API_KEY` `OPEN_SANDBOX_API_KEY`	API key, sent as the OPEN-SANDBOX-API-KEY header
`domain`	`ABX_OPENSANDBOX_DOMAIN` `OPEN_SANDBOX_DOMAIN`	host[:port] of the server, an alternative to base_url (used with 'protocol')
`protocol`	`ABX_OPENSANDBOX_PROTOCOL` `OPEN_SANDBOX_PROTOCOL`	Scheme used with 'domain' · Default: `http`
`use_server_proxy`	`ABX_OPENSANDBOX_USE_SERVER_PROXY` `OPEN_SANDBOX_USE_SERVER_PROXY`	Reach sandboxes through the lifecycle server's proxy (needed when sandbox host ports are not routable from here) · Default: `false`
`default_image`	`ABX_OPENSANDBOX_DEFAULT_IMAGE`	Image used when the template is the generic default 'base' · Default: `python:3.12-slim`
`image_aliases`	`ABX_OPENSANDBOX_IMAGE_ALIASES`	Short template names, name=image pairs separated by commas · Default: `code=opensandbox/code-interpreter:v1.1.0`
`entrypoint`	`ABX_OPENSANDBOX_ENTRYPOINT`	Command used when the caller does not set an entrypoint. The default keeps a stock image alive so execd can serve exec and files. Set "python3 commands.py" for a generated image that serves port 9000. A code-interpreter image keeps its runtime script unless this is set to something else. · Default: `tail -f /dev/null`
`ready_timeout`	`ABX_OPENSANDBOX_READY_TIMEOUT`	Seconds to wait for a new sandbox to run and execd to answer · Default: `60`
`registry_username`	`ABX_OPENSANDBOX_REGISTRY_USERNAME`	Username for a private image registry (image.auth)
`registry_password` Secret	`ABX_OPENSANDBOX_REGISTRY_PASSWORD`	Password for a private image registry
`network_policy`	`ABX_OPENSANDBOX_NETWORK_POLICY`	JSON NetworkPolicy applied to every new sandbox, e.g. {"defaultAction":"deny","egress":[{"action":"allow","target":"pypi.org"}]}
`platform`	`ABX_OPENSANDBOX_PLATFORM`	Target platform for new sandboxes: linux/amd64, linux/arm64, windows/amd64 or windows/arm64
`secure_access`	`ABX_OPENSANDBOX_SECURE_ACCESS`	Request secure access (Kubernetes gateway deployments only) · Default: `false`

Documentation

目录提供方，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.