Agent Sandbox Registry

python-sdk

Getting Started

中文

docs/en/guide/getting-started.md

Getting Started

This is the Client SDK: install it on your machine, create a sandbox, and use it. The service that starts inside the image is the Server SDK.

This tutorial covers the lifecycle from install through teardown.

Prerequisites

1. Installation

# Install the SDK
pip install agent-sandbox

# Install with all extras (recommended)
pip install "agent-sandbox[all]"

The abx CLI is not part of the Python package (there is no [cli] extra); it is a separate Node.js project, see Related: the abx CLI. The container-side runtime (agent_sandbox.server) is the separate agent-sandbox-server package (pip install agent-sandbox-server); agent-sandbox depends on it, so installing the client provides it too.

2. Configure the API Key

There are three ways to configure credentials. When a call actually needs the key, this is the order (highest first). The full table is in Configuration — Credential resolution.

Option 1: Code parameter (this call only)

from agent_sandbox.api.sandbox import Sandbox

sandbox = await Sandbox.create(api_key="your-api-key-here")

export ABX_SANDBOX_API_KEY="your-api-key-here"

Option 3: Persisted file (~/.abx/.env)

Used when neither the environment nor the project .env sets the key. The file is written by the abx CLI (abx config set sandbox_api_key your-api-key, permissions 600; see Related: the abx CLI) or edited by hand: ABX_SANDBOX_API_KEY=your-api-key.

3. Create Your First Sandbox

Using the SDK (async)

import asyncio
from agent_sandbox.api.sandbox import Sandbox

async def main():
    # Create a sandbox (default template: base, timeout: 300 seconds)
    sandbox = await Sandbox.create(template="base", timeout=300)
    print(f"Sandbox created: {sandbox.id}")
    print(f"Status: {sandbox.status.value}")

asyncio.run(main())

Using the SDK (sync)

from agent_sandbox.api.sandbox import Sandbox

sandbox = Sandbox.create_sync(template="base")
print(f"Sandbox ID: {sandbox.id}")

4. Execute Code

SDK

result = await sandbox.run_code("print('Hello, Agent Sandbox!')")
print(result.text)     # "Hello, Agent Sandbox!"
print(result.stdout)   # "Hello, Agent Sandbox!\n"
print(result.exit_code)  # 0

5. Run Shell Commands

SDK

result = await sandbox.commands.run("ls -la /home/user")
print(result.stdout)
print(f"Exit code: {result.exit_code}")

6. File Operations

Upload files to the sandbox

# Write a text file
await sandbox.files.write("/home/user/hello.py", "print('hello world')")

# Upload a local file
await sandbox.files.upload("./local_script.py", "/home/user/script.py")

Download files from the sandbox

# Read text
content = await sandbox.files.read("/home/user/hello.py")
print(content)

# Download to local
await sandbox.files.download("/home/user/output.csv", "./output.csv")

7. List Directory Contents

files = await sandbox.files.list("/home/user")
for f in files:
    print(f"{f.name} ({f.type.value}, {f.size} bytes)")

8. Destroy a Sandbox

SDK

await sandbox.kill()

async with await Sandbox.create(template="base") as sandbox:
    result = await sandbox.run_code("print('auto cleanup')")
    print(result.text)
# Automatically destroyed after exiting the with block

9. Complete Example

import asyncio
from agent_sandbox.api.sandbox import Sandbox

async def main():
    async with await Sandbox.create(template="base") as sandbox:
        # Install dependencies
        await sandbox.commands.run("pip install requests")

        # Execute code
        result = await sandbox.run_code("""
import requests
resp = requests.get('https://httpbin.org/get')
print(resp.status_code)
""")
        print(f"Status code: {result.text}")

        # Write and read files
        await sandbox.files.write("/home/user/note.txt", "Hello!")
        content = await sandbox.files.read("/home/user/note.txt")
        print(f"File content: {content}")

asyncio.run(main())

The sandbox server can also host coding-agent CLIs. Codex (codex, npm package @openai/codex) and Qwen Code (qwen, npm package @qwen-code/qwen-code) are supported today, on /v1/agents/sessions, after ABX_SERVER_ENABLED_GROUPS includes agents. See Hosted agents.

Next Steps

The command-line equivalents of the steps above (installing abx with npm or as a standalone binary, abx config set, abx create, abx exec, abx upload / download, abx kill) are in the CLI repository: Getting Started (CLI), Binary Installation, CLI Tutorial and Using Templates.