Get started

Pick one of three routes: the command line, Python code, or let the agent in your IDE call it over MCP. Every command can be copied as is; replace the values in angle brackets and keep secrets out of repositories, logs and chats.

Before you start

An API key for Alibaba Cloud Agent Sandbox Express Edition

The default provider is alicloud-express. Create the key in the Alibaba Cloud console.

Node.js 20+ (CLI and MCP)

Without Node you can download a single-file binary; see the install doc.

Python 3.10+ (Python SDK)

pip install agent-sandbox

Install
abx is an npm package. Single-file binaries exist for macOS, Linux and Windows.
shell
```
npm install -g @agent-sandbox/cli
abx --version
```
Set credentials
Use an environment variable, or let abx config set write ~/.abx/.env (mode 600). The CLI never reads E2B_API_KEY. The default region is cn-hangzhou.
shell
```
export ABX_SANDBOX_API_KEY="<YOUR_API_KEY>"
# or keep it on this machine only
abx config set sandbox_api_key <YOUR_API_KEY>
abx config set region cn-hangzhou
```
Create, run, destroy
base is the default template on Express. abx exec takes the command after --. Destroy when done so it stops using quota.
shell
```
abx create --template base
abx list
abx exec <sandbox-id> -- echo hello
abx kill <sandbox-id> --yes
```

Move files

Upload into the sandbox, download the result when it finishes.

shell

abx upload <sandbox-id> ./local.txt /home/user/local.txt
abx download <sandbox-id> /home/user/result.csv ./result.csv

Install
The core client is one package. For MCP, session persistence and the declarative decorator install agent-sandbox[all].
shell
```
pip install agent-sandbox
# or: pip install "agent-sandbox[all]"
```

Create and run

Sandbox.create(template="base") uses the built-in alicloud-express. async with destroys the sandbox on exit.

main.py

import asyncio
from agent_sandbox import Sandbox

async def main():
    async with await Sandbox.create(template="base") as sandbox:
        result = await sandbox.commands.run("echo hello")
        print(result.stdout)

        code = await sandbox.run_code("print(2 ** 10)")
        print(code.text)

        await sandbox.files.write("/tmp/data.txt", "content")
        print(await sandbox.files.read("/tmp/data.txt"))

asyncio.run(main())

Three ways to execute
commands.run runs a shell command, run_code runs the interpreter, run("name") calls a command registered in the template.

Switch provider

Install it first, then pass provider when you create. Do not pass one that is not installed.

shell

python -m agent_sandbox.providers install registry:opensandbox --yes

python

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

Install the CLI and set the key
The MCP server ships with abx and speaks STDIO.
shell
```
npm install -g @agent-sandbox/cli
export ABX_SANDBOX_API_KEY="<YOUR_API_KEY>"
```
Write the IDE config
Cursor, Claude and VS Code are supported. For other clients start the STDIO server with abx mcp start.
shell
```
abx mcp install --target cursor   # or claude, vscode
abx mcp start                     # STDIO server for any other client
```
Install the Agent Skill (optional)
A static SKILL.md that teaches Qoder, Claude Code, Cursor, Qwen Code and Codex how to operate Agent Sandbox. You do not need abx first.
shell
```
npx skills add agent-sandbox/agent-sandbox --skill agent-sandbox -a qoder -y
# swap qoder for claude-code, cursor, qwen-code or codex
```