Help

This page says what each provider status on a template page means, and what works today. Replace angle brackets with your own values. Never commit secrets.

Catalog providers do not declare templates.build. On the default provider, Express, abx template deploy builds and registers this directory. If --provider is a catalog provider, deploy stops with E8004 before Docker or a registry push. Provider-side template deploy is planned, not implemented: Provider template deploy.

Packages

The Python SDK is python-sdk, version 0.3.0, two distributions:

Distribution	Import	Role
`agent-sandbox-client`	`agent_sandbox`	Client SDK
`agent-sandbox-server`	`agent_sandbox.server`	Runtime inside the image (`agent-sandbox-server` on `PATH`)

Neither name is on PyPI yet. Until then, install both from the python-sdk commit 35da216a300f1e2e84254a1cf4b4a7ea98681505:

pip install "agent-sandbox-server @ git+https://github.com/Alibaba-Agent-Sandbox/python-sdk@35da216a300f1e2e84254a1cf4b4a7ea98681505#subdirectory=server-sdk" "agent-sandbox-client @ git+https://github.com/Alibaba-Agent-Sandbox/python-sdk@35da216a300f1e2e84254a1cf4b4a7ea98681505#subdirectory=client-sdk"

pip install agent-sandbox-client is coming. Do not run pip install agent-sandbox. That name is an unrelated project.

abx 0.3.0 is the v0.3.0 release. macOS and Linux:

curl -fsSL https://raw.githubusercontent.com/Alibaba-Agent-Sandbox/agent-sandbox/main/install.sh | sh

Windows (PowerShell):

irm https://raw.githubusercontent.com/Alibaba-Agent-Sandbox/agent-sandbox/main/install.ps1 | iex

Install a catalog provider

Express is the only built-in provider. opensandbox, e2b, cubesandbox, and alicloud-container are runtime.kind = "node" (provider.mjs) in awesome-providers. Install from that git tree:

abx provider install alibaba-agent-sandbox/awesome-providers//<id> --allow-unpinned --yes

--allow-unpinned is required without a terminal because main moves. Pin with --ref <40-hex-commit> instead. Files land in ~/.abx/providers/<id>. There is no install hook. abx provider list shows them. The CLI loads the module in its Node process. The Python SDK reaches it through the local engine (abx provider engine serve), so abx must be on PATH or named by ABX_BIN.

The Python installer reads this site's index, /providers/index.json. abx has no registry: form.

python -m agent_sandbox.providers install registry:<id> --yes

That command is agent-sandbox-client. It is not on PyPI yet; use the git install above. ABX_PROVIDER_REGISTRY overrides the index URL. Install docs: awesome-providers/docs/en/install.md.

alicloud-express

The status "Deploys on Express" means this directory can be built and registered here.

abx template deploy ./<name> -y --alias <name>
abx create --template <name>

Deploy prints a platform template id. --alias <name> also stores the manifest under that name, so abx create --template <name> and abx create --template <TemplateID> both work. Without --alias, create with the id deploy printed, not the directory name. abx --json template deploy <dir> -y prints one JSON object; the id field is TemplateID. abx deploy is the same pipeline.

base in template.yaml may be an image string or { image: ... }. On Express, a directory that has commands.py and does not set generation is published as generation 2. The provider start and ready commands are:

agent-sandbox-server serve --port 9000 --commands /home/user/app/commands.py
agent-sandbox-server healthcheck --port 9000

--start-cmd and --ready-cmd apply only with generation 2. The image does not set CMD or ENTRYPOINT; the platform runs the start command. agent-sandbox-server is not on PyPI.

abx template install alibaba-agent-sandbox/awesome-templates//<name> still downloads that directory and runs the same deploy. Create still uses the platform TemplateID, or the --alias you passed.

Express reads one environment name per credential:

Name	Use
`ABX_SANDBOX_API_KEY`	API key
`ABX_SANDBOX_BASE_URL`	API origin
`ABX_SANDBOX_DOMAIN`	Port hostnames
`ALICLOUD_ACCESS_KEY_ID`	AccessKey ID, for template deploy
`ALICLOUD_ACCESS_KEY_SECRET`	AccessKey secret
`ALIBABA_CLOUD_REGION_ID`	Region, default `cn-hangzhou`

It does not read E2B_API_KEY, ALIBABA_CLOUD_ACCESS_KEY_ID, ALIBABA_CLOUD_ACCESS_KEY_SECRET, AccessKey, or AccessSecret. Dockerfile mode also needs an ACR namespace: --acr-namespace or ACR_NAMESPACE.

Deploy guide: docs/en/guide/deploy-and-build.md.

alicloud-container

The status "Existing template id" means this directory is not registered on the cluster. The manifest does not declare templates.read or templates.build. Pass a template id the sandbox-manager already has. The provider's example is code-interpreter, not Express base.

abx --provider alicloud-container create --template <template id in the cluster>

await Sandbox.create(
    provider="alicloud-container",
    template="<template id in the cluster>",
)

Name	Use
`ABX_ALICLOUD_CONTAINER_DOMAIN`	Required, unless `ABX_ALICLOUD_CONTAINER_BASE_URL` is set
`ABX_ALICLOUD_CONTAINER_API_KEY`	`X-API-Key`. Required
`ABX_ALICLOUD_CONTAINER_BASE_URL`	Optional API origin
`ABX_ALICLOUD_CONTAINER_PROTOCOL`	`native` (default) or `private`

It does not read ABX_SANDBOX_API_KEY. pty is not declared.

cubesandbox

Same limit: no templates.build. Pass a template id that already exists on CubeAPI. Do not assume base exists. The default API is http://127.0.0.1:3000 and the default domain is cube.app.

await Sandbox.create(
    provider="cubesandbox",
    template="<template id on the cluster>",
)

ABX_CUBESANDBOX_API_KEY is optional. When it is unset, no auth header is sent. Also read: ABX_CUBESANDBOX_BASE_URL, ABX_CUBESANDBOX_DOMAIN, ABX_CUBESANDBOX_PROXY. Not ABX_SANDBOX_API_KEY.

pty is not declared, and the host does not open one for this provider. The status "No PTY" means this template needs a terminal CubeSandbox does not provide.

e2b

No templates.build. Pass a template id that already exists in the E2B account. The provider docs use base as the example. This page does not list other public E2B template names; they are not in the provider manifest.

export ABX_E2B_API_KEY="<your E2B key>"
abx --provider e2b create --template base

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

Name	Default
`ABX_E2B_API_KEY`	unset, required
`ABX_E2B_BASE_URL`	`https://api.e2b.app`
`ABX_E2B_DOMAIN`	`e2b.app`

It does not read ABX_SANDBOX_API_KEY or E2B_API_KEY. pty is not declared. abx template deploy does not register a template on E2B.

opensandbox

The status "Image URI, not this directory" means OpenSandbox does not build this directory. It does not declare templates.build.

template="base" is the image python:3.12-slim with entrypoint tail -f /dev/null.
The only built-in short name is code, which is opensandbox/code-interpreter:v1.1.0.
A value that contains : or / is an image URI. Build and push that image to a registry the OpenSandbox server can pull, then pass the URI.
code-interpreter, desktop, playwright, and vscode are not short names.

await Sandbox.create(provider="opensandbox", template="base")
await Sandbox.create(
    provider="opensandbox",
    template="registry.example.com/<name>:1",
)

The default server is http://127.0.0.1:8080. The API key is optional. The manifest's names are ABX_OPENSANDBOX_BASE_URL and ABX_OPENSANDBOX_API_KEY, and the key also accepts OPEN_SANDBOX_API_KEY. The manifest does not list OPENSANDBOX_API_KEY or OPENSANDBOX_BASE_URL. pty is declared. code.interpret is not: the default image has no code-interpreter runtime.

The language links do not work

The "中文版 / English" links in a template README are in-page anchors. Chinese headings now keep their anchors, so after a refresh they jump within the same page.