File: README.md Copy Chapter

AIO Sandbox - All-in-One Agent Sandbox Environment

🚀 Quick Start Copy Chapter

Get up and running in 30 seconds:

# Recommended: Enable API Key authentication (protects all services: API, JupyterLab, VNC)
# - Supports three methods: X-AIO-API-Key header, Authorization: Bearer header, ?api_key= query parameter
# - Without SANDBOX_API_KEY, services remain open (backward compatible)
docker run --security-opt seccomp=unconfined --rm -it \
  -e SANDBOX_API_KEY=your-secret-key \
  -p 127.0.0.1:8080:8080 ghcr.io/agent-infra/sandbox:latest

For users in mainland China:

docker run --security-opt seccomp=unconfined --rm -it \
  -e SANDBOX_API_KEY=your-secret-key \
  -p 127.0.0.1:8080:8080 enterprise-public-cn-beijing.cr.volces.com/vefaas-public/all-in-one-sandbox:1.11.0

For reproducible deployments, pin a release tag. Replace 1.11.0 with the release you want:

docker run --security-opt seccomp=unconfined --rm -it \
  -p 127.0.0.1:8080:8080 ghcr.io/agent-infra/sandbox:1.11.0
# or use the pinned mainland China mirror
docker run --security-opt seccomp=unconfined --rm -it \
  -p 127.0.0.1:8080:8080 enterprise-public-cn-beijing.cr.volces.com/vefaas-public/all-in-one-sandbox:1.11.0

These examples intentionally bind the host side to 127.0.0.1 because the sandbox listens on 0.0.0.0 inside the container. For cloud deployment, keep port 8080 private and publish it through a reverse proxy or Ingress: Cloud Deployment Guide.

Once running, access the environment at:

• 📖 Documentation: http://localhost:8080/v1/docs
• 🌐 VNC Browser: http://localhost:8080/vnc/index.html?autoconnect=true
• 💻 VSCode Server: http://localhost:8080/code-server/
• 🤖 MCP Services: http://localhost:8080/mcp

🎯 What is AIO Sandbox? Copy Chapter

AIO Sandbox is an all-in-one agent sandbox environment that combines Browser, Shell, File, MCP operations, and VSCode Server in a single Docker container. Built on cloud-native lightweight sandbox technology, it provides a unified, secure execution environment for AI agents and developers.

Why Choose AIO Sandbox? Copy Section

Traditional sandboxes are single-purpose (browser, code, or shell), making file sharing and functional coordination extremely challenging. AIO Sandbox solves this by providing:

• ✅ Unified File System - Files downloaded in browser are instantly available in Shell/File operations
• ✅ Multiple Interfaces - VNC, VSCode, Jupyter, and Terminal in one unified environment
• ✅ Secure Execution - Sandboxed Python and Node.js execution with safety guarantees
• ✅ Zero Configuration - Pre-configured MCP servers and development tools ready to use
• ✅ Agent-Ready - MCP-compatible APIs for seamless AI agent integration

📦 Installation Copy Chapter

SDK Installation Copy Section

| Python

pip install agent-sandbox
``` | **TypeScript/JavaScript**
```bash
npm install @agent-infra/sandbox
``` | **Golang**
```bash
go get github.com/agent-infra/sandbox-sdk-go
``` |
| --- | --- | --- |



### Basic Usage



| **Python Example**
```python
from agent_sandbox import Sandbox

# Initialize client
client = Sandbox(base_url="http://localhost:8080")
home_dir = client.sandbox.get_context().home_dir

# Execute shell commands
result = client.shell.exec_command(command="ls -la")
print(result.data.output)

# File operations
content = client.file.read_file(file=f"{home_dir}/.bashrc")
print(content.data.content)

# Browser automation
screenshot = client.browser.screenshot()
``` | **TypeScript Example**
```typescript
import { Sandbox } from '@agent-infra/sandbox';

// Initialize client
const sandbox = new Sandbox({ baseURL: 'http://localhost:8080' });

// Execute shell commands
const result = await sandbox.shell.exec({ command: 'ls -la' });
console.log(result.output);

// File operations
const content = await sandbox.file.read({ path: '/home/gem/.bashrc' });
console.log(content);

// Browser automation
const screenshot = await sandbox.browser.screenshot();
``` |
| --- | --- |



## 🌟 Key Features

### 🔗 Unified Environment
All components run in the same container with a shared filesystem, enabling seamless workflows:



### 🌐 Browser Automation
Full browser control through multiple interfaces:
- **VNC** - Visual browser interaction through remote desktop
- **CDP** - Chrome DevTools Protocol for programmatic control
- **MCP** - High-level browser automation tools



### 💻 Development Tools
Integrated development environment with:
- **VSCode Server** - Full IDE experience in browser
- **Jupyter Notebook** - Interactive Python environment
- **Terminal** - WebSocket-based terminal access
- **Port Forwarding** - Smart preview for web applications



### 🤖 MCP Integration
Pre-configured Model Context Protocol servers:
- **Browser** - Web automation and scraping
- **File** - File system operations
- **Shell** - Command execution
- **Markitdown** - Document processing



## 📚 Complete Example

Convert a webpage to Markdown with embedded screenshot:

```python
import asyncio
import base64
from playwright.async_api import async_playwright
from agent_sandbox import Sandbox

async def site_to_markdown():
    # Initialize sandbox client
    c = Sandbox(base_url="http://localhost:8080")
    home_dir = c.sandbox.get_context().home_dir

    # Browser: Automation to download HTML
    async with async_playwright() as p:
        browser_info = c.browser.get_info().data
        page = await (await p.chromium.connect_over_cdp(browser_info.cdp_url)).new_page()
        await page.goto("https://example.com", wait_until="networkidle")
        html = await page.content()
        screenshot_b64 = base64.b64encode(await page.screenshot()).decode('utf-8')

    # Jupyter: Convert HTML to markdown in sandbox
    c.jupyter.execute_code(code=f"""
from markdownify import markdownify
html = '''{html}'''
screenshot_b64 = "{screenshot_b64}"

md = f"{{markdownify(html)}}\\n\\n![Screenshot](data:image/png;base64,{{screenshot_b64}})"
with open('{home_dir}/site.md', 'w') as f:
    f.write(md)
print("Done!")
""")

    # Shell: List files in sandbox
    list_result = c.shell.exec_command(command=f"ls -lh {home_dir}")
    print(f"Files in sandbox: {list_result.data.output}")

    # File: Read the generated markdown
    return c.file.read_file(file=f"{home_dir}/site.md").data.content

if __name__ == "__main__":
    result = asyncio.run(site_to_markdown())
    print(f"Markdown saved successfully!")

🏗️ Architecture Copy Chapter

┌─────────────────────────────────────────────────────────────┐
│                    🌐 Browser + VNC                        │
├─────────────────────────────────────────────────────────────┤
│  💻 VSCode Server  │  🐚 Shell Terminal  │  📁 File Ops   │
├─────────────────────────────────────────────────────────────┤
│              🔗 MCP Hub + 🔒 Sandbox Fusion               │
├─────────────────────────────────────────────────────────────┤
│         🚀 Preview Proxy + 📊 Service Monitoring          │
└─────────────────────────────────────────────────────────────┘

🛠️ API Reference Copy Chapter

Core APIs Copy Section

MCP Servers Copy Section

🚢 Deployment Copy Chapter

Docker Compose Copy Section

services:
  sandbox:
    container_name: aio-sandbox
    image: ghcr.io/agent-infra/sandbox:latest
    security_opt:
      - seccomp:unconfined
    ports:
      - "127.0.0.1:${HOST_PORT:-8080}:8080"
    volumes:
      - sandbox_data:/home/gem/workspace
    extra_hosts:
      - "host.docker.internal:host-gateway"
    restart: "unless-stopped"
    shm_size: "2gb"
    environment:
      SANDBOX_API_KEY: ${SANDBOX_API_KEY:-}
      PROXY_SERVER: ${PROXY_SERVER:-}
      WORKSPACE: ${WORKSPACE:-/home/gem/workspace}
      TZ: ${TZ:-Asia/Singapore}

volumes:
  sandbox_data:

Kubernetes Copy Section

apiVersion: apps/v1
kind: Deployment
metadata:
  name: aio-sandbox
spec:
  replicas: 2
  selector:
    matchLabels:
      app: aio-sandbox
  template:
    metadata:
      labels:
        app: aio-sandbox
    spec:
      containers:
      - name: aio-sandbox
        image: ghcr.io/agent-infra/sandbox:latest
        ports:
        - containerPort: 8080
        resources:
          limits:
            memory: "2Gi"
            cpu: "1000m"

🤝 Integration Examples Copy Chapter

Browser Use Integration Copy Section

import asyncio

from agent_sandbox import Sandbox
from browser_use import Agent, Tools
from browser_use.browser import BrowserProfile, BrowserSession
from browser_use.llm import ChatOpenAI

sandbox = Sandbox(base_url="http://localhost:8080")
print("sandbox", sandbox.browser)
cdp_url = sandbox.browser.get_info().data.cdp_url

browser_session = BrowserSession(
    browser_profile=BrowserProfile(cdp_url=cdp_url, is_local=True)
)
tools = Tools()


async def main():
    agent = Agent(
        task='Visit https://duckduckgo.com and search for "browser-use founders"',
        llm=ChatOpenAI(model="gcp-claude4.1-opus"),
        tools=tools,
        browser_session=browser_session,
    )

    await agent.run()
    await browser_session.kill()

    input("Press Enter to close...")


if __name__ == "__main__":
    asyncio.run(main())

LangChain Integration Copy Section

from langchain.tools import BaseTool
from agent_sandbox import Sandbox

class SandboxTool(BaseTool):
    name = "sandbox_execute"
    description = "Execute commands in AIO Sandbox"

    def _run(self, command: str) -> str:
        client = Sandbox(base_url="http://localhost:8080")
        result = client.shell.exec_command(command=command)
        return result.data.output

OpenAI Assistant Integration Copy Section

from openai import OpenAI
from agent_sandbox import Sandbox
import json

client = OpenAI(
    api_key="your_api_key",
)
sandbox = Sandbox(base_url="http://localhost:8080")


# define a tool to run code in the sandbox
def run_code(code, lang="python"):
    if lang == "python":
        return sandbox.jupyter.execute_code(code=code).data
    return sandbox.nodejs.execute_nodejs_code(code=code).data


# Use OpenAI
response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "calculate 1+1"}],
    tools=[
        {
            "type": "function",
            "function": {
                "name": "run_code",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "code": {"type": "string"},
                        "lang": {"type": "string"},
                    },
                },
            },
        }
    ],
)


if response.choices[0].message.tool_calls:
    args = json.loads(response.choices[0].message.tool_calls[0].function.arguments)
    print("args", args)
    result = run_code(**args)
    print(result['outputs'][0]['text'])

MiniMax Integration Copy Section

MiniMax provides an OpenAI-compatible API, so you can use the same openai SDK with a different base_url:

from openai import OpenAI
from agent_sandbox import Sandbox
import json

client = OpenAI(
    api_key="your_minimax_api_key",
    base_url="https://api.minimax.io/v1",
)
sandbox = Sandbox(base_url="http://localhost:8080")


def run_code(code, lang="python"):
    if lang == "python":
        return sandbox.jupyter.execute_code(code=code).data
    return sandbox.nodejs.execute_code(code=code).data


response = client.chat.completions.create(
    model="MiniMax-M2.7",
    messages=[{"role": "user", "content": "calculate 1+1"}],
    tools=[
        {
            "type": "function",
            "function": {
                "name": "run_code",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "code": {"type": "string"},
                        "lang": {"type": "string"},
                    },
                },
            },
        }
    ],
    temperature=0.01,  # MiniMax requires temperature > 0
)


if response.choices[0].message.tool_calls:
    args = json.loads(response.choices[0].message.tool_calls[0].function.arguments)
    result = run_code(**args)
    print(result.outputs[0].text)

See the full minimax-integration example for more details.

🤝 Contributing Copy Chapter

We welcome contributions! Please see our Contributing Guide for details.

📄 License Copy Chapter

AIO Sandbox is released under the Apache License 2.0.

🙏 Acknowledgments Copy Chapter

Built with ❤️ by the Agent Infra team. Special thanks to all contributors and the open-source community.

📞 Support Copy Chapter

• 📖 Documentation
• 💬 GitHub Discussions
• 🐛 Issue Tracker

File: biome.json Copy Chapter

{
"$schema": "https://biomejs.dev/schemas/1.8.0/schema.json",
"organizeImports": {
"enabled": true
},
"vcs": {
"enabled": true,
"clientKind": "git",
"useIgnoreFile": true
},
"formatter": {
"indentStyle": "space"
},
"javascript": {
"formatter": {
"quoteStyle": "single"
}
},
"css": {
"parser": {
"cssModules": true
}
},
"linter": {
"enabled": true,
"rules": {
"recommended": true
}
}
}

File: CONTRIBUTING.md Copy Chapter

Contributing to Agent Infrastructure SDK

Thank you for your interest in contributing to the Agent Infrastructure SDK! This document provides guidelines and instructions for contributing to the project.

Table of Contents Copy Chapter

• Code of Conduct
• Getting Started
• Development Setup
• How to Contribute
• Pull Request Process
• Development Guidelines
• Testing
• Documentation
• Release Process

Code of Conduct Copy Chapter

We are committed to providing a welcoming and inclusive environment for all contributors. Please be respectful and constructive in all interactions.

Expected Behavior Copy Section

• Use welcoming and inclusive language
• Be respectful of differing viewpoints and experiences
• Gracefully accept constructive criticism
• Focus on what is best for the community
• Show empathy towards other community members

Getting Started Copy Chapter

Prerequisites Copy Section

• Node.js 18+ and npm/yarn for JavaScript SDK
• Python 3.8+ for Python SDK
• Git for version control
• Docker (optional, for containerized development)

Repository Structure Copy Section

sdk/
├── javascript/          # JavaScript/TypeScript SDK
│   ├── src/            # Source code
│   ├── tests/          # Test files
│   └── examples/       # Usage examples
├── python/             # Python SDK
│   ├── src/            # Source code
│   ├── tests/          # Test files
│   └── examples/       # Usage examples
└── website/            # Documentation website

Development Setup Copy Chapter

JavaScript SDK Copy Section

cd javascript
npm install
npm run build
npm test

Python SDK Copy Section

cd python
pip install -e .
pip install -r requirements-dev.txt
pytest

How to Contribute Copy Chapter

Reporting Issues Copy Section

Before creating an issue, please check if a similar issue already exists. When creating a new issue:

1. Use a clear and descriptive title
2. Provide a detailed description of the problem
3. Include steps to reproduce the issue
4. Specify your environment (OS, SDK version, runtime version)
5. Include relevant code snippets or error messages

Suggesting Enhancements Copy Section

Enhancement suggestions are tracked as GitHub issues. When suggesting an enhancement:

1. Use a clear and descriptive title
2. Provide a detailed description of the proposed enhancement
3. Explain why this enhancement would be useful
4. Include code examples if applicable

Contributing Code Copy Section

1. Fork the repository
2. Create a feature branch from main:
   bash Copy

   git checkout -b feature/your-feature-name

3. Make your changes following our coding standards
4. Write or update tests as needed
5. Ensure all tests pass
6. Commit your changes with a descriptive message
7. Push to your fork and create a pull request

Pull Request Process Copy Chapter

Before Submitting Copy Section

1. Test your changes: Run the full test suite
2. Update documentation: Update relevant documentation and examples
3. Follow code style: Run linters and formatters
4. Write clear commits: Use conventional commit format

Pull Request Guidelines Copy Section

1. Title: Use a clear, descriptive title following conventional commit format

   • feat: for new features
   • fix: for bug fixes
   • docs: for documentation changes
   • refactor: for code refactoring
   • test: for test additions/changes
   • chore: for maintenance tasks

2. Description: Include:

   • Summary of changes
   • Related issue numbers (fixes #123)
   • Breaking changes (if any)
   • Testing performed

3. Size: Keep PRs focused and reasonably sized

   • Split large changes into multiple PRs if possible
   • One feature/fix per PR

Review Process Copy Section

1. At least one maintainer review is required
2. All CI checks must pass
3. Resolve all review comments
4. Maintainers will merge using squash and merge

Development Guidelines Copy Chapter

Code Style Copy Section

JavaScript/TypeScript

• Use ESLint and Prettier configurations
• Follow TypeScript strict mode
• Use meaningful variable and function names
• Add JSDoc comments for public APIs

/**
 * Creates a new sandbox instance
 * @param config - Sandbox configuration options
 * @returns Promise<Sandbox> - The initialized sandbox
 */
async function createSandbox(config: SandboxConfig): Promise<Sandbox> {
  // Implementation
}

Python

• Follow PEP 8 style guide
• Use type hints for function signatures
• Use meaningful variable and function names
• Add docstrings for all public functions

def create_sandbox(config: SandboxConfig) -> Sandbox:
    """
    Creates a new sandbox instance.

    Args:
        config: Sandbox configuration options

    Returns:
        The initialized sandbox instance

    Raises:
        ValueError: If configuration is invalid
    """
    # Implementation

Commit Messages Copy Section

Follow conventional commit format:

<type>(<scope>): <subject>

<body>

<footer>

Examples:

feat(python): add sandbox lifecycle management
fix(javascript): resolve connection timeout issue
docs: update API reference for v2.0

Testing Copy Section

• Write unit tests for all new functionality
• Maintain or improve code coverage
• Include integration tests for API changes
• Test edge cases and error conditions

JavaScript Testing

npm test                 # Run all tests
npm run test:unit       # Run unit tests only
npm run test:integration # Run integration tests
npm run test:coverage   # Generate coverage report

Python Testing

pytest                   # Run all tests
pytest tests/unit       # Run unit tests only
pytest tests/integration # Run integration tests
pytest --cov=src        # Generate coverage report

Documentation Copy Chapter

Code Documentation Copy Section

• Document all public APIs
• Include examples in docstrings
• Explain complex algorithms or business logic
• Keep documentation up-to-date with code changes

User Documentation Copy Section

• Update README files as needed
• Add examples for new features
• Update API reference documentation
• Consider adding tutorials for complex features

Documentation Website Copy Section

The documentation website is built with Docusaurus:

cd website
npm install
npm start  # Start development server
npm build  # Build for production

Release Process Copy Chapter

Version Numbering Copy Section

We follow Semantic Versioning (SemVer):

• MAJOR version for incompatible API changes
• MINOR version for backwards-compatible functionality additions
• PATCH version for backwards-compatible bug fixes

Release Checklist Copy Section

1. Update version numbers in package files
2. Update CHANGELOG.md
3. Run full test suite
4. Build and verify packages
5. Create git tag
6. Publish to package repositories
7. Update documentation website
8. Create GitHub release with notes

Publishing Copy Section

JavaScript SDK

npm version <major|minor|patch>
npm run build
npm publish

Python SDK

cd python
./publish.sh  # Builds, publishes to PyPI, and creates git tag

Questions and Support Copy Chapter

If you have questions or need help:

1. Check the documentation
2. Search existing issues
3. Join our community discussions
4. Create a new issue if needed

License Copy Chapter

By contributing to this project, you agree that your contributions will be licensed under the same license as the project (see LICENSE file).

Acknowledgments Copy Chapter

Thank you to all contributors who help make this project better!

File: docker-compose.yaml Copy Chapter

services:
sandbox:
container_name: aio-sandbox
image: ghcr.io/agent-infra/sandbox:latest
security_opt:
- seccomp:unconfined
extra_hosts:
- "host.docker.internal:host-gateway"
restart: "unless-stopped"
shm_size: "2gb"
mem_limit: "8g"
cpus: "4"
ports:
- "127.0.0.1:${HOST_PORT:-8080}:8080"
environment:
PROXY_SERVER: ${PROXY_SERVER:-}
JWT_PUBLIC_KEY: ${JWT_PUBLIC_KEY:-}
DNS_OVER_HTTPS_TEMPLATES: ${DNS_OVER_HTTPS_TEMPLATES:-"https://cloudflare-dns.com/dns-query{?dns}"}
WORKSPACE: ${WORKSPACE:-"/home/gem"}
HOMEPAGE: ${HOMEPAGE:-}
BROWSER_EXTRA_ARGS: ${BROWSER_EXTRA_ARGS:-}
TZ: ${TZ:-Asia/Singapore}
DISPLAY_WIDTH: ${DISPLAY_WIDTH:-1280}
DISPLAY_HEIGHT: ${DISPLAY_HEIGHT:-1024}
WAIT_PORTS: "8079,8091"
VNC_SERVER_PORT: 5900
PUBLIC_PORT: 8080
AUTH_BACKEND_PORT: 8081
WEBSOCKET_PROXY_PORT: 6080
GEM_SERVER_PORT: 8088
MCP_HUB_PORT: 8079
SANDBOX_SRV_PORT: 8091
JUPYTER_LAB_PORT: 8888
CODE_SERVER_PORT: 8200
MCP_SERVER_BROWSER_PORT: 8100
TINYPROXY_PORT: 8118
MCP_SERVER_MARKITDOWN_PORT: 8101
MCP_SERVER_CHROME_DEVTOOLS_PORT: 8102
BROWSER_REMOTE_DEBUGGING_PORT: 9222
PIP_INDEX_URL: ${PIP_INDEX_URL:-https://pypi.org/simple}
UV_DEFAULT_INDEX: ${UV_DEFAULT_INDEX:-https://pypi.org/simple}
NPM_CONFIG_REGISTRY: ${NPM_CONFIG_REGISTRY:-https://registry.npmjs.org}
# for gh cli
GITHUB_TOKEN: ""
# Claude Skills
AIO_SKILLS_PATH: ${AIO_SKILLS_PATH:-}
# Features
DISABLE_JUPYTER: ${DISABLE_JUPYTER:-false}
DISABLE_CODE_SERVER: ${DISABLE_CODE_SERVER:-false}

File: package.json Copy Chapter

{
"name": "sandbox",
"version": "1.0.0",
"private": true,
"license": "Apache-2.0",
"scripts": {},
"dependencies": {},
"devDependencies": {
"@biomejs/biome": "^1.9.4",
"@types/node": "^18.11.17",
"prettier": "^3.4.2"
}
}

File: pnpm-workspace.yaml Copy Chapter

packages:

• 'website'
• 'sdk/js'

File: evaluation/README.md Copy Chapter

AIO Sandbox Tool Evaluation

English | 简体中文

A comprehensive evaluation framework for MCP (Model Context Protocol) tools and AI agent capabilities based on aio-sandbox.

Inspired by Anthropic's "Writing Tools for Agents"

Prerequisites Copy Chapter

• Python >= 3.13
• uv package manager

Installation Copy Chapter

1. Clone the repository:

   bash Copy

   git clone <repository-url>
   cd evaluation

2. Install dependencies:

   bash Copy

   uv sync

3. Configure environment:

   bash Copy

   cp .env.example .env

   Edit .env with your credentials:

   env Copy

   # Azure OpenAI Configuration
   OPENAI_BASE_URL=https://your-endpoint.openai.azure.com
   OPENAI_API_KEY=your-api-key
   AZURE_OPENAI_DEPLOYMENT=gpt-4
   AZURE_OPENAI_API_VERSION=2024-02-15-preview
   
   # MCP Server Configuration
   MCP_SERVER_URL=http://localhost:8080/mcp
   
   # Optional: Concurrency
   MAX_CONCURRENT_TASKS=5

Usage Copy Chapter

Run All Evaluations Copy Section

uv run main.py

Run Specific Evaluation Copy Section

uv run main.py --eval basic
uv run main.py --eval browser
uv run main.py --eval collaboration
uv run main.py --eval workflow

Use OpenAI-Compatible Providers Copy Section

The evaluation framework also supports standard OpenAI and compatible APIs
(e.g. MiniMax) via the --agent openai flag:

# Standard OpenAI
uv run main.py --agent openai --openai-model gpt-4

# MiniMax (OpenAI-compatible)
export OPENAI_API_KEY="your_minimax_api_key"
uv run main.py --agent openai \
    --openai-base-url https://api.minimax.io/v1 \
    --openai-model MiniMax-M2.7

Available Categories Copy Section

Project Structure Copy Chapter

evaluation/
├── main.py                 # Main entry point and orchestration
├── agent_loop.py           # Agent loop implementations (Azure OpenAI, OpenAI-compatible, etc.)
├── dataset_parser.py       # XML dataset parser
├── .env.example            # Environment configuration template
├── pyproject.toml          # Project dependencies
├── dataset/                # Evaluation datasets
│   ├── evaluation_basic.xml
│   ├── evaluation_browser.xml
│   ├── evaluation_collaboration.xml
│   └── ...
└── result/                 # Evaluation reports (auto-generated)
    └── YYYYMMDD/           # Date-based output directory
        └── evaluation_*.md

Extending the Framework Copy Chapter

Add New Evaluation Category Copy Section

1. Create XML file in dataset/:

   text Copy

   dataset/evaluation_mycategory.xml

2. Run:

   bash Copy

   uv run main.py --eval mycategory

Contributing Copy Chapter

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new features
4. Ensure all tests pass
5. Submit a Pull Request

License Copy Chapter

See LICENSE in the repository root.

References Copy Chapter

• Model Context Protocol (MCP)
• Anthropic: Writing Tools for Agents
• Azure OpenAI Documentation
• MiniMax API Documentation

File: evaluation/README_zh.md Copy Chapter

AIO Sandbox 工具评测

English | 简体中文

一个基于 aio-sandbox 的 MCP（模型上下文协议）工具和 AI 智能体能力的综合评测框架。

来源：Anthropic 的《为智能体编写工具》

前置要求 Copy Chapter

• Python >= 3.13
• uv 包管理器

安装 Copy Chapter

1. 克隆仓库：

   bash Copy

   git clone <repository-url>
   cd evaluation

2. 安装依赖：

   bash Copy

   uv sync

3. 配置环境：

   bash Copy

   cp .env.example .env

   编辑 .env 文件，填入你的凭据：

   env Copy

   # Azure OpenAI 配置
   OPENAI_BASE_URL=https://your-endpoint.openai.azure.com
   OPENAI_API_KEY=your-api-key
   AZURE_OPENAI_DEPLOYMENT=gpt-4
   AZURE_OPENAI_API_VERSION=2024-02-15-preview
   
   # MCP 服务器配置
   MCP_SERVER_URL=http://localhost:8080/mcp
   
   # 可选：并发配置
   MAX_CONCURRENT_TASKS=5

使用方法 Copy Chapter

运行所有评测 Copy Section

顺序运行所有评测文件：

uv run main.py

运行特定评测 Copy Section

运行特定评测类别：

uv run main.py --eval basic
uv run main.py --eval browser
uv run main.py --eval collaboration
uv run main.py --eval workflow

可用的评测类别 Copy Section

项目结构 Copy Chapter

evaluation/
├── main.py                 # 主入口和评测编排
├── agent_loop.py          # 智能体循环实现（Azure OpenAI 等）
├── dataset_parser.py      # XML 数据集解析器
├── .env.example           # 环境配置模板
├── pyproject.toml         # 项目依赖
├── dataset/               # 评测数据集
│   ├── evaluation_basic.xml
│   ├── evaluation_browser.xml
│   ├── evaluation_collaboration.xml
│   └── ...
└── result/                # 评测报告（自动生成）
    └── YYYYMMDD/          # 基于日期的输出目录
        └── evaluation_*.md

扩展框架 Copy Chapter

添加新的评测类别 Copy Section

1. 在 dataset/ 目录创建 XML 文件：

   text Copy

   dataset/evaluation_mycategory.xml

2. 运行：

   bash Copy

   uv run main.py --eval mycategory

贡献 Copy Chapter

欢迎贡献！请：

1. Fork 仓库
2. 创建功能分支
3. 为新功能添加测试
4. 确保所有测试通过
5. 提交 Pull Request

许可证 Copy Chapter

查看仓库根目录的 LICENSE 文件。

参考资料 Copy Chapter

• 模型上下文协议（MCP）
• Anthropic：为智能体编写工具
• Azure OpenAI 文档

File: evaluation/dataset/README.md Copy Chapter

Dataset 评测用例总览

1. evaluation_ping.xml - 基础连通性测试

• 测试 aio 系统版本获取:回答 aio 系统的版本号

2. evaluation_basic.xml - 单工具基础能力测试

A. 环境探测类

• 检查 Python 包 'fastapi' 是否已安装
• 统计已安装的 Python 包数量

B. 文件操作类

• 创建文件并写入内容 "Hello MCP",然后读取
• 列出 /tmp 目录中以 'test_eval' 开头的文件数量
• 搜索文件中 'Hello MCP' 模式的匹配次数

C. 代码执行类

• 执行 Python 代码计算 2^10
• 计算 1-100 内所有偶数的和
• 统计字符串 "Model Context Protocol" 中的元音字母数量

D. Shell 操作类

• 执行 bash echo 命令输出 "MCP_TEST"
• 使用 bash 统计 /tmp 目录中的文件夹数量

3. evaluation_browser.xml - 浏览器基础测试

• 导航到 bytedance.com,检查是否包含 'ByteDance' 或 '字节跳动'
• 导航到 bytedance.com,统计页面链接数量
• 导航到 baidu.com,用 JavaScript 获取链接数量
• 导航到 baidu.com,用 JavaScript 获取页面标题
• 导航到 baidu.com,统计 DOM 中的 anchor 元素数量
• 测试表单填充:在 baidu.com 搜索框填入 'test_search'
• 测试表单填充工作流:填入 'MCP test' 并验证
• 测试完整浏览器工作流:导航、读取链接、获取 markdown、执行 JS
• 测试标签页管理:创建新标签页并统计数量
• 测试标签页切换:切换标签页并获取标题
• 搜索 "aio sandbox",导航到 GitHub 页面,输出主要贡献者
• 获取浏览器下载列表并统计数量
• 触发下载并检查下载列表是否包含文件
• 检查下载项是否包含 'filename' 字段

4. evaluation_browser_advanced.xml - 浏览器高级交互测试

A. 元素点击操作

• 点击按钮并验证文本变化
• 点击多个按钮中的特定按钮(使用索引)

B. 表单填充与提交

• 填充文本输入框和邮箱输入框

C. 键盘操作

• 测试按键事件(Enter 键)
• 测试特殊按键(Tab 键)
• 测试组合键(Delete 键)

D. 鼠标移动与悬停

• 测试鼠标悬停事件
• 测试悬停菜单显示
• 测试悬停 tooltip 显示

E. 滚动操作

• 测试页面滚动
• 测试负向滚动(向上滚动)
• 测试滚动到底部

F. 导航历史

• 测试后退功能
• 测试前进功能

G. 标签页管理

• 关闭标签页并统计剩余数量
• 切换标签页后关闭
• 测试关闭最后一个标签页的行为

H. 下拉选择

• 测试下拉菜单选择
• 测试通过索引选择下拉选项

I. 复杂交互场景

• 测试计算器交互:填充数字并执行加法运算

J. 可点击元素获取

• 过滤特定类型的可点击元素
• 获取复杂页面中的所有可交互元素

K. 浏览器信息获取

• 获取浏览器视口信息
• 获取 CDP URL
• 计算视口面积

5. evaluation_code_advanced.xml - 代码执行高级测试

A. JavaScript 基础执行

• 基础算术运算
• 字符串反转操作

B. JavaScript 对象和数组

• 数组求和操作
• JSON 解析

C. Python 高级特性

• 列表推导式计算平方和
• 字典值求和
• lambda 和 map 函数使用

D. 文件操作 + 代码执行

• Python 文件 I/O 操作

E. JavaScript 异步代码

• 同步循环求和

F. 错误处理

• Python 异常捕获(ZeroDivisionError)
• JavaScript 错误处理(JSON 解析错误)

G. 数学运算

• Python math 库使用
• JavaScript Math 操作

H. 字符串处理

• Python 正则表达式匹配邮箱
• JavaScript 正则表达式匹配数字

I. 数据结构

• Python 集合交集操作

J. 综合场景

• Python 数据处理管道
• JavaScript 函数式编程

6. evaluation_collaboration.xml - 多工具协作测试

E. 文件+代码执行

• 读取文件并统计 'async' 出现次数
• 创建并执行斐波那契数列脚本

F. Shell+文件操作

• 创建目录和文件,然后读取
• 获取当前工作目录并写入文件

G. 环境探测+代码分析

• 获取包列表并统计包含 'fast' 的包数量

H. Browser + 文件操作

• 创建 HTML 文件并用浏览器导航验证

I. 编辑器 + 代码执行

• 使用编辑器创建 Python 文件并执行
• 修改文件后重新执行

J. 复杂多步协作

• bash + 文件 + 代码执行管道
• 获取上下文并写入文件验证版本号

K. 浏览器 + 代码分析

• 浏览器 evaluate + Python 处理 DOM 数据

L. 文件查找 + 处理

• 批量处理文件
• 文件搜索和聚合统计

7. evaluation_editor.xml - str_replace_editor 工具测试

A. 文件查看 (view)

• 查看完整文件内容
• 查看指定行范围

B. 文件创建 (create)

• 创建新的 Python 文件

C. 字符串替换 (str_replace)

• 单次字符串替换
• 多行字符串替换

D. 插入 (insert)

• 在指定行插入内容

E. 复杂编辑场景

• Python 代码重构

F. 边界情况

• 创建空文件
• 处理特殊字符

G. 撤销操作 (undo_edit)

• 基础撤销操作
• 多次撤销操作
• 撤销新文件创建

8. evaluation_error.xml - 错误处理测试

• 读取不存在的文件
• 执行产生 ZeroDivisionError 的 Python 代码

9. evaluation_packages.xml - 包管理工具测试

A. Node.js 包查询

• 检查 'express' 是否已安装
• 统计 Node.js 包数量

B. 混合包查询

• 同时获取 Python 和 Node.js 包

C. 不同语言别名

• 使用 'node' 别名
• 使用 'py' 别名

D. 包搜索

• 搜索包含特定字符串的包

E. 版本信息

• 提取包版本号

F. 包统计

• 统计所有包的总数量

10. evaluation_util.xml - 工具测试

• 转换网页到 markdown 格式
• 统计 markdown 中特定词汇出现次数

11. evaluation_workflow.xml - 真实工作场景

H. 代码审查工作流

• 搜索包含特定关键字的 Python 文件
• 使用 AST 解析统计函数定义数量

I. 数据处理管道

• 解析 XML 并统计元素数量

File: evaluation/result/20251112/improvement_suggestions.md Copy Chapter

AIO Sandbox MCP工具改进建议

"理论和实践有时会冲突。每次都是理论输。" - Linus Torvalds

基于对评测反馈的深度分析,以下是核心问题诊断和改进方案。

【核心判断】 Copy Chapter

✅ 值得做:这些问题不是理论上的完美主义,而是实际用户每天都在碰到的真实痛点。

【关键洞察】 Copy Chapter

数据结构问题 Copy Section

• 工具返回格式不统一:部分工具返回纯文本,部分返回JSON,增加了解析复杂度
• sandbox_execute_code执行结果不可预测:表达式返回值有时在stdout,有时需要显式print

复杂度问题 Copy Section

• str_replace_editor与file_operations功能重叠:两个工具都能做文件创建,用户困惑
• browser_evaluate的JavaScript格式要求模糊:需要箭头函数包装但错误提示不明确

风险点 Copy Section

• undo_edit逻辑缺陷:对新创建的文件执行undo应该删除文件,但实际保留了文件
• get_packages别名支持不一致:'node'不支持但'nodejs'支持,容易出错

【致命缺陷排序】 Copy Chapter

🔴 Level 1 - 必须立即修复(影响正确性) Copy Section

1.1 undo_edit对新创建文件的处理错误

问题描述:

创建文件 → 执行undo_edit → 文件仍然存在 ❌
预期:创建文件 → 执行undo_edit → 文件被删除 ✓

数据流分析:

• 创建操作被记录为"编辑历史"
• undo应该回退到"文件不存在"状态
• 当前实现只回退了文件内容,没有删除文件本身

修复方案:

# 伪代码
class EditorHistory:
    def undo_create(self, path):
        # 简单粗暴:删除文件
        if self.operation_type == 'create':
            os.remove(path)  # 不要留垃圾
        else:
            # 正常的内容回退
            self.restore_previous_content()

Linus评价:"这是个bug,不是feature。新文件的undo应该删除文件,这是常识。"

1.2 sandbox_execute_code的返回行为不一致

问题描述:

# 场景1:直接表达式 - 没有输出
execute_code("2**10")  # stdout: "" ❌

# 场景2:需要print才有输出
execute_code("print(2**10)")  # stdout: "1024" ✓

# 场景3:但JavaScript却不同
execute_code("10 + 20", language="javascript")  # stdout: "30" ✓

根本原因:Python REPL和脚本执行的区别

• REPL会自动打印表达式结果
• exec()不会打印返回值

修复方案(Good Taste):

def execute_code(code, language='python'):
    if language == 'python':
        # 包装代码,自动打印最后一个表达式
        wrapped = f"""
import sys
_result = None
try:
    _result = ({code})
    if _result is not None:
        print(_result)
except SyntaxError:
    # 是语句不是表达式,直接执行
    exec({repr(code)})
"""
        # 执行包装后的代码
        return run(wrapped)
    # JavaScript保持原样
    return run(code, 'js')

Linus评价:"用户不应该关心'表达式'和'语句'的区别。自动处理这种边界情况,这是好品味。"

🟡 Level 2 - 应该尽快优化(影响易用性) Copy Section

2.1 str_replace_editor的create命令在文件存在时失败

问题描述:

评测中多次遇到:创建文件失败 → 切换到file_operations → 成功覆盖

特殊情况分析:

IF 文件不存在: create成功
IF 文件已存在: create失败,提示"File already exists"

消除特殊情况的方案:

def str_replace_editor(command, path, content, overwrite=False):
    if command == 'create':
        if os.path.exists(path) and not overwrite:
            # 不要失败,提供更好的默认行为
            return {
                "suggest": "use overwrite=True or use str_replace command",
                "file_exists": True,
                "current_size": os.path.getsize(path)
            }
        # 直接写入,不管文件是否存在
        write_file(path, content)
        return {"success": True}

Linus评价:"失败是因为设计不好。'create'和'overwrite'不应该是两个命令,应该用一个参数控制。"

2.2 browser_evaluate的JavaScript格式要求不明确

问题描述:

// 失败:直接声明
const x = 5; console.log(x);  // ❌ "Unexpected token 'const'"

// 成功:箭头函数包装
() => { const x = 5; console.log(x); return x; }  // ✓

当前错误信息无用:

Error: "Unexpected token 'const'"
// 用户不知道怎么修正

改进方案(实用主义):

def browser_evaluate(script):
    # 尝试1:直接执行
    result = try_eval(script)
    if result.success:
        return result

    # 尝试2:自动包装
    wrapped = f"(() => {{ {script} }})()"
    result = try_eval(wrapped)
    if result.success:
        return result

    # 尝试3:更智能的包装(捕获最后一个表达式)
    wrapped = f"""
    (() => {{
        let _last_value;
        {transform_to_capture_last_value(script)}
        return _last_value;
    }})()
    """
    return try_eval(wrapped)

Linus评价:"不要让用户学习你的内部实现细节。自动处理格式,失败了再fallback,这是务实的做法。"

2.3 get_packages返回纯文本而非结构化数据

问题描述:

# 当前返回
"""
  - fastapi==0.121.0
  - numpy==2.2.6
  - pandas==2.3.3
"""

# 用户需要自己解析,容易出错
packages = output.split('\n')
for line in packages:
    name = line.strip()[2:].split('==')[0]  # 丑陋的字符串处理

好的数据结构 > 坏的代码:

# 改进后返回
{
    "language": "python",
    "count": 169,
    "packages": [
        {"name": "fastapi", "version": "0.121.0"},
        {"name": "numpy", "version": "2.2.6"},
        {"name": "pandas", "version": "2.3.3"}
    ]
}

# 用户代码变得简单
count = result['count']
fastapi = next(p for p in result['packages'] if p['name'] == 'fastapi')

Linus评价:"糟糕的程序员担心代码,优秀的程序员担心数据结构。返回结构化数据,让用户代码变简单。"

🟢 Level 3 - 可以改进(提升体验) Copy Section

3.1 file_operations和str_replace_editor功能重叠

当前状态:

创建文件:
- file_operations(action='write')  ✓
- str_replace_editor(command='create')  ✓

两个工具都能做,用户困惑该用哪个

Linus的建议:

"一个功能一个工具。如果有重叠,就是设计错了。"

改进方案:

• file_operations: 专注于简单的CRUD操作(create/read/update/delete/list/search)
• str_replace_editor: 专注于编辑操作(view/str_replace/insert/undo)

明确的职责划分:

file_operations: 我是文件管理器
str_replace_editor: 我是编辑器

你要创建新文件? → file_operations
你要编辑已有文件? → str_replace_editor

3.2 get_packages不支持常见别名

问题描述:

get_packages(language='py')     # ❌ 失败:"should be 'python' or 'nodejs'"
get_packages(language='node')   # ❌ 失败:"should be 'python' or 'nodejs'"
get_packages(language='js')     # ❌ 失败

用户体验差:用户需要记住精确的参数值,不符合直觉

修复方案(简单有效):

LANGUAGE_ALIASES = {
    'py': 'python',
    'python': 'python',
    'python3': 'python',
    'node': 'nodejs',
    'nodejs': 'nodejs',
    'js': 'nodejs',
    'javascript': 'nodejs'
}

def get_packages(language=None):
    if language:
        language = LANGUAGE_ALIASES.get(language.lower())
        if not language:
            return error("Unsupported language. Try: py/python, node/nodejs/js")
    # 继续执行

Linus评价:"别让用户猜。支持常见别名,这是基本的用户友好性。"

3.3 文件操作工具缺少批量操作支持

问题描述:

# 场景:搜索7个文件中是否包含'def'
# 当前:需要调用7次file_operations
for file in py_files:
    file_operations(action='search', path=file, content='def')

# 效率低,工具调用次数多

改进方案:

# 新增batch参数
file_operations(
    action='search',
    paths=['/tmp/main.py', '/tmp/calc.py', ...],  # 批量路径
    content='def'
)

# 返回
{
    "results": [
        {"path": "/tmp/main.py", "matches": 16},
        {"path": "/tmp/calc.py", "matches": 1},
        ...
    ],
    "total_matches": 22
}

【实施优先级】 Copy Chapter

Week 1 (立即修复):
├── undo_edit bug修复
├── execute_code返回值统一化
└── browser_evaluate自动包装

Week 2 (易用性改进):
├── get_packages返回JSON
├── str_replace_editor支持overwrite
└── 别名支持

Week 3 (体验优化):
├── 工具职责明确化文档
├── 批量操作支持
└── 错误提示改进

【Linus式总结】 Copy Chapter

Good Taste原则 Copy Section

1. 自动处理边界情况:不要让用户区分"表达式"和"语句"
2. 消除特殊情况:文件存在与否不应该影响create的行为
3. 数据结构优先:返回JSON而不是文本,让用户代码更简单

Never Break Userspace原则 Copy Section

• 添加overwrite参数时,默认值应该保持向后兼容
• 返回格式改JSON时,提供format='legacy'选项过渡

Pragmatism原则 Copy Section

• 自动包装JavaScript代码,不要强制用户学习内部细节
• 支持常见别名(py/node/js),因为这是实际使用中会遇到的

🔵 Level 4 - Next.js 全栈场景优化(实战验证) Copy Section

4.1 长时间npm操作需要更好的进度反馈

问题描述:

# Next.js评测中的耗时分析
npx create-next-app: 134.50秒 (占总时间201.36秒的67%)
等待服务启动: 10秒
其他操作: 56.86秒

用户痛点:

• 长达2分钟的创建过程没有任何进度反馈
• 用户不知道是"正在执行"还是"卡住了"
• 超时参数(timeout: 120)被迫使用,但仍不够

Linus评价:"用户等待超过30秒就会焦虑。提供实时输出,让用户看到进度。"

改进方案:

def execute_bash(cmd, stream_output=False):
    if stream_output:
        # 流式返回输出,每1秒返回一次增量
        for line in process.stdout:
            yield {"type": "stdout", "content": line}
    else:
        # 传统方式:等待完成后返回
        return process.communicate()

优先级:中等(影响用户体验,但不影响功能正确性)

4.2 后台进程管理需要更优雅的方案

问题描述:

# 当前做法:手动管理后台进程
cd /tmp/my-nextjs-app && nohup npm run dev -- -p 3500 > dev.log 2>&1 &
sleep 10  # 硬编码等待时间
cat dev.log  # 手动检查日志

特殊情况太多:

• IF 服务启动很快:浪费了等待时间
• IF 服务启动很慢:10秒不够,测试会失败
• IF 端口被占用:没有错误检测机制
• IF 进程启动失败:用户不知道

Linus的"Good Taste"方案:

def start_dev_server(cmd, port, ready_pattern=r"Ready|Listening"):
    """
    启动开发服务器并等待就绪

    - 消除硬编码的sleep时间
    - 自动检测服务是否启动成功
    - 提供清晰的错误信息
    """
    process = subprocess.Popen(cmd, stdout=PIPE, stderr=STDOUT)

    start_time = time.time()
    timeout = 60  # 最多等60秒

    while time.time() - start_time < timeout:
        # 检查进程是否还活着
        if process.poll() is not None:
            return error(f"Process exited with code {process.returncode}")

        # 检查端口是否可用
        if is_port_listening(port):
            return success("Server is ready")

        time.sleep(0.5)

    return error(f"Timeout waiting for server on port {port}")

消除的特殊情况:

• ❌ sleep 10 - 硬编码等待
• ❌ cat dev.log - 手动检查日志
• ❌ 不知道服务是否真的启动了
• ✅ 自动检测,服务就绪立即返回

4.3 browser工具与bash工具的协同需要优化

问题描述:

# Next.js评测中的工具切换
sandbox_browser_navigate    # 访问首页
sandbox_browser_evaluate    # 获取title
sandbox_browser_navigate    # 访问API
sandbox_browser_evaluate    # 获取JSON
sandbox_execute_bash        # 用curl再验证一次
sandbox_execute_code        # 用Python解析JSON

# 为什么需要这么多步骤?

根本原因:

• browser_evaluate 返回的JSON需要手动解析
• 浏览器工具无法直接提取JSON响应
• 需要切换到bash/python来处理数据

实用主义改进:

# 新增便捷方法
def browser_fetch_json(url):
    """
    直接获取JSON API响应

    当前需要3步:
    1. navigate(url)
    2. evaluate("document.body.innerText")
    3. execute_code("json.loads(...)")

    改进后1步:
    browser_fetch_json(url) → {"status": "success"}
    """
    navigate(url)
    text = evaluate("document.body.innerText")
    try:
        return json.loads(text)
    except:
        return {"error": "Not valid JSON", "content": text}

【附录:评测数据摘要】 Copy Chapter

• 总任务数:76个任务(新增 Next.js 全栈场景)
• 成功率:100% (但过程中有很多tool retry)
• 工具调用统计:
  • 平均每任务2.9次工具调用
  • 最高:19次(复杂的browser任务)
  • 最低:1次(简单的execute任务)

关键发现:

• str_replace_editor 的 create 命令失败率:约30%(因为文件已存在)
• browser_evaluate 的JavaScript语法错误率:约40%(需要重试包装)
• execute_code 需要添加print才能得到结果:约25%
• [新增] Next.js长时间npm操作缺少进度反馈,用户体验差
• [新增] 后台进程管理依赖硬编码等待时间,不够可靠

这不是理论问题,这是实际用户体验的数据支撑。

"Talk is cheap. Show me the code." - Linus Torvalds

以上建议都是基于实际评测数据,而不是猜测。每个改进都能解决真实存在的用户痛点。

File: evaluation/result/20251112/Latest.md Copy Chapter

Eval Report

Datetime: 2025-11-12 13:27:23
Latest Update: 2025-11-12 (Added Next.js evaluation)

basic Copy Chapter

browser Copy Chapter

browser_advanced Copy Chapter

code_advanced Copy Chapter

collaboration Copy Chapter

editor Copy Chapter

error Copy Chapter

fix Copy Chapter

packages Copy Chapter

ping Copy Chapter

util Copy Chapter

workflow Copy Chapter

nextjs Copy Chapter

File: examples/README.md Copy Chapter

Agent Sandbox Examples

This directory contains examples demonstrating various use cases and integrations with agent-sandbox.

Table of Contents Copy Chapter

• basic-file-operations - Core file operations (upload, read, list, download)
• oss-upload - Stream sandbox files to cloud storage (Volcengine TOS, AWS S3)
• volcengine-provider - Volcengine cloud provider integration
• site-to-markdown - Website to markdown conversion with browser automation
• browser-use-integration - AI-driven browser automation
• playwright-integration - Browser automation with Playwright
• openai-integration - OpenAI function calling with code execution
• ag2-integration - AG2 multi-agent workflow with sandbox-backed code execution
• minimax-integration - MiniMax function calling with code execution (OpenAI-compatible)
• langgraph-deepagents-integration - LangGraph deep agent with MCP tools integration
• code-execute - Execute code in sandbox (Jupyter and Node.js)

Prerequisites Copy Chapter

All examples require:

• Python 3.12+
• A running sandbox instance (most examples use http://localhost:8080)
• uv package manager

Contributing Copy Chapter

We welcome contributions of new examples!

Quick Start (Easiest Way) Copy Section

Copy the _template directory and start coding:

# Copy template to your new example
cp -r _template my-example-name
cd my-example-name

# Set up environment
cp .env.example .env

# Start coding in main.py
# Run it: uv run main.py

The template includes all necessary files - just modify main.py with your code!

Before Submitting Copy Section

1. Test your example:

   bash Copy

   uv run main.py

2. Update the main examples/README.md Table of Contents

3. Keep it focused - one clear purpose per example

Example Naming Copy Section

• Use kebab-case: browser-automation, file-operations
• For integrations: openai-integration, langgraph-deepagents-integration

Need Help? Copy Section

• Check existing examples for reference
• Review the Agent Sandbox Documentation
• Open an issue for questions or suggestions

File: examples/_template/README.md Copy Chapter

Your Example Name

Brief description of what this example demonstrates.

Quick Start Copy Chapter

1. Start the sandbox

# Recommended: Enable API Key authentication (protects all services: API, JupyterLab, VNC)
# - Supports three methods: X-AIO-API-Key header, Authorization: Bearer header, ?api_key= query parameter
# - Without SANDBOX_API_KEY, services remain open (backward compatible)
docker run --security-opt seccomp=unconfined --rm -it \
  -e SANDBOX_API_KEY=your-secret-key \
  -p 127.0.0.1:8080:8080 ghcr.io/agent-infra/sandbox:latest

2. Configure the environment

# 1. Copy .env.example to .env
cp .env.example .env

# 2. Run the example
uv run main.py

What This Does Copy Chapter

Explain what happens when you run this example.

Customize Copy Chapter

Modify main.py to add your own logic.

File: examples/ag2-integration/README.md Copy Chapter

AG2 Integration Example

This example demonstrates how to run an AG2 multi-agent workflow against Agent Sandbox.

Prerequisites Copy Chapter

• A running sandbox instance at http://localhost:8080
• Python 3.12+
• OpenAI API key

Quick Start Copy Chapter

# Start sandbox
docker run --security-opt seccomp=unconfined --rm -it -p 127.0.0.1:8080:8080 ghcr.io/agent-infra/sandbox:latest

# Configure env
cp .env.example .env

# Install dependencies and run
uv sync
uv run main.py

What This Example Does Copy Chapter

1. Creates persistent Jupyter and shell sessions in the sandbox
2. Registers sandbox-backed AG2 tools for Python, shell, and file operations
3. Runs a Coder + Reviewer group chat against the Iris dataset
4. Verifies generated artifacts in /home/gem
5. Cleans up sandbox sessions before exit

Optional Smoke Test Copy Chapter

smoke_test.ipynb is a step-by-step notebook for validating the SDK calls used by main.py before running the full multi-agent flow.

File: examples/basic-file-operations/README.md Copy Chapter

Basic File Operations Example

This example demonstrates basic file operations with agent-sandbox, including:

• Uploading files to the sandbox
• Listing files in the sandbox
• Reading files from the sandbox
• Downloading files from the sandbox

Prerequisites Copy Chapter

• A running sandbox instance at http://localhost:8080
• Python 3.11+

Running the Example Copy Chapter

uv run main.py

What This Example Does Copy Chapter

1. Reads a local image file (foo.png)
2. Uploads it to the sandbox at /home/sandbox/test.png
3. Lists files in the sandbox directory
4. Reads the file back from the sandbox
5. Downloads the file from the sandbox to verify the operation

File: examples/browser-use-cua/README.md Copy Chapter

Browser-Use Integration Example

This example demonstrates how to integrate browser-use with agent-sandbox, allowing you to use browser automation agents with a sandboxed browser.

Prerequisites Copy Chapter

• A running sandbox instance at http://localhost:8080
• Python 3.11+
• OpenAI API key or compatible LLM endpoint

Running the Example Copy Chapter

# Set your LLM API credentials
export OPENAI_API_KEY="your_api_key"

# Run the example
uv run main.py

What This Example Does Copy Chapter

1. Connects to the sandbox browser via CDP
2. Creates a browser-use Agent with the sandboxed browser session
3. Executes an AI-driven browser automation task
4. The agent will visit DuckDuckGo and search for "browser-use founders"

Configuration Copy Chapter

You can modify the task in main.py:

agent = Agent(
    task='Visit https://duckduckgo.com and search for "browser-use founders"',
    llm=ChatOpenAI(model="gcp-claude4.1-opus"),
    tools=tools,
    browser_session=browser_session,
)

Update the LLM model in the code according to your setup.

File: examples/browser-use-integration/README.md Copy Chapter

Browser-Use Integration Example

This example demonstrates how to integrate browser-use with agent-sandbox, allowing you to use browser automation agents with a sandboxed browser.

Prerequisites Copy Chapter

• A running sandbox instance at http://localhost:8080
• Python 3.11+
• OpenAI API key or compatible LLM endpoint

Running the Example Copy Chapter

# Set your LLM API credentials
export OPENAI_API_KEY="your_api_key"

# Run the example
uv run main.py

What This Example Does Copy Chapter

1. Connects to the sandbox browser via CDP
2. Creates a browser-use Agent with the sandboxed browser session
3. Executes an AI-driven browser automation task
4. The agent will visit DuckDuckGo and search for "browser-use founders"

Configuration Copy Chapter

You can modify the task in main.py:

agent = Agent(
    task='Visit https://duckduckgo.com and search for "browser-use founders"',
    llm=ChatOpenAI(model="gcp-claude4.1-opus"),
    tools=tools,
    browser_session=browser_session,
)

Update the LLM model in the code according to your setup.

File: examples/code-execute/README.md Copy Chapter

Basic File Operations Example

This example demonstrates basic file operations with agent-sandbox, including:

• Uploading files to the sandbox
• Listing files in the sandbox
• Reading files from the sandbox
• Downloading files from the sandbox

Prerequisites Copy Chapter

• A running sandbox instance at http://localhost:8080
• Python 3.11+

Running the Example Copy Chapter

uv run main.py

What This Example Does Copy Chapter

1. Reads a local image file (foo.png)
2. Uploads it to the sandbox at /home/sandbox/test.png
3. Lists files in the sandbox directory
4. Reads the file back from the sandbox
5. Downloads the file from the sandbox to verify the operation

File: examples/langgraph-deepagents-integration/README.md Copy Chapter

aio-deepagents

A LangGraph-based deep agent implementation that uses AIO Sandbox as a native DeepAgents sandbox backend, implementing the BaseSandbox protocol (execute, upload_files, download_files).

Features Copy Chapter

• Native Sandbox Backend: Direct integration via DeepAgents sandbox protocol
• OpenAI Compatible: Supports various LLM providers through OpenAI-compatible API
• Streaming Support: Real-time response streaming

Prerequisites Copy Chapter

• Python 3.12 or higher
• Docker (for running AIO sandbox)
• An OpenAI-compatible API key (OpenRouter, etc.)

Quick Start Copy Chapter

1. Start AIO Docker Sandbox Copy Section

For International Users:

docker run --security-opt seccomp=unconfined --rm -it -p 127.0.0.1:8080:8080 ghcr.io/agent-infra/sandbox:latest

For Users in Mainland China:

docker run --security-opt seccomp=unconfined --rm -it -p 127.0.0.1:8080:8080 enterprise-public-cn-beijing.cr.volces.com/vefaas-public/all-in-one-sandbox:latest

More information:

• AIO Sandbox Guide

2. Setup Environment Copy Section

uv venv
uv sync

3. Configure Environment Variables Copy Section

cp .env.example .env

Edit .env with your API details:

OPENAI_API_KEY=sk-xxxxx
OPENAI_MODEL_ID=anthropic/claude-sonnet-4
OPENAI_BASEURL=https://openrouter.ai/api/v1
SANDBOX_URL=http://localhost:8080

4. Run the Agent Copy Section

uv run main.py

Architecture Copy Chapter

DeepAgents Agent
    └── AIOSandboxBackend (sandbox_backend.py)
        ├── execute(cmd)       → client.bash.exec()
        ├── upload_files()     → client.file.write_file()
        └── download_files()   → client.file.read_file()
            └── agent-sandbox SDK → AIO Sandbox HTTP API

This follows the same pattern as langchain-daytona, langchain-runloop, etc.

Project Structure Copy Chapter

aio-deepagents/
├── main.py              # Main entry point
├── sandbox_backend.py   # AIOSandboxBackend — DeepAgents sandbox protocol impl
├── pyproject.toml       # Project configuration and dependencies
├── .env.example         # Environment variables template
└── README.md            # This file

Customization Copy Chapter

• Change the question: Modify the content in the astream call in main.py
• Update instructions: Change the system_prompt parameter
• Switch models: Update the OPENAI_MODEL_ID environment variable

License Copy Chapter

This project is licensed under the terms specified in the LICENSE file.

File: examples/minimax-integration/README.md Copy Chapter

MiniMax Integration Example

This example demonstrates how to use MiniMax models with agent-sandbox for safe code execution, leveraging MiniMax's OpenAI-compatible API.

Prerequisites Copy Chapter

• A running sandbox instance at http://localhost:8080
• Python 3.11+
• MiniMax API key (get one here)

Running the Example Copy Chapter

# Set your MiniMax API key
export MINIMAX_API_KEY="your_api_key"

# Run the example
uv run main.py

You can customise the model and the task via environment variables:

MINIMAX_MODEL=MiniMax-M2.7-highspeed TASK="sort a list of 100 random numbers" uv run main.py

What This Example Does Copy Chapter

1. Connects to MiniMax via the OpenAI-compatible endpoint (https://api.minimax.io/v1)
2. Sends a natural-language task to a MiniMax model (default: MiniMax-M2.7, 204K context)
3. The model generates code and calls the run_code tool
4. The code is executed inside the sandbox and results are returned

Available MiniMax Models Copy Chapter

Key Features Copy Chapter

• OpenAI-compatible — uses the standard openai Python SDK, just with a different base_url
• Safe Code Execution — all code runs in an isolated sandbox environment
• Multi-language Support — supports both Python (Jupyter) and Node.js execution
• Function Calling — leverages MiniMax's tool-use capabilities

File: examples/openai-integration/README.md Copy Chapter

OpenAI Integration Example

This example demonstrates how to integrate OpenAI's function calling with agent-sandbox to enable safe code execution in a sandboxed environment.

Prerequisites Copy Chapter

• A running sandbox instance at http://localhost:8080
• Python 3.11+
• OpenAI API key

Running the Example Copy Chapter

# Set your OpenAI API key
export OPENAI_API_KEY="your_api_key"

# Update the API key in main.py, then run
uv run main.py

What This Example Does Copy Chapter

1. Defines a run_code function that executes Python or Node.js code in the sandbox
2. Registers the function as an OpenAI tool
3. Sends a natural language request to GPT-4 (e.g., "calculate 1+1")
4. GPT-4 decides to use the run_code tool with appropriate code
5. The code is executed in the sandbox and results are returned

Key Features Copy Chapter

• Safe Code Execution: All code runs in an isolated sandbox environment
• Multi-language Support: Supports both Python (via Jupyter) and Node.js execution
• OpenAI Function Calling: Leverages GPT's ability to generate and call functions

Example Usage Copy Chapter

The example is currently configured to calculate 1+1, but you can modify the task in main.py:

messages=[{"role": "user", "content": "calculate 1+1"}]

Try different tasks like:

• "create a fibonacci sequence generator"
• "calculate the factorial of 10"
• "fetch data from an API and parse it"

File: examples/oss-upload/README.md Copy Chapter

Basic File Operations Example

This example demonstrates basic file operations with agent-sandbox, including:

• Uploading files to the sandbox
• Listing files in the sandbox
• Reading files from the sandbox
• Downloading files from the sandbox

Prerequisites Copy Chapter

• A running sandbox instance at http://localhost:8080
• Python 3.11+

Running the Example Copy Chapter

uv run main.py

What This Example Does Copy Chapter

1. Reads a local image file (foo.png)
2. Uploads it to the sandbox at /home/sandbox/test.png
3. Lists files in the sandbox directory
4. Reads the file back from the sandbox
5. Downloads the file from the sandbox to verify the operation

File: examples/playwright-integration/README.md Copy Chapter

Playwright Integration Example

This example demonstrates how to integrate Playwright with agent-sandbox, allowing you to use Playwright's powerful browser automation capabilities with a sandboxed browser.

Prerequisites Copy Chapter

• A running sandbox instance at http://localhost:8080
• Python 3.11+
• uv package manager

Running the Example Copy Chapter

# Install Playwright browsers (first time only)
uv run playwright install chromium

# Run the example
uv run main.py

What This Example Does Copy Chapter

1. Connects to the sandbox browser via CDP (Chrome DevTools Protocol)
2. Creates a new browser context and page using Playwright
3. Navigates to DuckDuckGo and performs a search
4. Extracts the first search result's title and link
5. Takes a screenshot of the search results page
6. Saves the screenshot as search_results.png

Configuration Copy Chapter

You can modify the automation script in main.py to perform different tasks:

# Navigate to a website
await page.goto("https://example.com")

# Interact with elements
await page.click('button[type="submit"]')
await page.fill('input[name="email"]', "[email protected]")

# Wait for elements
await page.wait_for_selector('.result')

# Extract data
title = await page.title()
text = await page.locator('.content').inner_text()

# Take screenshots
await page.screenshot(path="screenshot.png")

Key Features Copy Chapter

• Browser Automation: Full Playwright API for browser control
• Sandboxed Execution: Browser runs in isolated sandbox environment
• CDP Integration: Connect via Chrome DevTools Protocol
• Screenshot Support: Capture visual output
• Element Selection: Powerful selectors and locators
• Async/Await: Modern async Python patterns

Advanced Usage Copy Chapter

Multiple Pages Copy Section

page1 = await context.new_page()
page2 = await context.new_page()

await page1.goto("https://example1.com")
await page2.goto("https://example2.com")

Network Interception Copy Section

await page.route("**/*.{png,jpg,jpeg}", lambda route: route.abort())

Emulation Copy Section

context = await browser.new_context(
    viewport={'width': 1280, 'height': 720},
    user_agent='Custom User Agent'
)

Resources Copy Chapter

• Playwright Documentation
• Agent Sandbox Documentation
• Playwright Selectors Guide

File: examples/site-to-markdown/README.md Copy Chapter

Site to Markdown Example

This example demonstrates how to combine multiple sandbox features:

• Browser automation with Playwright
• Jupyter code execution for HTML processing
• File operations

The example fetches a website, converts it to markdown, and saves it with a screenshot.

Prerequisites Copy Chapter

• A running sandbox instance at http://localhost:8080
• Python 3.11+
• Playwright installed (will be installed automatically with dependencies)

Running the Example Copy Chapter

# Install Playwright browsers (first time only)
uv run playwright install

# Run the example
uv run main.py

What This Example Does Copy Chapter

1. Connects to the sandbox browser via CDP
2. Navigates to a website (https://sandbox.agent-infra.com/)
3. Captures the HTML content and screenshot
4. Uses Jupyter in the sandbox to convert HTML to markdown using markdownify
5. Saves the markdown file with embedded screenshot
6. Downloads the result to local filesystem as output.md

File: examples/volcengine-provider/README.md Copy Chapter

Volcengine Provider Example

This example demonstrates how to use the Volcengine cloud provider to create and manage sandbox instances using the Volcengine VEFAAS API.

Prerequisites Copy Chapter

• Volcengine account with VEFAAS access
• Environment variables set:
  • VOLCENGINE_ACCESS_KEY: Your Volcengine access key
  • VOLCENGINE_SECRET_KEY: Your Volcengine secret key
  • VOLCENGINE_REGION: Region (default: cn-beijing)
• Python 3.11+

Running the Example Copy Chapter

export VOLCENGINE_ACCESS_KEY="your_access_key"
export VOLCENGINE_SECRET_KEY="your_secret_key"
export VOLCENGINE_REGION="cn-beijing"

uv run main.py

What This Example Does Copy Chapter

1. Creates a Volcengine application
2. Waits for the application to be ready
3. Creates a sandbox instance
4. Lists all sandboxes for the function
5. Gets sandbox details and public domain
6. Tests the sandbox by listing files
7. Deletes the sandbox instance

File: sdk/fern/fern.config.json Copy Chapter

{
"organization": "sandbox",
"version": "0.85.1"
}

File: sdk/fern/generators.yml Copy Chapter

yaml-language-server: $schema=https://schema.buildwithfern.dev/generators-yml.json

api:
specs:
- openapi: ../../website/docs/public/v1/openapi.json
default-group: python-sdk
groups:
python-sdk:
generators:
- name: fernapi/fern-python-sdk
version: 4.28.0
config:
package_name: "agent_sandbox"
pydantic_config:
skip_validation: false
smart_union: true
client_class_name: "Sandbox"
client:
class_name: "Sandbox"
output:
location: local-file-system
path: ../python/agent_sandbox
js-sdk:
generators:
- name: fernapi/fern-typescript-sdk
version: 3.28.4
config:
namespaceExport: Sandbox
allowCustomFetcher: true
skipResponseValidation: true
includeApiReference: true
noSerdeLayer: true
omitUndefined: true
enableInlineTypes: false
neverThrowErrors: true
smart-casing: true
output:
location: local-file-system
path: ../js/src
sdk-go:
generators:
- name: fernapi/fern-go-sdk
version: 1.12.4
output:
location: local-file-system
path: ../../sandbox-sdk-go
config:
module:
path: github.com/agent-infra/sandbox-sdk-go

File: sdk/go/README.md Copy Chapter

Go SDK

Please refer to https://github.com/agent-infra/sandbox-sdk-go.

File: sdk/js/README.md Copy Chapter

@agent-infra/sandbox

Node.js/TypeScript SDK for AIO Sandbox integration, providing tools and interfaces for sandbox management and cloud provider integrations.

Installation Copy Chapter

npm install @agent-infra/sandbox

or with yarn:

yarn add @agent-infra/sandbox

or with pnpm:

pnpm add @agent-infra/sandbox

Quick Start Copy Chapter

Basic Usage Copy Section

import { SandboxApiClient } from '@agent-infra/sandbox';

// Initialize the client
const client = new SandboxApiClient({
  environment: 'https://your-sandbox-api.com',
  // Add authentication if required
});

// Use the API
const result = await client.file.read({
  path: '/path/to/file',
});

console.log(result);

Using Cloud Providers Copy Section

The SDK includes provider implementations for managing sandboxes on different cloud platforms.

Volcengine Provider

import { providers } from '@agent-infra/sandbox';

// Initialize Volcengine provider
const volcengineProvider = new providers.VolcengineProvider({
  accessKey: process.env.VOLCENGINE_ACCESS_KEY,
  secretKey: process.env.VOLCENGINE_SECRET_KEY,
  region: 'cn-beijing', // Optional, defaults to 'cn-beijing'
});

// Create a sandbox
const sandboxId = await volcengineProvider.createSandbox(
  'your-function-id',
  30 // timeout in minutes
);
console.log('Created sandbox:', sandboxId);

// Get sandbox details with APIG domains
const sandbox = await volcengineProvider.getSandbox(
  'your-function-id',
  sandboxId
);
console.log('Sandbox domains:', sandbox.domains);

// List all sandboxes for a function
const sandboxes = await volcengineProvider.listSandboxes('your-function-id');
console.log('Total sandboxes:', sandboxes.length);

// Delete a sandbox
await volcengineProvider.deleteSandbox('your-function-id', sandboxId);
console.log('Sandbox deleted');

Application Management

// Create an application
const appId = await volcengineProvider.createApplication(
  'my-app',
  'my-gateway'
);

// Check application readiness
const [isReady, functionId] = await volcengineProvider.getApplicationReadiness(appId);
if (isReady) {
  console.log('Application is ready, function ID:', functionId);
}

// Get APIG domains for a function
const domains = await volcengineProvider.getApigDomains('your-function-id');
console.log('Available domains:', domains);

Features Copy Chapter

Sandbox API Client Copy Section

• File Operations: Read, write, search, and manage files
• Shell Execution: Execute shell commands and manage sessions
• Browser Automation: Control browser actions and retrieve information
• Code Execution: Execute code in various languages (Python, Node.js, Jupyter)
• MCP Integration: Execute MCP (Model Context Protocol) tools

Cloud Providers Copy Section

Volcengine Provider

• ✅ Sandbox lifecycle management (create, delete, get, list)
• ✅ Application deployment and monitoring
• ✅ APIG (API Gateway) domain management
• ✅ Automatic request signing with HMAC-SHA256
• ✅ Support for temporary credentials

Extensible Provider System

Create custom providers by extending the BaseProvider class:

import { providers } from '@agent-infra/sandbox';

class MyCustomProvider extends providers.BaseProvider {
  async createSandbox(functionId: string, ...kwargs: any[]): Promise<any> {
    // Your implementation
  }

  async deleteSandbox(functionId: string, sandboxId: string, ...kwargs: any[]): Promise<any> {
    // Your implementation
  }

  async getSandbox(functionId: string, sandboxId: string, ...kwargs: any[]): Promise<any> {
    // Your implementation
  }

  async listSandboxes(functionId: string, ...kwargs: any[]): Promise<any> {
    // Your implementation
  }
}

API Reference Copy Chapter

SandboxApiClient Copy Section

The main client for interacting with the Sandbox API.

const client = new SandboxApiClient({
  environment: string,          // API base URL
  timeout?: number,             // Request timeout in milliseconds
  headers?: Record<string, string>, // Custom headers
});

Available Modules

• client.file - File operations
• client.shell - Shell command execution
• client.browser - Browser automation
• client.code - Code execution
• client.jupyter - Jupyter notebook operations
• client.nodejs - Node.js specific operations
• client.mcp - MCP tool execution

Providers Copy Section

BaseProvider (Abstract)

Base class for all cloud provider implementations.

Methods:

• createSandbox(functionId: string, ...kwargs: any[]): Promise<any>
• deleteSandbox(functionId: string, sandboxId: string, ...kwargs: any[]): Promise<any>
• getSandbox(functionId: string, sandboxId: string, ...kwargs: any[]): Promise<any>
• listSandboxes(functionId: string, ...kwargs: any[]): Promise<any>

VolcengineProvider

Volcengine VEFAAS implementation.

Constructor Options:

{
  accessKey: string;              // Volcengine access key ID
  secretKey: string;              // Volcengine secret access key
  region?: string;                // Region (default: 'cn-beijing')
  clientSideValidation?: boolean; // Enable validation (default: true)
}

Additional Methods:

• createApplication(name: string, gatewayName: string): Promise<string | null>
• getApplicationReadiness(id: string): Promise<[boolean, string | null]>
• getApigDomains(functionId: string): Promise<DomainInfo[]>

Environment Variables Copy Chapter

Configure Volcengine credentials using environment variables:

# Volcengine credentials (option 1)
VOLCENGINE_ACCESS_KEY=your-access-key
VOLCENGINE_SECRET_KEY=your-secret-key

# Volcengine credentials (option 2)
VOLC_ACCESSKEY=your-access-key
VOLC_SECRETKEY=your-secret-key

TypeScript Support Copy Chapter

This package is written in TypeScript and includes full type definitions. TypeScript 5.0+ is recommended.

import type {
  SandboxApi,
  BaseClientOptions,
  BaseRequestOptions
} from '@agent-infra/sandbox';

Examples Copy Chapter

Execute Shell Command Copy Section

const result = await client.shell.exec({
  command: 'ls -la',
  timeout: 5000,
});
console.log(result.stdout);

Read File Copy Section

const fileContent = await client.file.read({
  path: '/path/to/file.txt',
});
console.log(fileContent.content);

Browser Automation Copy Section

const browserInfo = await client.browser.info();
console.log('Browser:', browserInfo);

await client.browser.config({
  action: {
    type: 'click',
    selector: '#button',
  },
});

Execute Python Code Copy Section

const result = await client.code.execute({
  code: 'print("Hello from sandbox!")',
  language: 'python',
});
console.log(result.output);

Error Handling Copy Chapter

import { SandboxApiError, SandboxApiTimeoutError } from '@agent-infra/sandbox';

try {
  const result = await client.file.read({ path: '/nonexistent' });
} catch (error) {
  if (error instanceof SandboxApiTimeoutError) {
    console.error('Request timed out');
  } else if (error instanceof SandboxApiError) {
    console.error('API error:', error.statusCode, error.message);
  } else {
    console.error('Unexpected error:', error);
  }
}

Development Copy Chapter

Project Structure Copy Section

sdk/js/
├── src/              # TypeScript source code
│   ├── api/          # Generated API modules
│   ├── core/         # Core utilities
│   ├── errors/       # Error classes
│   ├── providers/    # Cloud provider implementations (custom code)
│   │   ├── base.ts       # Base provider interface
│   │   ├── volcengine.ts # Volcengine implementation
│   │   ├── sign.ts       # Request signing utilities
│   │   └── README.md     # Provider documentation
│   ├── BaseClient.ts # Base client implementation
│   ├── Client.ts     # Main API client
│   └── index.ts      # Package entry point
├── dist/             # Compiled JavaScript output (generated by build)
├── package.json      # Package configuration
└── tsconfig.json     # TypeScript configuration

Building Copy Section

The SDK uses TypeScript and compiles source code from src/ to dist/:

npm run build

This will:

1. Compile TypeScript files from src/ to JavaScript in dist/
2. Generate .d.ts type definition files
3. Generate source maps for debugging

Testing Copy Section

npm test

# With coverage
npm run test:coverage

# With UI
npm run test:ui

Development Mode Copy Section

npm run dev  # Watch mode with auto-rebuild

Generating SDK Copy Section

The base SDK code is generated using Fern:

cd sdk/fern
fern generate --group nodejs-sdk --local

This generates TypeScript code from the OpenAPI specification into src/.
Custom providers in src/providers/ are preserved via .fernignore.

Contributing Copy Chapter

Contributions are welcome! Please feel free to submit a Pull Request.

Adding Custom Providers Copy Section

See providers/README.md for detailed information on implementing custom cloud providers.

License Copy Chapter

ISC

Links Copy Chapter

• Repository
• Issues
• Volcengine Documentation

Support Copy Chapter

For questions and support, please open an issue on GitHub.

Version: 1.0.0
Node.js: >=18.0.0
TypeScript: >=5.0.0

File: sdk/js/package.json Copy Chapter

{
"name": "@agent-infra/sandbox",
"version": "1.0.17",
"description": "Node.js SDK for AIO Sandbox integration providing tools and interfaces",
"main": "./dist/cjs/index.js",
"module": "./dist/esm/index.mjs",
"types": "./dist/types/index.d.ts",
"exports": {
".": {
"types": "./dist/types/index.d.ts",
"import": "./dist/esm/index.mjs",
"require": "./dist/cjs/index.js"
}
},
"scripts": {
"build": "rslib build && tsc",
"prepublishOnly": "npm run build",
"test": "vitest",
"test:coverage": "vitest --coverage",
"test:ui": "vitest --ui",
"dev": "tsc --watch",
"clean": "rimraf dist"
},
"repository": {
"type": "git",
"url": "git+https://github.com/agent-infra/sandbox-sdk.git",
"directory": "js"
},
"files": [
"dist",
"README.md",
"package.json"
],
"keywords": [
"aio",
"sandbox",
"sdk",
"nodejs",
"typescript"
],
"author": "",
"license": "ISC",
"devDependencies": {
"@rslib/core": "^0.17.1",
"@types/node": "^20.19.24",
"@vitest/coverage-v8": "^1.0.0",
"@vitest/ui": "^1.0.0",
"rimraf": "^5.0.0",
"typescript": "^5.9.3",
"vitest": "^1.0.0"
},
"engines": {
"node": ">=18.0.0"
}
}

File: sdk/js/tsconfig.json Copy Chapter

{
"compilerOptions": {
"target": "ES2020",
"module": "ESNext",
"lib": ["ES2020"],
"types": ["node"],
"declaration": true,
"declarationMap": true,
"sourceMap": true,
"rootDir": "./src",
"removeComments": true,
"strict": false,
"skipLibCheck": true,
"noEmitOnError": false,
"esModuleInterop": true,
"forceConsistentCasingInFileNames": false,
"moduleResolution": "bundler",
"resolveJsonModule": true,
"allowSyntheticDefaultImports": true,
"noUnusedLocals": false,
"noUnusedParameters": false,
"exactOptionalPropertyTypes": false,
"emitDeclarationOnly": true,
"outDir": "./dist/types"
},
"include": ["src//*"],
"exclude": ["node_modules", "dist", "/.test.ts", "**/.spec.ts"]
}

File: sdk/js/examples/README.md Copy Chapter

Sandbox SDK Examples

TypeScript examples demonstrating usage of the @agent-infra/sandbox SDK.

Examples Copy Chapter

1. simple-examples.ts Copy Section

Basic, straightforward examples covering core SDK functionality:

• Getting sandbox context
• Executing shell commands
• Running Python code
• File operations (write, read, list, find, search)

2. basic-usage.ts Copy Section

Fundamental sandbox operations:

• Sandbox context retrieval
• Shell command execution
• Python code execution
• File read/write operations
• Directory listing
• Python package information

3. volcengine-provider.ts Copy Section

Volcengine cloud provider integration:

• Creating sandboxes with configuration
• Getting sandbox information
• Listing sandboxes
• Deleting sandboxes

4. advanced-usage.ts Copy Section

Comprehensive demonstration of SDK features:

• File operations (read, write, list, search, find)
• Code execution (Python, JavaScript, Node.js)
• Shell commands
• Volcengine provider workflow

5. error-handling.ts Copy Section

Error handling patterns and resilience strategies:

• Error type detection and handling
• Retry logic with exponential backoff
• Circuit breaker pattern
• Graceful degradation

Running Examples Copy Chapter

Install dependencies first:

npm install

Run individual examples:

npm run simple      # Simple examples
npm run basic       # Basic usage
npm run volcengine  # Volcengine provider
npm run advanced    # Advanced usage
npm run error       # Error handling

Run all examples:

npm run all

Environment Variables Copy Chapter

For Volcengine examples:

export VOLCENGINE_ACCESS_KEY=your-access-key
export VOLCENGINE_SECRET_KEY=your-secret-key

For custom sandbox URL:

export SANDBOX_API_URL=http://your-sandbox:8080

Type Checking Copy Chapter

Check TypeScript types:

npm run build

Known SDK Issues Copy Section

The SDK source has several TypeScript compilation errors that prevent clean builds:

1. Missing errors module (./errors/index.js): The SandboxError and SandboxTimeoutError classes are exported but the module doesn't exist
2. HeadersIterator type: DOM type HeadersIterator is not found
3. Buffer/Blob compatibility: Type incompatibility between Node.js Buffer and DOM Blob
4. APIResponse error property: Many client methods try to access .error on wrong response type

These are SDK build issues, not example code issues. All example TypeScript code is syntactically correct and will run properly with tsx even though tsc reports errors from the SDK internals.

To run examples without type checking:

npx tsx simple-examples.ts
npx tsx basic-usage.ts
# etc.

Example Code Patterns Copy Chapter

API Response Pattern Copy Section

All SDK methods return APIResponse<T, E> with .ok discriminator:

const response = await client.file.readFile({ file: '/tmp/test.txt' });

if (response.ok) {
  console.log('Success:', response.body);
} else {
  console.error('Error:', response.error);
}

Error Handling Copy Section

try {
  const response = await client.shell.execCommand({
    command: 'echo "Hello"'
  });
  
  if (!response.ok) {
    console.error('Command failed');
  }
} catch (error) {
  if (error instanceof Error) {
    console.error('Error:', error.message);
  }
}

File Operations Copy Section

// Write
await client.file.writeFile({
  file: '/tmp/test.txt',
  content: 'Hello World'
});

// Read
const read = await client.file.readFile({ 
  file: '/tmp/test.txt' 
});

// List
const list = await client.file.listPath({ 
  path: '/tmp' 
});

// Search
const search = await client.file.searchInFile({
  file: '/tmp/test.txt',
  regex: 'pattern'
});

// Find
const find = await client.file.findFiles({
  path: '/tmp',
  glob: '*.txt'
});

Code Execution Copy Section

// Python
await client.code.executeCode({
  language: 'python',
  code: 'print("Hello from Python!")'
});

// JavaScript
await client.code.executeCode({
  language: 'javascript',
  code: 'console.log("Hello from JS!")'
});

// Node.js
await client.nodejs.executeCode({
  code: 'console.log(process.version)'
});

File: sdk/js/examples/package.json Copy Chapter

{
"name": "@agent-infra/sandbox-examples",
"version": "1.0.0",
"private": true,
"type": "module",
"scripts": {
"build": "tsc",
"simple": "tsx simple-examples.ts",
"basic": "tsx basic-usage.ts",
"volcengine": "tsx volcengine-provider.ts",
"error": "tsx error-handling.ts",
"advanced": "tsx advanced-usage.ts",
"all": "npm run simple && npm run basic && npm run error && npm run advanced"
},
"dependencies": {
"@agent-infra/sandbox": "file:.."
},
"devDependencies": {
"@types/node": "^20.19.24",
"tsx": "^4.7.0",
"typescript": "^5.9.3"
}
}

File: sdk/js/examples/tsconfig.json Copy Chapter

{
"compilerOptions": {
"target": "ES2020",
"module": "ESNext",
"lib": ["ES2020", "DOM"],
"noEmit": true,
"moduleResolution": "bundler",
"esModuleInterop": true,
"skipLibCheck": true,
"strict": true,
"resolveJsonModule": true,
"isolatedModules": true,
"types": ["node"]
},
"include": ["./*.ts"],
"exclude": ["node_modules", "../src"]
}

File: sdk/js/src/providers/README.md Copy Chapter

Sandbox Providers

This directory contains custom cloud provider implementations for sandbox management.

Volcengine Provider Copy Chapter

The Volcengine provider integrates with Volcengine VEFAAS (Volcengine Function as a Service) API to manage sandbox instances.

Installation Copy Section

The provider is included in the @agent-infra/sandbox package. Install it via npm:

npm install @agent-infra/sandbox

Usage Copy Section

import { providers } from '@agent-infra/sandbox';

// Initialize the Volcengine provider
const provider = new providers.VolcengineProvider({
  accessKey: 'your-access-key',
  secretKey: 'your-secret-key',
  region: 'cn-beijing', // Optional, defaults to 'cn-beijing'
  clientSideValidation: true, // Optional, defaults to true
});

// Create a sandbox
const sandboxId = await provider.createSandbox('function-id', 30);

// Get sandbox details
const sandbox = await provider.getSandbox('function-id', sandboxId);

// List all sandboxes
const sandboxes = await provider.listSandboxes('function-id');

// Delete a sandbox
await provider.deleteSandbox('function-id', sandboxId);

// Set sandbox timeout
await provider.setSandboxTimeout('function-id', sandboxId, 120);

Application Management Copy Section

The provider also supports application lifecycle management:

// Create an application
const applicationId = await provider.createApplication('app-name', 'gateway-name');

// Check application readiness
const [isReady, functionId] = await provider.getApplicationReadiness(applicationId);

// Get APIG domains for a function
const domains = await provider.getApigDomains('function-id');

Custom Providers Copy Chapter

To create a custom provider, extend the BaseProvider class:

import { providers } from '@agent-infra/sandbox';

class MyCustomProvider extends providers.BaseProvider {
  async createSandbox(functionId: string, ...kwargs: any[]): Promise<any> {
    // Implementation
  }

  async deleteSandbox(functionId: string, sandboxId: string, ...kwargs: any[]): Promise<any> {
    // Implementation
  }

  async getSandbox(functionId: string, sandboxId: string, ...kwargs: any[]): Promise<any> {
    // Implementation
  }

  async listSandboxes(functionId: string, ...kwargs: any[]): Promise<any> {
    // Implementation
  }
}

API Reference Copy Chapter

BaseProvider (Abstract) Copy Section

Base class for all cloud provider implementations.

Methods

• createSandbox(functionId: string, ...kwargs: any[]): Promise<any>
• deleteSandbox(functionId: string, sandboxId: string, ...kwargs: any[]): Promise<any>
• getSandbox(functionId: string, sandboxId: string, ...kwargs: any[]): Promise<any>
• listSandboxes(functionId: string, ...kwargs: any[]): Promise<any>

VolcengineProvider Copy Section

Volcengine VEFAAS implementation of the BaseProvider.

Constructor Options

• accessKey (string): Volcengine access key ID
• secretKey (string): Volcengine secret access key
• region (string, optional): Volcengine region, defaults to 'cn-beijing'
• clientSideValidation (boolean, optional): Enable client-side validation, defaults to true

Additional Methods

• createApplication(name: string, gatewayName: string, ...kwargs: any[]): Promise<string | null>
• getApplicationReadiness(id: string, ...kwargs: any[]): Promise<[boolean, string | null]>
• getApigDomains(functionId: string): Promise<DomainInfo[]>
• setSandboxTimeout(functionId: string, sandboxId: string, timeout: number): Promise<any>

Environment Variables Copy Chapter

For the Volcengine provider, you can also configure credentials using environment variables:

• VOLCENGINE_ACCESS_KEY
• VOLCENGINE_SECRET_KEY

License Copy Chapter

Apache License 2.0

File: sdk/python/README.md Copy Chapter

Agent Sandbox Python SDK

A Python SDK for the All-in-One Sandbox API, providing access to sandbox, shell, file, jupyter, nodejs, and mcp services.

Installation Copy Chapter

pip install agent-sandbox

Usage Copy Chapter

from agent_sandbox import Sandbox

client = Sandbox(base_url="http://localhost:8091")

ctx = client.sandbox.get_context()
print(ctx)

result = client.shell.exec_command(command="ls -la")
print(result)

Async Support Copy Chapter

The SDK also provides async support through the AsyncSandbox class:

import asyncio
from agent_sandbox import AsyncSandbox

async def main():
    client = AsyncSandbox(base_url="http://localhost:8091")
    
    # Get sandbox context
    ctx = await client.sandbox.get_context()
    print(ctx)

    result = await client.shell.exec_command(command="ls -la")
    print(result)

asyncio.run(main())

Cloud Providers Copy Chapter

Volcengine Copy Section

Create a sandbox instance using the Volcengine provider. For more details, please refer to examples/provider_volcengine.py.

from __future__ import print_function

import os
import sys

# Add the parent directory to Python path so we can import agent_sandbox
sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))

from agent_sandbox.providers import VolcengineProvider


def main():
    """
    Main function demonstrating Volcengine provider usage.
    """
    # Configuration - replace with your actual credentials
    access_key = os.getenv("VOLC_ACCESSKEY")
    secret_key = os.getenv("VOLC_SECRETKEY")
    region = os.getenv("VOLCENGINE_REGION", "cn-beijing")
    
    # Initialize the Volcengine provider
    provider = VolcengineProvider(
        access_key=access_key,
        secret_key=secret_key,
        region=region
    )
    
    print("=== Volcengine Sandbox Provider Example ===\n")
    
    function_id = "yatoczqh"
    
    print("1. Creating a sandbox...")
    sandbox_id = provider.create_sandbox(function_id=function_id)
    print(f"Create response: {sandbox_id}")


if __name__ == "__main__":
    main()

Features Copy Chapter

• Sandbox: Access sandbox environment information and installed packages
• Shell: Execute shell commands with session management
• File: Read, write, search, and manage files
• Jupyter: Execute Python code in Jupyter kernels
• Node.js: Execute JavaScript code in Node.js environment
• MCP: Interact with Model Context Protocol servers

Requirements Copy Chapter

• Python 3.8+
• httpx
• pydantic
• typing_extensions (for Python < 3.10)

File: sdk/python/agent_sandbox/providers/README.md Copy Chapter

Cloud Providers

This module contains cloud provider implementations for sandbox management.

Volcengine Copy Chapter

The Volcengine provider integrates with Volcengine VEFAAS APIs to manage sandbox instances.

from agent_sandbox.providers import VolcengineProvider

provider = VolcengineProvider(
    access_key="your-access-key",
    secret_key="your-secret-key",
    region="cn-beijing",
)

sandbox_id = provider.create_sandbox("function-id", timeout=30)
sandbox = provider.get_sandbox("function-id", sandbox_id)
sandboxes = provider.list_sandboxes("function-id")
provider.set_sandbox_timeout("function-id", sandbox_id, 120)
provider.delete_sandbox("function-id", sandbox_id)

File: website/i18n.json Copy Chapter

{
"oneLineCommand": {
"zh": "docker run --rm -it -p 127.0.0.1:8080:8080 enterprise-public-cn-beijing.cr.volces.com/vefaas-public/all-in-one-sandbox:latest",
"en": "docker run --rm -it -p 127.0.0.1:8080:8080 ghcr.io/agent-infra/sandbox:latest"
},
"gettingStarted": {
"zh": "开始",
"en": "Getting Started"
},
"features": {
"zh": "特性",
"en": "Features"
},
"defaultTheme": {
"zh": "默认主题",
"en": "Default Theme"
},
"advanced": {
"zh": "高级能力",
"en": "Advanced"
},
"apiOverview": {
"zh": "API 概览",
"en": "API Overview"
},
"config": {
"zh": "配置",
"en": "Config"
},
"loadingApiReference": {
"zh": "正在加载 API 文档...",
"en": "Loading API Reference..."
},
"searchPlaceholderText": {
"zh": "搜索",
"en": "Search"
},
"searchPanelCancelText": {
"zh": "取消",
"en": "Cancel"
},
"searchNoResultsText": {
"zh": "未找到匹配的结果",
"en": "No matching results"
},
"searchSuggestedQueryText": {
"zh": "尝试搜索其他关键词",
"en": "Try searching for different keywords"
},
"footerMessage": {
"zh": "为 AI Agents 打造 · AIO Sandbox © 2026",
"en": "Built with ❤️ for AI Agents · AIO Sandbox © 2026"
}
}

File: website/package.json Copy Chapter

{
"name": "website",
"version": "1.0.0",
"private": true,
"scripts": {
"build": "rspress build",
"check": "biome check --write",
"dev": "rspress dev",
"format": "prettier --write .",
"preview": "rspress preview",
"deploy": "npm run build && npm run preview"
},
"dependencies": {
"@rspress/core": "2.0.21",
"@rspress/plugin-llms": "2.0.21",
"@scalar/api-reference-react": "0.8.6",
"core-js": "^3.45.1"
},
"devDependencies": {
"@biomejs/biome": "^1.9.4",
"@rsbuild/plugin-sass": "2.0.1",
"@rsbuild/plugin-svgr": "^2.0.5",
"@rspress/plugin-sitemap": "2.0.21",
"@shikijs/transformers": "^3.13.0",
"@types/node": "^18.11.17",
"@types/react": "^19.2.14",
"prettier": "^3.4.2",
"rsbuild-plugin-google-analytics": "1.0.6",
"rsbuild-plugin-open-graph": "1.1.3",
"rspress-plugin-font-open-sans": "1.0.4"
}
}

File: website/tsconfig.json Copy Chapter

{
"compilerOptions": {
"target": "ES2020",
"lib": ["DOM", "ES2020"],
"module": "ESNext",
"jsx": "react-jsx",
"noEmit": true,
"strict": true,
"skipLibCheck": true,
"isolatedModules": true,
"resolveJsonModule": true,
"moduleResolution": "bundler",
"useDefineForClassFields": true,
"allowImportingTsExtensions": true
},
"include": ["docs", "theme", "rspress.config.ts"],
"mdx": {
"checkMdx": true
}
}

File: website/diagrams/README.md Copy Chapter

Diagram sources

Archify specs (skill tt-a1i/archify). Regenerate with
node bin/archify.mjs deliver <type> <name>.<type>.json <name>.html --quality showcase,
then export SVG from the delivered viewer into docs/public/architecture/<name>.svg:

• aiod-overview.architecture.json — the Introduction hero.
• aiod-permission-model.architecture.json — the permission model (Daemon → Architecture).
• aiod-browser-cdp.architecture.json — the two browser paths (Daemon → Browser API).
• aiod-jupyter-kernel.architecture.json — the kernels aiod spawns (Daemon → Jupyter).
• aiod-human-in-loop.architecture.json — agent and person on the same objects (Daemon → Computer Use).
• aiod-mcp-flow.architecture.json — one endpoint, one tool list (Daemon → examples → MCP).
• aio-sandbox-overview.architecture.json — the surfaces inside the container (Guide → Introduction).
• aio-agent-calls-sandbox.architecture.json — agent outside, capabilities inside (Guide → Agent Call Sandbox vs In Sandbox).
• aio-agent-in-sandbox.architecture.json — agent process inside the container (Guide → Agent Call Sandbox vs In Sandbox).
• aiod-existing-environment.architecture.json — aiod added into an existing container, VM or desktop (Daemon → Introduction).
• aiod-watch-flow.sequence.json — watch, poll, stop (Daemon → Files, Daemon → examples → file ops).
• aiod-code-execution-flow.sequence.json — dataset in, chart out (Daemon → examples → code execution).
• aiod-code-backends.sequence.json — which backend runs the code (Daemon → Code).
• aiod-browser-use-flow.sequence.json — serve a page, then drive it (Daemon → examples → browser use).
• aiod-terminal-flow.sequence.json — create, attach, run (Daemon → examples → terminal).
• aiod-terminal-reconnect.sequence.json — reattach with and without durable (Daemon → examples → terminal).
• aiod-computer-action.sequence.json — one computer action, then the accessibility tree (Daemon → Computer Use).

*.html without a matching spec are hand-drawn SVG sources; the <svg> element is
extracted verbatim into docs/public/architecture/<name>.svg.

aiod-capabilities.gen.py writes the capability status board straight to docs/public/architecture/aiod-capabilities.svg.

File: website/diagrams/aio-agent-calls-sandbox.architecture.json Copy Chapter

{
"schema_version": 1,
"diagram_type": "architecture",
"meta": {
"title": "Agent calls the sandbox",
"quality_profile": "showcase",
"visual_preset": "signal-flow",
"locale": "en"
},
"layout": {
"mode": "grid",
"cols": 3,
"cellW": 176,
"cellH": 72,
"gapX": 144,
"gapY": 56
},
"components": [
{
"id": "agent",
"type": "external",
"label": "Agent",
"sublabel": "LLM · orchestration",
"row": 1,
"col": 0,
"size": [
176,
72
]
},
{
"id": "api",
"type": "backend",
"label": "Sandbox API",
"sublabel": "REST · SDK · MCP",
"row": 1,
"col": 1,
"size": [
176,
72
]
},
{
"id": "shell",
"type": "backend",
"label": "Shell",
"sublabel": "commands · PTY",
"row": 0,
"col": 2,
"size": [
176,
72
]
},
{
"id": "files",
"type": "backend",
"label": "Files",
"sublabel": "read · write",
"row": 1,
"col": 2,
"size": [
176,
72
]
},
{
"id": "browser",
"type": "backend",
"label": "Browser",
"sublabel": "CDP",
"row": 2,
"col": 2,
"size": [
176,
72
]
}
],
"boundaries": [
{
"kind": "region",
"label": "AIO Sandbox",
"wraps": [
"api",
"shell",
"files",
"browser"
]
}
],
"connections": [
{
"id": "agent-api",
"from": "agent",
"to": "api",
"label": "HTTP · :8080",
"variant": "emphasis"
},
{
"id": "api-shell",
"from": "api",
"to": "shell"
},
{
"id": "api-files",
"from": "api",
"to": "files"
},
{
"id": "api-browser",
"from": "api",
"to": "browser"
}
]
}

File: website/diagrams/aio-agent-in-sandbox.architecture.json Copy Chapter

{
"schema_version": 1,
"diagram_type": "architecture",
"meta": {
"title": "Agent inside the sandbox",
"quality_profile": "showcase",
"visual_preset": "signal-flow",
"locale": "en"
},
"layout": {
"mode": "grid",
"cols": 3,
"cellW": 176,
"cellH": 64,
"gapX": 144,
"gapY": 32
},
"components": [
{
"id": "agent",
"type": "external",
"label": "Agent process",
"sublabel": "local commands · files",
"row": 1,
"col": 0,
"size": [
176,
64
]
},
{
"id": "api",
"type": "backend",
"label": "Sandbox API",
"sublabel": "REST · SDK · MCP",
"row": 1,
"col": 1,
"size": [
176,
64
]
},
{
"id": "shell",
"type": "backend",
"label": "Shell",
"sublabel": "commands · PTY",
"row": 0,
"col": 2,
"size": [
176,
64
]
},
{
"id": "files",
"type": "backend",
"label": "Files",
"sublabel": "read · write",
"row": 1,
"col": 2,
"size": [
176,
64
]
},
{
"id": "browser",
"type": "backend",
"label": "Browser",
"sublabel": "CDP",
"row": 2,
"col": 2,
"size": [
176,
64
]
},
{
"id": "code",
"type": "backend",
"label": "Code",
"sublabel": "Python · Node",
"row": 3,
"col": 2,
"size": [
176,
64
]
}
],
"boundaries": [
{
"kind": "region",
"label": "AIO Sandbox",
"wraps": [
"agent",
"api",
"shell",
"files",
"browser",
"code"
]
}
],
"connections": [
{
"id": "agent-api",
"from": "agent",
"to": "api",
"label": "127.0.0.1:8080",
"variant": "emphasis"
},
{
"id": "api-shell",
"from": "api",
"to": "shell"
},
{
"id": "api-files",
"from": "api",
"to": "files"
},
{
"id": "api-browser",
"from": "api",
"to": "browser"
},
{
"id": "api-code",
"from": "api",
"to": "code"
}
]
}

File: website/diagrams/aio-sandbox-overview.architecture.json Copy Chapter

{
"schema_version": 1,
"diagram_type": "architecture",
"meta": {
"title": "AIO Sandbox surfaces",
"quality_profile": "showcase",
"visual_preset": "signal-flow",
"locale": "en"
},
"layout": {
"mode": "grid",
"cols": 5,
"cellW": 176,
"cellH": 72,
"gapX": 72,
"gapY": 48
},
"components": [
{
"id": "agent",
"type": "external",
"label": "Agent",
"sublabel": "tool calls",
"row": 1,
"col": 0,
"size": [
176,
72
]
},
{
"id": "gateway",
"type": "backend",
"label": "nginx",
"row": 1,
"col": 1,
"sublabel": ":8080",
"size": [
176,
72
]
},
{
"id": "browser",
"type": "frontend",
"label": "Browser",
"sublabel": "VNC · CDP",
"row": 0,
"col": 2,
"size": [
176,
72
]
},
{
"id": "shell",
"type": "backend",
"label": "Shell",
"sublabel": "WebSocket",
"row": 0,
"col": 3,
"size": [
176,
72
]
},
{
"id": "files",
"type": "backend",
"label": "Files",
"sublabel": "API",
"row": 1,
"col": 2,
"size": [
176,
72
]
},
{
"id": "code",
"type": "backend",
"label": "Code",
"sublabel": "execute",
"row": 1,
"col": 3,
"size": [
176,
72
]
},
{
"id": "mcp",
"type": "backend",
"label": "MCP Hub",
"sublabel": "tools",
"row": 2,
"col": 2,
"size": [
424,
72
]
},
{
"id": "vscode",
"type": "frontend",
"label": "VSCode Server",
"sublabel": "code-server",
"row": 0,
"col": 4,
"size": [
176,
72
]
},
{
"id": "preview",
"type": "backend",
"label": "Preview proxy",
"sublabel": "ports",
"row": 1,
"col": 4,
"size": [
176,
72
]
},
{
"id": "services",
"type": "backend",
"label": "Services",
"sublabel": "processes",
"row": 2,
"col": 4,
"size": [
176,
72
]
}
],
"boundaries": [
{
"kind": "region",
"label": "AIO Sandbox",
"wraps": [
"gateway",
"browser",
"shell",
"files",
"code",
"mcp",
"vscode",
"preview",
"services"
],
"pad": 44
},
{
"kind": "region",
"label": "agent tools",
"wraps": [
"browser",
"shell",
"files",
"code",
"mcp"
],
"pad": 18
},
{
"kind": "region",
"label": "human surfaces",
"wraps": [
"vscode",
"preview",
"services"
],
"pad": 18
}
],
"connections": [
{
"id": "agent-gateway",
"from": "agent",
"to": "gateway",
"label": "HTTP · WebSocket",
"variant": "emphasis",
"labelDy": -30
}
]
}

File: website/diagrams/aiod-browser-cdp.architecture.json Copy Chapter

{
"schema_version": 1,
"diagram_type": "architecture",
"meta": {
"title": "Browser CDP",
"quality_profile": "showcase",
"visual_preset": "signal-flow",
"locale": "en"
},
"layout": {
"mode": "grid",
"cols": 3,
"cellW": 176,
"cellH": 72,
"gapX": 144,
"gapY": 56
},
"components": [
{
"id": "agent",
"type": "external",
"label": "Agent",
"sublabel": "Playwright · REST",
"row": 1,
"col": 0,
"size": [176, 72]
},
{
"id": "aiod",
"type": "backend",
"label": "aiod",
"sublabel": "/v1/browser",
"row": 0,
"col": 1,
"size": [176, 72]
},
{
"id": "nginx",
"type": "backend",
"label": "nginx",
"sublabel": "/cdp/*",
"row": 2,
"col": 1,
"size": [176, 72]
},
{
"id": "chromium",
"type": "external",
"label": "Chromium",
"sublabel": "CDP :9222",
"row": 1,
"col": 2,
"size": [176, 72]
}
],
"boundaries": [
{
"kind": "region",
"label": "container · VM",
"wraps": ["aiod", "nginx", "chromium"]
}
],
"connections": [
{
"id": "agent-aiod",
"from": "agent",
"to": "aiod",
"label": "REST",
"variant": "emphasis"
},
{
"id": "aiod-chromium",
"from": "aiod",
"to": "chromium",
"label": "CDP"
},
{
"id": "agent-nginx",
"from": "agent",
"to": "nginx",
"label": "cdp_url",
"variant": "dashed"
},
{
"id": "nginx-chromium",
"from": "nginx",
"to": "chromium",
"label": "WebSocket",
"variant": "dashed"
}
]
}

File: website/diagrams/aiod-browser-use-flow.sequence.json Copy Chapter

{
"schema_version": 1,
"diagram_type": "sequence",
"meta": {
"title": "Drive a page the sandbox serves",
"quality_profile": "showcase",
"visual_preset": "signal-flow",
"column_fit": "spread",
"locale": "en",
"viewBox": [1080, 640]
},
"participants": [
{ "id": "agent", "type": "external", "label": "Agent" },
{ "id": "aiod", "type": "backend", "label": "aiod", "sublabel": "files · browser" },
{ "id": "chromium", "type": "frontend", "label": "Chromium", "sublabel": "CDP :9222" },
{ "id": "server", "type": "backend", "label": "Server", "sublabel": ":18780" }
],
"messages": [
{ "id": "write-pages", "from": "agent", "to": "aiod", "y": 172, "label": "write index.html · thanks.html", "variant": "emphasis" },
{ "id": "store-pages", "from": "aiod", "to": "server", "y": 204, "label": "index.html · thanks.html", "variant": "default" },
{ "id": "run-server", "from": "agent", "to": "aiod", "y": 236, "label": "run server", "variant": "emphasis" },
{ "id": "http-server", "from": "aiod", "to": "server", "y": 268, "label": "http.server 18780", "variant": "default" },
{ "id": "navigate", "from": "agent", "to": "aiod", "y": 300, "label": "navigate", "variant": "emphasis" },
{ "id": "cdp-load", "from": "aiod", "to": "chromium", "y": 332, "label": "CDP · load", "variant": "default" },
{ "id": "get-index", "from": "chromium", "to": "server", "y": 364, "label": "GET /index.html", "variant": "default" },
{ "id": "snapshot", "from": "agent", "to": "aiod", "y": 396, "label": "snapshot", "variant": "emphasis" },
{ "id": "fill", "from": "agent", "to": "aiod", "y": 428, "label": "fill e6", "variant": "emphasis" },
{ "id": "click", "from": "agent", "to": "aiod", "y": 460, "label": "click e14", "variant": "emphasis" },
{ "id": "evaluate", "from": "agent", "to": "aiod", "y": 492, "label": "evaluate #result", "variant": "emphasis" },
{ "id": "result", "from": "chromium", "to": "agent", "y": 524, "label": "hello, Ada", "variant": "return" }
],
"activations": [
{ "participant": "aiod", "from": 164, "to": 536, "type": "backend" },
{ "participant": "chromium", "from": 326, "to": 532, "type": "frontend" }
]
}

File: website/diagrams/aiod-code-backends.sequence.json Copy Chapter

{
"schema_version": 1,
"diagram_type": "sequence",
"meta": {
"title": "How a run picks its backend",
"quality_profile": "showcase",
"visual_preset": "signal-flow",
"column_fit": "spread",
"locale": "en",
"viewBox": [1080, 660]
},
"participants": [
{ "id": "agent", "type": "external", "label": "Agent" },
{ "id": "aiod", "type": "backend", "label": "aiod", "sublabel": "code" },
{ "id": "jupyter", "type": "cloud", "label": "Jupyter endpoint", "sublabel": "external" },
{ "id": "kernel", "type": "backend", "label": "ipykernel", "sublabel": "spawned by aiod" },
{ "id": "native", "type": "backend", "label": "Native REPL", "sublabel": "python3 · node" }
],
"segments": [
{ "from": 206, "to": 306, "label": "AIO_JUPYTER_ENDPOINT reachable" },
{ "from": 322, "to": 422, "label": "ipykernel importable" },
{ "from": 438, "to": 538, "label": "otherwise · every javascript request" }
],
"messages": [
{ "id": "execute", "from": "agent", "to": "aiod", "y": 176, "label": "execute code", "variant": "emphasis" },
{ "id": "proxy", "from": "aiod", "to": "jupyter", "y": 232, "label": "execute · proxied", "variant": "default" },
{ "id": "proxy-result", "from": "jupyter", "to": "aiod", "y": 276, "label": "result", "variant": "return" },
{ "id": "zmq", "from": "aiod", "to": "kernel", "y": 348, "label": "execute_request · ZMQ", "variant": "default" },
{ "id": "zmq-result", "from": "kernel", "to": "aiod", "y": 392, "label": "result", "variant": "return" },
{ "id": "harness", "from": "aiod", "to": "native", "y": 464, "label": "{code, timeout_ms}", "variant": "default" },
{ "id": "harness-result", "from": "native", "to": "aiod", "y": 508, "label": "result", "variant": "return" },
{ "id": "response", "from": "aiod", "to": "agent", "y": 568, "label": "status · outputs · stdout", "variant": "return" }
],
"activations": [
{ "participant": "aiod", "from": 168, "to": 580, "type": "backend" },
{ "participant": "jupyter", "from": 226, "to": 282, "type": "cloud" },
{ "participant": "kernel", "from": 342, "to": 398, "type": "backend" },
{ "participant": "native", "from": 458, "to": 514, "type": "backend" }
]
}

File: website/diagrams/aiod-code-execution-flow.sequence.json Copy Chapter

{
"schema_version": 1,
"diagram_type": "sequence",
"meta": {
"title": "Analyze a dataset in a kernel session",
"quality_profile": "showcase",
"visual_preset": "signal-flow",
"column_fit": "spread",
"locale": "en",
"viewBox": [1080, 640]
},
"participants": [
{ "id": "agent", "type": "external", "label": "Agent" },
{ "id": "aiod", "type": "backend", "label": "aiod", "sublabel": "files · code" },
{ "id": "session", "type": "backend", "label": "Session", "sublabel": "analysis" },
{ "id": "files", "type": "database", "label": "Files", "sublabel": "/tmp/analysis" }
],
"messages": [
{ "id": "write-csv", "from": "agent", "to": "aiod", "y": 172, "label": "write sales.csv", "variant": "emphasis" },
{ "id": "store-csv", "from": "aiod", "to": "files", "y": 204, "label": "sales.csv", "variant": "default" },
{ "id": "execute-load", "from": "agent", "to": "aiod", "y": 236, "label": "execute", "variant": "emphasis" },
{ "id": "read-csv", "from": "aiod", "to": "session", "y": 268, "label": "df = read_csv()", "variant": "default" },
{ "id": "outputs", "from": "session", "to": "agent", "y": 300, "label": "outputs[0].text", "variant": "return" },
{ "id": "execute-plot", "from": "agent", "to": "aiod", "y": 332, "label": "execute · same session", "variant": "emphasis" },
{ "id": "savefig", "from": "aiod", "to": "session", "y": 364, "label": "Agg · savefig()", "variant": "default" },
{ "id": "store-png", "from": "session", "to": "files", "y": 396, "label": "plot.png", "variant": "default" },
{ "id": "list", "from": "agent", "to": "aiod", "y": 428, "label": "list files", "variant": "emphasis" },
{ "id": "listing", "from": "files", "to": "agent", "y": 460, "label": "files[]", "variant": "return" },
{ "id": "download", "from": "agent", "to": "aiod", "y": 492, "label": "download plot.png", "variant": "emphasis" },
{ "id": "bytes", "from": "files", "to": "agent", "y": 524, "label": "plot.png bytes", "variant": "return" }
],
"activations": [
{ "participant": "aiod", "from": 164, "to": 536, "type": "backend" },
{ "participant": "session", "from": 262, "to": 404, "type": "backend" }
]
}

File: website/diagrams/aiod-computer-action.sequence.json Copy Chapter

{
"schema_version": 1,
"diagram_type": "sequence",
"meta": {
"title": "One computer action",
"quality_profile": "showcase",
"visual_preset": "signal-flow",
"column_fit": "spread",
"locale": "en",
"viewBox": [1080, 640]
},
"participants": [
{ "id": "agent", "type": "external", "label": "Agent" },
{ "id": "aiod", "type": "backend", "label": "aiod", "sublabel": "desktop proxy" },
{ "id": "worker", "type": "backend", "label": "computer-use", "sublabel": "worker" },
{ "id": "desktop", "type": "frontend", "label": "Desktop", "sublabel": "X display" }
],
"segments": [
{ "from": 152, "to": 384, "label": "action · screenshot" },
{ "from": 400, "to": 568, "label": "accessibility tree" }
],
"messages": [
{ "id": "action", "from": "agent", "to": "aiod", "y": 172, "label": "action + screenshot", "variant": "emphasis" },
{ "id": "action-proxied", "from": "aiod", "to": "worker", "y": 204, "label": "proxied", "variant": "default" },
{ "id": "inject", "from": "worker", "to": "desktop", "y": 236, "label": "input · xdotool / AT-SPI", "variant": "default" },
{ "id": "capture", "from": "worker", "to": "desktop", "y": 268, "label": "capture frame", "variant": "default" },
{ "id": "frame", "from": "desktop", "to": "worker", "y": 300, "label": "PNG", "variant": "return" },
{ "id": "action-result", "from": "worker", "to": "aiod", "y": 332, "label": "status · screenshot", "variant": "return" },
{ "id": "action-response", "from": "aiod", "to": "agent", "y": 364, "label": "base64 PNG", "variant": "return" },
{ "id": "find", "from": "agent", "to": "aiod", "y": 420, "label": "find nodes · role · name", "variant": "emphasis" },
{ "id": "find-proxied", "from": "aiod", "to": "worker", "y": 452, "label": "proxied", "variant": "default" },
{ "id": "atspi", "from": "worker", "to": "desktop", "y": 484, "label": "AT-SPI query", "variant": "default" },
{ "id": "nodes", "from": "desktop", "to": "worker", "y": 516, "label": "nodes", "variant": "return" },
{ "id": "find-response", "from": "aiod", "to": "agent", "y": 548, "label": "node_id · role · name · bounds", "variant": "return" }
],
"activations": [
{ "participant": "aiod", "from": 164, "to": 556, "type": "backend" },
{ "participant": "worker", "from": 196, "to": 340, "type": "backend" },
{ "participant": "worker", "from": 444, "to": 524, "type": "backend" },
{ "participant": "desktop", "from": 228, "to": 308, "type": "frontend" },
{ "participant": "desktop", "from": 476, "to": 524, "type": "frontend" }
]
}

File: website/diagrams/aiod-existing-environment.architecture.json Copy Chapter

{
"schema_version": 1,
"diagram_type": "architecture",
"meta": {
"title": "Add aiod to an existing environment",
"quality_profile": "showcase",
"visual_preset": "signal-flow",
"locale": "en",
"viewBox": [
926,
420
]
},
"components": [
{
"id": "agent",
"type": "external",
"label": "Agent",
"sublabel": "one interface",
"pos": [
110,
127
],
"size": [
176,
72
]
},
{
"id": "aiod",
"type": "backend",
"label": "aiod",
"sublabel": "commands · files · browser · code",
"pos": [
480,
125
],
"size": [
304,
76
]
},
{
"id": "image",
"type": "external",
"label": "Your image",
"sublabel": "toolchain · private SDK",
"pos": [
480,
237
],
"size": [
142,
68
]
},
{
"id": "apps",
"type": "external",
"label": "Your apps",
"sublabel": "enterprise apps",
"pos": [
642,
237
],
"size": [
142,
68
]
}
],
"boundaries": [
{
"kind": "region",
"label": "Existing environment · container · VM · desktop",
"wraps": [
"aiod",
"image",
"apps"
]
}
],
"connections": [
{
"id": "agent-aiod",
"from": "agent",
"to": "aiod",
"label": "HTTP · MCP · SDK",
"variant": "emphasis"
}
]
}

File: website/diagrams/aiod-human-in-loop.architecture.json Copy Chapter

{
"schema_version": 1,
"diagram_type": "architecture",
"meta": {
"title": "Agent and person",
"quality_profile": "showcase",
"visual_preset": "signal-flow",
"locale": "en"
},
"layout": {
"mode": "grid",
"cols": 3,
"cellW": 176,
"cellH": 72,
"gapX": 144,
"gapY": 56
},
"components": [
{
"id": "agent",
"type": "external",
"label": "Agent",
"sublabel": "tool calls",
"row": 0,
"col": 0,
"size": [
176,
72
]
},
{
"id": "aiod",
"type": "backend",
"label": "aiod",
"sublabel": "tools API",
"row": 1,
"col": 0,
"size": [
176,
72
]
},
{
"id": "terminal",
"type": "backend",
"label": "Terminal",
"sublabel": "PTY session",
"row": 0,
"col": 1,
"size": [
176,
72
]
},
{
"id": "chromium",
"type": "external",
"label": "Chromium",
"sublabel": "CDP :9222",
"row": 1,
"col": 1,
"size": [
176,
72
]
},
{
"id": "desktop",
"type": "backend",
"label": "Desktop",
"sublabel": "X display",
"row": 2,
"col": 1,
"size": [
176,
72
]
},
{
"id": "person",
"type": "external",
"label": "Person",
"sublabel": "browser tab",
"row": 0,
"col": 2,
"size": [
176,
72
]
},
{
"id": "gateway",
"type": "backend",
"label": "Gateway",
"sublabel": "nginx",
"row": 1,
"col": 2,
"size": [
176,
72
]
}
],
"boundaries": [
{
"kind": "region",
"label": "agent tools",
"wraps": [
"agent",
"aiod"
]
},
{
"kind": "region",
"label": "human in the loop",
"wraps": [
"person",
"gateway"
]
}
],
"connections": [
{
"id": "agent-aiod",
"from": "agent",
"to": "aiod",
"label": "HTTP",
"variant": "emphasis",
"labelDy": 24
},
{
"id": "aiod-terminal",
"from": "aiod",
"to": "terminal"
},
{
"id": "aiod-chromium",
"from": "aiod",
"to": "chromium"
},
{
"id": "aiod-desktop",
"from": "aiod",
"to": "desktop"
},
{
"id": "person-gateway",
"from": "person",
"to": "gateway",
"label": "HTTPS",
"labelDy": 24
},
{
"id": "gateway-terminal",
"from": "gateway",
"to": "terminal",
"label": "/terminal",
"variant": "dashed"
},
{
"id": "gateway-chromium",
"from": "gateway",
"to": "chromium",
"label": "/browser-ui",
"variant": "dashed",
"labelDx": -37
},
{
"id": "gateway-desktop",
"from": "gateway",
"to": "desktop",
"label": "/vnc",
"variant": "dashed"
}
]
}

File: website/diagrams/aiod-jupyter-kernel.architecture.json Copy Chapter

{
"schema_version": 1,
"diagram_type": "architecture",
"meta": {
"title": "Jupyter kernels",
"quality_profile": "showcase",
"visual_preset": "signal-flow",
"locale": "en"
},
"layout": {
"mode": "grid",
"cols": 3,
"cellW": 176,
"cellH": 72,
"gapX": 144,
"gapY": 56
},
"components": [
{
"id": "agent",
"type": "external",
"label": "Agent",
"sublabel": "Jupyter plane",
"row": 1,
"col": 0,
"size": [
176,
72
]
},
{
"id": "aiod",
"type": "backend",
"label": "aiod",
"sublabel": "kernel client",
"row": 1,
"col": 1,
"size": [
176,
72
]
},
{
"id": "s1",
"type": "frontend",
"label": "ipykernel",
"sublabel": "session s1",
"row": 0,
"col": 2,
"size": [
176,
72
]
},
{
"id": "s2",
"type": "frontend",
"label": "ipykernel",
"sublabel": "session s2",
"row": 1,
"col": 2,
"size": [
176,
72
]
},
{
"id": "warm",
"type": "external",
"label": "ipykernel",
"sublabel": "warm · one-off",
"row": 2,
"col": 2,
"size": [
176,
72
]
}
],
"boundaries": [
{
"kind": "region",
"label": "spawned by aiod",
"wraps": [
"s1",
"s2",
"warm"
]
}
],
"connections": [
{
"id": "agent-aiod",
"from": "agent",
"to": "aiod",
"label": "HTTP",
"variant": "emphasis"
},
{
"id": "aiod-s1",
"from": "aiod",
"to": "s1",
"label": "ZMQ"
},
{
"id": "aiod-s2",
"from": "aiod",
"to": "s2"
},
{
"id": "aiod-warm",
"from": "aiod",
"to": "warm",
"variant": "dashed"
}
]
}

File: website/diagrams/aiod-mcp-flow.architecture.json Copy Chapter

{
"schema_version": 1,
"diagram_type": "architecture",
"meta": {
"title": "MCP endpoint",
"quality_profile": "showcase",
"visual_preset": "signal-flow",
"locale": "en"
},
"layout": {
"mode": "grid",
"cols": 3,
"cellW": 176,
"cellH": 72,
"gapX": 144,
"gapY": 56
},
"components": [
{
"id": "agent",
"type": "external",
"label": "Agent",
"sublabel": "MCP client",
"row": 0,
"col": 0,
"size": [176, 72]
},
{
"id": "aiod",
"type": "backend",
"label": "aiod",
"sublabel": "/mcp · JSON-RPC",
"row": 0,
"col": 1,
"size": [176, 72]
},
{
"id": "builtin",
"type": "backend",
"label": "Built-in tools",
"sublabel": "files · command · code",
"row": 0,
"col": 2,
"size": [176, 72]
},
{
"id": "upstream",
"type": "external",
"label": "mcp-server-browser",
"sublabel": "EXTRA_MCP_SERVERS",
"row": 1,
"col": 2,
"size": [176, 72]
}
],
"boundaries": [
{
"kind": "region",
"label": "one tool list",
"wraps": ["builtin", "upstream"]
}
],
"connections": [
{
"id": "agent-aiod",
"from": "agent",
"to": "aiod",
"label": "tools/call",
"variant": "emphasis"
},
{
"id": "aiod-builtin",
"from": "aiod",
"to": "builtin"
},
{
"id": "aiod-upstream",
"from": "aiod",
"to": "upstream",
"label": "forward",
"variant": "dashed"
}
]
}

File: website/diagrams/aiod-overview.architecture.json Copy Chapter

{
"schema_version": 1,
"diagram_type": "architecture",
"meta": {
"title": "aiod",
"quality_profile": "showcase",
"locale": "en"
},
"layout": {
"mode": "grid",
"cols": 3,
"cellW": 180,
"cellH": 72,
"gapX": 72,
"gapY": 40
},
"components": [
{
"id": "agent",
"type": "external",
"label": "Agent",
"sublabel": "SDK · curl · MCP",
"row": 1,
"col": 0
},
{
"id": "aiod",
"type": "backend",
"label": "aiod",
"sublabel": "tools API · /mcp",
"tag": ":18091",
"row": 1,
"col": 1
},
{
"id": "interp",
"type": "backend",
"label": "Interpreters",
"sublabel": "bash · python · node",
"row": 0,
"col": 2
},
{
"id": "chromium",
"type": "external",
"label": "Chromium",
"sublabel": "CDP :9222",
"row": 1,
"col": 2
},
{
"id": "cu",
"type": "backend",
"label": "computer-use",
"sublabel": "desktop · :18100",
"row": 2,
"col": 2
}
],
"boundaries": [
{
"kind": "region",
"label": "Same host or container",
"wraps": [
"interp",
"chromium",
"cu"
]
}
],
"connections": [
{
"id": "agent-aiod",
"from": "agent",
"to": "aiod",
"label": "HTTP · WebSocket",
"variant": "emphasis"
},
{
"id": "aiod-interp",
"from": "aiod",
"to": "interp",
"label": "spawn"
},
{
"id": "aiod-chromium",
"from": "aiod",
"to": "chromium",
"label": "CDP",
"labelDy": 13
},
{
"id": "aiod-cu",
"from": "aiod",
"to": "cu",
"label": "proxy"
}
]
}

File: website/diagrams/aiod-permission-model.architecture.json Copy Chapter

{
"schema_version": 1,
"diagram_type": "architecture",
"meta": {
"title": "Permission model",
"quality_profile": "showcase",
"visual_preset": "signal-flow",
"locale": "en"
},
"layout": {
"mode": "grid",
"cols": 3,
"cellW": 176,
"cellH": 72,
"gapX": 144,
"gapY": 76
},
"components": [
{
"id": "agent",
"type": "external",
"label": "Agent",
"sublabel": "SDK · MCP · curl",
"row": 0,
"col": 0,
"size": [
176,
72
]
},
{
"id": "gate",
"type": "security",
"label": "API key",
"sublabel": "AIO_API_KEY",
"row": 0,
"col": 1,
"size": [
176,
72
]
},
{
"id": "aiod",
"type": "backend",
"label": "aiod",
"sublabel": "AIO_DEFAULT_USER",
"row": 1,
"col": 1,
"size": [
176,
72
]
},
{
"id": "exec",
"type": "backend",
"label": "Commands · PTY · Code",
"sublabel": "runs as user",
"row": 0,
"col": 2,
"size": [
176,
72
]
},
{
"id": "files",
"type": "database",
"label": "Files",
"sublabel": "owned by user",
"row": 1,
"col": 2,
"size": [
176,
72
]
}
],
"boundaries": [
{
"kind": "region",
"label": "container · VM",
"wraps": [
"gate",
"aiod",
"exec",
"files"
],
"pad": 40
},
{
"kind": "security-group",
"label": "per-request user",
"wraps": [
"exec",
"files"
]
}
],
"connections": [
{
"id": "agent-gate",
"from": "agent",
"to": "gate",
"label": "x-api-key",
"variant": "emphasis"
},
{
"id": "gate-aiod",
"from": "gate",
"to": "aiod"
},
{
"id": "aiod-exec",
"from": "aiod",
"to": "exec",
"label": "execution identity"
},
{
"id": "aiod-files",
"from": "aiod",
"to": "files",
"label": "ownership identity",
"labelDy": 14
}
]
}

File: website/diagrams/aiod-terminal-flow.sequence.json Copy Chapter

{
"schema_version": 1,
"diagram_type": "sequence",
"meta": {
"title": "Attach to a terminal",
"quality_profile": "showcase",
"visual_preset": "signal-flow",
"column_fit": "spread",
"locale": "en",
"viewBox": [1080, 500]
},
"participants": [
{ "id": "agent", "type": "external", "label": "Agent" },
{ "id": "aiod", "type": "backend", "label": "aiod", "sublabel": "terminal" },
{ "id": "shell", "type": "backend", "label": "Shell" }
],
"messages": [
{ "id": "create", "from": "agent", "to": "aiod", "y": 172, "label": "create session demo-1", "variant": "emphasis" },
{ "id": "attach", "from": "agent", "to": "aiod", "y": 212, "label": "attach", "variant": "emphasis" },
{ "id": "ready", "from": "aiod", "to": "agent", "y": 252, "label": "ready", "variant": "return" },
{ "id": "input", "from": "agent", "to": "aiod", "y": 292, "label": "input · uname -s", "variant": "default" },
{ "id": "run", "from": "aiod", "to": "shell", "y": 332, "label": "uname -s", "variant": "default" },
{ "id": "output", "from": "shell", "to": "agent", "y": 372, "label": "output · Darwin", "variant": "return" }
],
"activations": [
{ "participant": "aiod", "from": 164, "to": 384, "type": "backend" },
{ "participant": "shell", "from": 324, "to": 380, "type": "backend" }
]
}

File: website/diagrams/aiod-terminal-reconnect.sequence.json Copy Chapter

{
"schema_version": 1,
"diagram_type": "sequence",
"meta": {
"title": "Reattach with and without durable",
"quality_profile": "showcase",
"visual_preset": "signal-flow",
"column_fit": "spread",
"locale": "en",
"viewBox": [1080, 624]
},
"participants": [
{ "id": "agent", "type": "external", "label": "Agent" },
{ "id": "aiod", "type": "backend", "label": "aiod", "sublabel": "terminal" },
{ "id": "shell", "type": "backend", "label": "Shell" }
],
"segments": [
{ "from": 160, "to": 232, "label": "socket drops" },
{ "from": 250, "to": 394, "label": "A · durable=true" },
{ "from": 412, "to": 524, "label": "B · plain attach" }
],
"messages": [
{ "id": "keeps-running", "from": "shell", "to": "aiod", "y": 196, "label": "output continues", "variant": "default" },
{ "id": "attach-durable", "from": "agent", "to": "aiod", "y": 284, "label": "attach durable", "variant": "emphasis" },
{ "id": "ready-resumed", "from": "aiod", "to": "agent", "y": 324, "label": "ready · resumed true", "variant": "return" },
{ "id": "gap-output", "from": "aiod", "to": "agent", "y": 364, "label": "output · the gap", "variant": "return" },
{ "id": "attach-plain", "from": "agent", "to": "aiod", "y": 452, "label": "attach", "variant": "emphasis" },
{ "id": "ready-fresh", "from": "aiod", "to": "agent", "y": 492, "label": "ready · resumed false", "variant": "return" }
],
"activations": [
{ "participant": "aiod", "from": 164, "to": 504, "type": "backend" },
{ "participant": "shell", "from": 164, "to": 504, "type": "backend" }
]
}

File: website/diagrams/aiod-watch-flow.sequence.json Copy Chapter

{
"schema_version": 1,
"diagram_type": "sequence",
"meta": {
"title": "Watch a directory",
"quality_profile": "showcase",
"visual_preset": "signal-flow",
"column_fit": "spread",
"locale": "en",
"viewBox": [1080, 600]
},
"participants": [
{ "id": "agent", "type": "external", "label": "Agent" },
{ "id": "aiod", "type": "backend", "label": "aiod", "sublabel": "files · watch" },
{ "id": "files", "type": "database", "label": "Files", "sublabel": "/tmp/demo" },
{ "id": "command", "type": "backend", "label": "Command" }
],
"messages": [
{ "id": "start-watch", "from": "agent", "to": "aiod", "y": 172, "label": "watch /tmp/demo", "variant": "emphasis" },
{ "id": "subtree", "from": "aiod", "to": "files", "y": 204, "label": "watch subtree", "variant": "default" },
{ "id": "run", "from": "agent", "to": "aiod", "y": 236, "label": "run command", "variant": "emphasis" },
{ "id": "spawn", "from": "aiod", "to": "command", "y": 268, "label": "spawn", "variant": "default" },
{ "id": "write", "from": "command", "to": "files", "y": 300, "label": "writes src/util.py", "variant": "default" },
{ "id": "notify", "from": "files", "to": "aiod", "y": 332, "label": "create · write src/util.py", "variant": "dashed" },
{ "id": "poll-0", "from": "agent", "to": "aiod", "y": 364, "label": "poll cursor=0", "variant": "emphasis" },
{ "id": "events-1-2", "from": "aiod", "to": "agent", "y": 396, "label": "events 1–2 · cursor 2", "variant": "return" },
{ "id": "poll-2", "from": "agent", "to": "aiod", "y": 428, "label": "poll cursor=2 · timeout=30", "variant": "emphasis" },
{ "id": "events-after", "from": "aiod", "to": "agent", "y": 460, "label": "events after 2", "variant": "return" },
{ "id": "stop-watch", "from": "agent", "to": "aiod", "y": 492, "label": "stop watch", "variant": "emphasis" }
],
"activations": [
{ "participant": "aiod", "from": 164, "to": 504, "type": "backend" },
{ "participant": "command", "from": 262, "to": 308, "type": "backend" }
]
}

File: website/docs/README.md Copy Chapter

AIO Sandbox Documentation

This documentation provides comprehensive guides and API references for the AIO Sandbox environment.

📚 Documentation Structure Copy Chapter

docs/
├── index.md          # Homepage with overview
├── guide/            # User guides and tutorials
│   ├── quick-start.md
│   └── ...
├── api/              # API reference documentation
│   ├── index.md      # API overview
│   ├── swagger.md    # Interactive API docs guide
│   ├── file.md       # File operations API
│   ├── shell.md      # Shell & terminal API
│   ├── browser.md    # Browser automation API
│   └── mcp.md        # MCP services API
└── examples/         # Practical examples
    ├── agent.md
    ├── browser.md
    └── terminal.md

🚀 Viewing Documentation Copy Chapter

Local Development Copy Section

If you're running the documentation locally:

# Install dependencies
npm install

# Start dev server
npm run docs:dev

# Build for production
npm run docs:build

Live API Documentation Copy Section

When AIO Sandbox is running, access the interactive Swagger UI at:

• Swagger UI: http://localhost:8080/v1/docs
• OpenAPI Spec: http://localhost:8080/openapi.json

📖 Key Sections Copy Chapter

For Users Copy Section

• Quick Start - Get up and running in minutes
• Features Guide - Explore all capabilities
• Examples - Real-world use cases

For Developers Copy Section

• API Reference - Complete API documentation with interactive Swagger UI

🛠️ API Integration Copy Chapter

Generate Client SDKs Copy Section

Use the OpenAPI specification to generate client libraries:

# Install OpenAPI Generator
npm install -g @openapitools/openapi-generator-cli

# Generate Python client
openapi-generator-cli generate \
  -i http://localhost:8080/openapi.json \
  -g python \
  -o ./python-client

# Generate TypeScript client
openapi-generator-cli generate \
  -i http://localhost:8080/openapi.json \
  -g typescript-axios \
  -o ./typescript-client

Import to API Tools Copy Section

• Postman: Import → URL → http://localhost:8080/openapi.json
• Insomnia: Import → From URL → http://localhost:8080/openapi.json
• Bruno: Import → OpenAPI → http://localhost:8080/openapi.json

📝 Documentation Updates Copy Chapter

The documentation is automatically generated from:

1. OpenAPI Specification (/openapi.json) - API endpoints and schemas
2. Markdown Files - Guides, examples, and additional content
3. Code Comments - Inline documentation in source code

To update documentation:

1. Modify the relevant markdown files in /docs
2. Update OpenAPI spec for API changes
3. Run build to generate updated docs

🤝 Contributing Copy Chapter

Contributions to documentation are welcome! Please:

1. Follow the existing structure and style
2. Write from a user perspective
3. Include practical examples
4. Test all code samples
5. Update the OpenAPI spec for API changes

📚 Resources Copy Chapter

• GitHub Repository: https://github.com/agent-infra/sandbox
• Issue Tracker: https://github.com/agent-infra/sandbox/issues
• Docker Hub: https://hub.docker.com/r/agent-infra/sandbox

📄 License Copy Chapter

This documentation is part of the AIO Sandbox project and follows the same license terms.

File: website/docs/en/404.md Copy Chapter

pageType: custom layout: false Copy Chapter

██╗  ██╗ ██████╗ ██╗  ██╗
 ██║  ██║██╔═══██╗██║  ██║
 ███████║██║   ██║███████║
 ╚════██║██║   ██║╚════██║
      ██║╚██████╔╝     ██║
      ╚═╝ ╚═════╝      ╚═╝
  


<h1 style="font-size: 2.8rem; margin: 1.5rem 0 0.5rem; color: #2c3e50; font-weight: 700;">
  Oops! Page Not Found
</h1>


  The page you're looking for seems to have escaped from the sandbox! 
  Let's get you back on track with these helpful links.




  <a href="/sandbox/" 
     style="display: flex; align-items: center; justify-content: center; background: linear-gradient(135deg, #3498db, #2980b9); color: white; padding: 1rem 1.5rem; text-decoration: none; border-radius: 10px; font-weight: 600; transition: transform 0.2s; box-shadow: 0 4px 15px rgba(52, 152, 219, 0.3);"
     onmouseover="this.style.transform='translateY(-2px)'" 
     onmouseout="this.style.transform='translateY(0)'">
    🏠
    Go Home
  </a>
  
  <a href="/sandbox/guide/" 
     style="display: flex; align-items: center; justify-content: center; background: linear-gradient(135deg, #2ecc71, #27ae60); color: white; padding: 1rem 1.5rem; text-decoration: none; border-radius: 10px; font-weight: 600; transition: transform 0.2s; box-shadow: 0 4px 15px rgba(46, 204, 113, 0.3);"
     onmouseover="this.style.transform='translateY(-2px)'" 
     onmouseout="this.style.transform='translateY(0)'">
    📖
    Documentation
  </a>
  
  <a href="/sandbox/api/" 
     style="display: flex; align-items: center; justify-content: center; background: linear-gradient(135deg, #e67e22, #d35400); color: white; padding: 1rem 1.5rem; text-decoration: none; border-radius: 10px; font-weight: 600; transition: transform 0.2s; box-shadow: 0 4px 15px rgba(230, 126, 34, 0.3);"
     onmouseover="this.style.transform='translateY(-2px)'" 
     onmouseout="this.style.transform='translateY(0)'">
    🔧
    API Reference
  </a>




  <h3 style="margin-top: 0; margin-bottom: 1.5rem; color: #2c3e50; font-size: 1.3rem; font-weight: 600;">
    🔍 Popular Pages
  </h3>
  
    
      <h4 style="color: #3498db; margin: 0 0 0.5rem; font-size: 1rem;">Getting Started</h4>
      
        <li style="margin: 0.3rem 0;">
          <a href="/sandbox/guide/quick-start" style="color: #555; text-decoration: none; font-size: 0.9rem; display: flex; align-items: center;">
            ⚡Quick Start Guide
          </a>
        </li>
        <li style="margin: 0.3rem 0;">
          <a href="/sandbox/guide/features" style="color: #555; text-decoration: none; font-size: 0.9rem; display: flex; align-items: center;">
            ✨Features Overview
          </a>
        </li>
      
    
    
      <h4 style="color: #e67e22; margin: 0 0 0.5rem; font-size: 1rem;">API Documentation</h4>
      
        <li style="margin: 0.3rem 0;">
          <a href="/sandbox/api/shell" style="color: #555; text-decoration: none; font-size: 0.9rem; display: flex; align-items: center;">
            🐚Shell WebSocket API
          </a>
        </li>
        <li style="margin: 0.3rem 0;">
          <a href="/sandbox/api/file" style="color: #555; text-decoration: none; font-size: 0.9rem; display: flex; align-items: center;">
            📁File Operations API
          </a>
        </li>
      
    
  




  
    
  
  
    Try searching for "terminal", "file operations", "browser", or "API"
  




  <h4 style="color: #666; margin-bottom: 1rem; font-size: 1rem;">AIO Sandbox Architecture</h4>

┌─────────────────────────────────────────────────────────────┐
│ 🌐 Browser + VNC │
├─────────────────────────────────────────────────────────────┤
│ 💻 VSCode Server │ 🐚 Shell Terminal │ 📁 File Ops │
├─────────────────────────────────────────────────────────────┤
│ 🔗 MCP Hub + 🔒 Sandbox Fusion │
├─────────────────────────────────────────────────────────────┤
│ 🚀 Preview Proxy + 📊 Service Monitoring │
└─────────────────────────────────────────────────────────────┘

Still can't find what you're looking for? 
    [Visit our GitHub](https://github.com/agent-infra/sandbox) 
    or check the 
    [examples section](/sandbox/examples/).

File: website/docs/en/_nav.json Copy Chapter

[
{
"text": "Guide",
"link": "/guide/start/introduction",
"activeMatch": "/guide/"
},
{
"text": "Daemon",
"link": "/daemon/start/introduction",
"activeMatch": "/daemon/"
},
{
"text": "API",
"link": "/api",
"activeMatch": "/api/"
},
{
"text": "Blog",
"link": "/blog/index",
"activeMatch": "/blog/"
},
{
"text": "Version",
"items": [
{
"text": "Changelog",
"link": "https://github.com/agent-infra/sandbox/releases"
}
]
}
]

File: website/docs/en/index.md Copy Chapter

pageType: home

hero:
name: AIO Sandbox
text: |
All-in-One Environment
for AI Agents
tagline: |
🌐 Browser | 💻 Terminal | 📁 File

🔧 VSCode | 📊 Jupyter |  MCP

actions:
- theme: brand
text: Get Started
link: /guide/start/introduction
- theme: alt
text: GitHub
link: https://github.com/agent-infra/sandbox
image:
src: /aio-icon.png
alt: AIO Sandbox Logo

features:

• title: Unified Environment
  details: One Docker container with shared filesystem. Files downloaded in the browser are instantly accessible in Terminal and VSCode.
  icon: 🌐
• title: Out of the Box
  details: Built‑in VNC browser, VS Code, Jupyter, file manager, and terminal—accessible directly via API/SDK.
  icon: ⚡
• title: Secure Execution
  details: Isolated Python and Node.js sandboxes. Safe code execution without system risks.
  icon: 🔐
• title: Agent-Ready
  details: Pre-configured MCP Server with Browser, File, Terminal, Markdown, Ready-to-use for AI agents.
  icon: 🤖
• title: Developer Friendly
  details: Cloud-based VSCode with persistent terminals, intelligent port forwarding(via ${Port}-${domain}/ or /proxy), and instant frontend/backend previews.
  icon: 🔧
• title: Production Ready
  details: Enterprise-grade Docker deployment. Lightweight, scalable.
  icon: 🚀

File: website/docs/en/blog/_meta.json Copy Chapter

["index.mdx", "announcing-0"]

File: website/docs/en/blog/announcing-0.mdx Copy Chapter

date: 2025-10-29 14:00:00 sidebar: false Copy Chapter

October 29, 2025

AIO Sandbox: An Integrated and Customizable Sandbox Environment for AI Agents

Background Copy Chapter

As LLMs continue to evolve, AI application forms have undergone three generational shifts:

• Chatbot: Conversational interaction, answering questions
• Copilot: Collaborative assistance, improving efficiency
• Agent: Autonomous execution, completing tasks

Agents can autonomously perceive their environment, plan steps, and invoke tools, enabling them to operate computers like humans: automatically browsing web pages to collect information, generating and running code to analyze data, executing system commands to manage files, and even completing complex multi-step operations through visual interfaces. This capability allows Agent deliverables to approach or even exceed human professional standards.

Pain Points Copy Section

1. 🧩 Environment Fragmentation: Multiple single-function sandboxes (like E2B for code execution, Browserbase for browsers) force Agents to transfer data across sandboxes via NAS/OSS, increasing latency and complexity. For example: a deep research Agent completing 'convert a paper into a PPT' needs to exchange dozens of intermediate files (JSON configs, chart images, preview screenshots, etc.) across multiple sandboxes, adding complexity and overhead to the entire Agent system.

2. 🎁 Difficult Customization: Different types of Agents require different pre-installed tech stacks. Traditional sandboxes provide unified pre-installed environments that cannot meet all Agents' personalized needs.

3. 🔒 Security Isolation Challenges: Need to give Agents real system capabilities (network, files, browser, GPU) while maintaining strong isolation to prevent unauthorized access and data leaks.

4. 🖥️ Difficult Visual Interaction: Complex Agent tasks require human takeover, functional sandboxes need to integrate VNC, Terminal, VSCode to maintain consistent experience. Resolution switching, screenshots, and GUI visual operations.

5. 🌐 Browser Environment Complexity: Anti-automation and fingerprint risk control, CDP instability, inadequate proxy support with username/password, missing GUI operations.

A well-configured computer can significantly improve human work efficiency; similarly, a powerful sandbox environment can also improve Agent task quality and execution speed.

Introduction Copy Chapter

One-sentence introduction: AIO Sandbox integrates browser, code execution, terminal, visual takeover, forward and reverse proxy, MCP, authentication and other basic functions in a single sandbox, allowing environment customization based on needs, enabling different Agents to "complete tasks more efficiently in a unified environment container".

• Website: sandbox.agent-infra.com

• Github: github.com/agent-infra/sandbox

• API: sandbox.agent-infra.com/api

• Paper: arxiv.org/pdf/2509.02544#S2.SS2

Features Copy Section

• 📦 Out-of-the-box: Connect directly to sandbox capabilities via /mcp protocol, also providing API / SDK for customizing sandbox toolsets.
• 🚀 Second-level Startup: Full sandbox service startup completes in seconds, reaching millisecond-level after pre-caching/cold start.
• 🌈 Customizable: Agents in various vertical scenarios need domain-specific tools and dependencies; AIO provides a unified image base, supporting on-demand expansion with convention-based routing and service configuration.
• 🌐 Browser: Integrates Web Infra's RS lightweight kernel, providing CDP, screenshots, pure visual GUI operations, and Proxy configuration.
• 🔄 Human Takeover: Provides browser VNC, Code Server, Terminal, supporting human takeover and debugging mid-task.
• 📡 Proxy and Forwarding: Supports forward proxy with authentication; maps {port}-{domain} wildcard domains or /proxy|/absproxy/{port} paths to services inside the sandbox (convenient for preview/demo).
• 🔒Security Authentication: JWT Bearer access control; provides Short-Lived Tickets for links that cannot carry Headers.

Examples Copy Chapter

More at: https://seed-tars.com/showcase/ui-tars-2

Quick Start Copy Chapter

Cloud Copy Section

One-Click Deploy All-in-One Sandbox Application--Function Service-Volcano Engine

Local Copy Section

Prerequisites: Install Docker, then start locally with one command:

docker run --rm -it -p 127.0.0.1:8080:8080 ghcr.io/agent-infra/sandbox:latest

# For faster access in China
# docker run --security-opt seccomp=unconfined --rm -it -p 127.0.0.1:8080:8080 enterprise-public-cn-beijing.cr.volces.com/vefaas-public/all-in-one-sandbox:latest

**System Architecture** Copy Chapter

Overview Copy Section

AIO Sandbox provides Agents with basic capabilities like Browser, File, Shell, Code, and offers extensibility to support developers in combining and customizing dedicated sandboxes based on Agent needs (such as AIO Sandbox for Mobile/Medical/Legal/Finance/Scientific Research).
Sandbox customization levels increase progressively:

1. Standard (Out-of-the-box): Plug-and-play for Agents via /mcp endpoint, suitable for quick PoC Agent validation.
2. Custom Toolset (Tool/Skills Extension): Without modifying the image, add or orchestrate tools based on SDK/API (such as adding web_search); also extend Skills to implement automated handling of specific sandbox tasks.
3. Custom Image: Based on FROM aio.sandbox base image, install specific dependencies (such as multimedia/image processing, etc.), mount custom services (e.g., /custom_tools/ocr image recognition).

Core Components Copy Section

Browser

Browser environment for Agents, core is providing CDP and VNC, mainstream Browser Use frameworks can be used directly;
AIO provides x11-based browser GUI visual operation interface, which can be combined with CDP for more efficient, lower risk-control Browser Use solutions.

CDP

CDP (Chrome Devtools Protocol) is a protocol for communicating with Chrome or Chromium browsers, providing browser control APIs via WebSocket for navigation and loading, DOM manipulation, JS execution/debugging, network interception and simulation, screenshots and rendering, security and permissions, etc.
For a more intuitive understanding, here's an example of using CDP to initiate a page navigation command:

'/Applications/Google Chrome.app/Contents/MacOS/Google Chrome' \
    --disable-gpu \
    --user-data-dir=./test \
    --remote-debugging-port=9222 \
    https://www.chromestatus.com

Visit http://localhost:9222/json/version, where webSocketDebuggerUrl is the CDP address:

$ curl http://localhost:9222/json/version
{
   "Browser": "Chrome/141.0.7390.66",
   "Protocol-Version": "1.3",
   "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/141.0.0.0 Safari/537.36",
   "V8-Version": "14.1.146.11",
   "WebKit-Version": "537.36 (@95681a3c3d516c397b75ff45b8980c1088666775)",
   "webSocketDebuggerUrl": "ws://localhost:9222/devtools/browser/a6c5f19f-5d24-4bed-ba08-9c15cf5aeedb"
}

After establishing a WebSocket connection with CDP, you can execute browser commands:

Note: AIO Sandbox doesn't directly expose the CDP interface /json/version, but relays CDP through the uvicorn service and adds heartbeat detection to avoid ws disconnection issues.

GUI Visual Operations

Screenshots
Unlike CDP-based screenshots, visual screenshots /v1/browser/screenshot include Tabs (the entire browser window), and operations target the entire browser window.

Unlike CDP browser operations, visual operations /v1/browser/actions simulate human behavior for clicking, typing, scrolling, etc., which can reduce target website risk control strategies.

Unified Action Space
Abstract GUI operations into composable minimal atomic actions, such as moving mouse, clicking, dragging, scrolling, key press, text input, and additional utility functions like wait, aligning as closely as possible with VLM visual models executing actual actions.

Takeover

When Browser Use encounters login requirements, human takeover is generally needed, requiring an interactive browser interface. Currently there are two approaches:

1. VNC Takeover: AIO Sandbox provides /vnc/index.html page for direct user interaction.

2. Frontend connects via CDP, real-time redrawing complete browser interface on Canvas (Playground); we've packaged the frontend part into a component @agent-infra/browser-ui. Below, left is the actual browser, right is browser-ui screen mirroring:

The differences between the two takeover methods are roughly as follows:

Command Line Interpreter

For Coding Agents, most tasks can be completed through command line execution. When designing the Shell module, using OpenHands' CmdRunAction as the execution engine, combined with tmux, implements multi-session execution capability.

File Operations

File/code editing only requires two tools:

• File CRUD: Encapsulates basic I/O for file read/write/list directory/create/upload/download, with path validation and permission control, covering common file operation scenarios.

• Text Editor: Implements model-oriented fine-grained editing tool str_replace_editor, supporting:

  • view (view file or directory, including line range)
  • str_replace (exact string replacement)
  • insert (insert by line, legacy version support)
  • undo_edit (undo)

Code Execution

Balancing language coverage and image size, using Python 3.10/3.11/3.12 and Node.js 22 runtimes from Sandbox Fusion, providing an integrated secure isolation environment for code execution.

MCP Servers Aggregator Copy Section

Aggregates multiple MCP Servers (e.g., chrome-devtools-mcp) through unified entry point /mcp, supporting parameter-level filtering, and allowing tool name prefixing (namespacing).

Filter MCP Servers by search, future expansion will include tags (tags) and category (category) multi-dimensional filtering to reduce redundant calls and lower model token costs.

Proxy Copy Section

In Agent sandboxes, there are generally two types of scenarios corresponding to forward and reverse proxies:

1. Forward Proxy: Browser Use Agent can access private/global networks

2. Reverse Proxy: Coding Agent services developed inside the sandbox are exposed externally for user-side preview

Forward Proxy

Using TinyProxy proxy server to bypass geographic restrictions, access restricted content, or provide secure access within corporate intranets.

Why introduce TinyProxy when Chrome has --proxy-server to specify proxy?
The Chromium official documentation states that it will not use any username/password embedded in proxy settings (e.g., http://user:pass@host:port), authentication must go through a separate challenge dialog, affecting the entire Browser Use experience (as shown below):

Reverse Proxy

Provides two methods to access service ports inside the Sandbox:

1. subdomain wildcard forwarding (recommended): Any domain matching ${port}-${domain} format will be forwarded to ports inside the sandbox.

2. subpath forwarding: Encounters many issues: for routing-sensitive services (like frontend projects), the additional /proxy|absproxy/${port} path causes resource matching 404s.

Authentication Copy Section

Agent operations in the sandbox generate user data. To implement unified AIO Sandbox authentication without intrusion, without modifying any existing business routing configuration, and without increasing the mental burden of future routing configuration expansion, an "asymmetric encryption + JWT" reverse proxy architecture was designed at the internal Nginx gateway layer:

How to Enable (One-time Configuration)

• Generate key pair

openssl genrsa -out private_key.pem 2048
openssl rsa -in private_key.pem -pubout -out public_key.pem
echo "Key pair generation complete!"

• Start service (with public key to enable authentication), using environment variable JWT_PUBLIC_KEY

export JWT_PUBLIC_KEY=$(cat public_key.pem | base64)
JWT_PUBLIC_KEY="${JWT_PUBLIC_KEY}"

Issue JWT

Business service uses private key to generate a JWT valid for 1 hour. Below is a simplified script to generate JWT, in practice business backend should use mature JWT libraries:

# This is a simplified script to generate JWT, in practice business backend should use mature JWT libraries
base64url_encode() { openssl base64 -e -A | tr '+/' '-_' | tr -d '='; }
header='{"alg":"RS256","typ":"JWT"}'
exp_time=$(($(date +%s) + 3600))
payload="{\"exp\":${exp_time}}"
to_be_signed="$(echo -n "$header" | base64url_encode).$(echo -n "$payload" | base64url_encode)"
signature=$(echo -n "$to_be_signed" | openssl dgst -sha256 -sign private_key.pem | base64url_encode)
jwt="${to_be_signed}.${signature}"
echo "JWT generated: ${jwt}"

Usage

1. Header Authentication

   shell Copy

   curl --silent -X GET "http://localhost:8080/v1/sandbox" \
        -H "Authorization: Bearer ${jwt}"

2. Short-Lived Ticket Authentication Example (using VNC page access): Direct access cannot authenticate via Header method, can only use ?ticket= ticket as query parameter.

   • Use JWT to obtain ticket from common endpoint (default validity is 30s, can be configured via TICKET_TTL_SECONDS environment variable)
   bash Copy

   echo "Using JWT to exchange for common one-time ticket..."
   
   ticket_response=$(curl --silent -X POST "http://localhost:8080/tickets" \
        -H "Authorization: Bearer ${jwt}")
   
   ticket=$(echo "$ticket_response" | jq -r .ticket)
   expires=$(echo "$ticket_response" | jq -r .expires_in)
   
   echo "Successfully obtained! Ticket: ${ticket}, Validity: ${expires} seconds"

   • Client builds and uses VNC URL: Now you can use the obtained ${ticket} variable to build the VNC URL and initiate access.
   bash Copy

   # Bash script simulates client URL concatenation
   vnc_url="http://localhost:8080/vnc/index.html?ticket=${ticket}&path=websockify%3Fticket%3D${ticket}"
   
   echo "Client-built final URL: ${vnc_url}"
   
   # Simulate access (should be done in browser)
   # curl -I "${vnc_url}"

Extension and Ecosystem Copy Chapter

Custom Images Copy Section

In AIO, service processes (supervisord) and service routing (Nginx) are automatically mounted following convention-based directories:

• Service process directory: /opt/gem/supervisord/*.conf
• Routing directory: /opt/gem/nginx/*.conf

To customize services and routing on top of the AIO image, refer to the following image code:

FROM enterprise-public-cn-beijing.cr.volces.com/vefaas-public/all-in-one-sandbox:latest

# ----------------------
# Install additional system dependencies (if any)
# installed path: /usr/bin/*
# ----------------------
RUN set -eux; \
    apt-get update; \
    apt-get install -y --no-install-recommends \
        ${your_system_dep} \
        --no-install-recommends; \
    # clean up
    apt-get clean && \
    rm -rf /var/lib/apt/lists/*;

# ----------------------
# npm install (if any)
#
# ----------------------
RUN npm i -g ${your_npm_package}

# ----------------------
# python pip install (if any)
# installed path: /usr/local/bin/*
# ----------------------
RUN pip install ${your_python_package}

# Add custom Server service
COPY ./supervisord.agent_server.conf /opt/tiger/run/supervisord/agent_server.conf
# Bind Nginx routing
COPY ./nginx.agent_server.conf /opt/gem/nginx/nginx.agent_server.conf

# # If you don't need services in AIO, you can delete them, e.g., Code Server
# ## Delete Code Server process and routing
# RUN rm -rf /opt/gem/supervisord/supervisord.code_server.conf
# ## Delete Code Server routing
# RUN rm -rf /opt/gem/nginx/code_server.conf

SDK Integration Copy Section

Using fern to convert AIO Sandbox API documentation directly into Python / Go / Node.js SDKs. Using Python as an example, a few lines of code connect AIO Sandbox's core functionality:

from agent_sandbox import Sandbox

client = Sandbox(base_url="http://localhost:8080")

# Execute Shell
shell_res = client.shell.exec_command(command="ls -la")
print(shell_res.data.output) # /home/gem

# Browser Screenshot
screenshot = client.browser.screenshot()
print(screenshot)

# Get Browser CDP
browser_info = client.browser.get_browser_info()
cdp_url = browser_info.data.cdp_url # ws://

# Read File
file_res = client.file.read_file(file="/home/gem/.bashrc")
print(file_res.data.content)

More usage examples: agent-infra/sandbox#examples

browser-use

Just add 4 lines of code to integrate the community's browser-use:

Complete code: browser-use#main.py

LangGraph-DeepAgents

Complete code: langgraph-deepagents#main.py

Custom Toolsets Copy Section

You can use API / SDK to compose high-level toolsets needed by Agents, for example link_reader returns page content for a URL:

from openai import OpenAI
from agent_sandbox import Sandbox
import json

client = OpenAI(
    api_key="your_api_key",
)
sandbox = Sandbox(base_url="http://localhost:8080")

tools = [{
    "type": "function",
    "function": {
        "name": "link_reader",
        "description": "Render and read webpage, return title, body text, and final URL (based on CDP).",
        "parameters": {
            "type": "object",
            "properties": {
                "url": {"type": "string", "format": "uri"},
                "timeout_ms": {"type": "integer", "default": 30000}
            },
            "required": ["url"]
        }
    }
}]

async def link_reader(url: str, timeout_ms: int = 30_000) -> dict:
    cdp_url = sandbox.browser.get_browser_info().cdp_url
    async with async_playwright() as p:
        browser = await p.chromium.connect_over_cdp(cdp_url)
        try:
            page = await browser.new_page()
            await page.goto(url, wait_until="networkidle", timeout=timeout_ms)
            title = await page.title()
            text = await page.evaluate("document.body.innerText || ''")
            return {"final_url": page.url, "title": title, "text": text[:8000]}
        finally:
            await browser.close()

Deployment Copy Section

Currently the best public cloud deployment form is function computing, based on Sandbox's designated instance access capability: One-Click Deploy All-in-One Sandbox Application--Function Service-Volcano Engine

Summary and Outlook Copy Chapter

AIO Sandbox provides an integrated, customizable base environment (Agent Env), enabling Agents to complete diverse tasks including browsing, executing code, running commands, and file operations within the same environment, while supporting customization of domain-specific sandboxes for different Agents. This sandbox system will continue to evolve and expand alongside the rising intelligence ceiling of Agents and the creativity of developers.

Going forward, we will continue to refine stability, observability, and ecosystem integration, continuously improve evaluation systems and best practices, driving robust deployment and efficient operation of AIO Sandbox in more large-scale, high-demand Agent application scenarios.

Appendix Copy Chapter

Terminology Copy Section

References Copy Section

• UI-TARS-2 Technical Report: Advancing GUI Agent with Multi-Turn Reinforcement Learning
• AIO Sandbox: All-in-One Sandbox for AI Agents & Developers
• Agentic AI Infrastructure Practice Series (2): Necessity and Practice of Dedicated Sandbox Environment
• Writing effective tools for AI agents—using AI agents
• Unifying the Computer Use Action Space

File: website/docs/en/blog/index.mdx Copy Chapter

title: Overview sidebar: false Copy Chapter

AIO Sandbox Blog

Check here for the latest articles and release announcements about AIO Sandbox.

[AIO Sandbox: An Integrated and Customizable Sandbox Environment for AI Agents](/blog/announcing-0) Copy Chapter

October 29, 2025

AIO Sandbox integrates all capabilities through a Docker image, providing a unified file system and authentication, and supports image customization, thereby enhancing the efficiency of Agent task execution and delivery.

File: website/docs/en/daemon/_meta.json Copy Chapter

[
{
"type": "dir",
"label": "Getting Started",
"name": "start"
},
"architecture",
{
"type": "dir",
"label": "Capabilities",
"name": "basic"
},
{
"type": "dir",
"label": "Deploy",
"name": "ops"
},
{
"type": "dir",
"label": "Examples",
"name": "examples"
},
{
"type": "file",
"name": "api",
"label": "API Reference"
}
]

File: website/docs/en/daemon/architecture.md Copy Chapter

Architecture

aiod is AIO Sandbox's core daemon process. It serves the sandbox tools API and hosts the MCP endpoint.

The shell, interpreters, browser, and desktop it drives are separate processes. aiod discovers them at runtime but does not start them.

The daemon process Copy Chapter

It serves commands, files, terminals (PTY), code execution, and browser control over HTTP and WebSocket, and hosts POST /mcp.

The browser is the Chromium process listening for CDP at BROWSER_REMOTE_DEBUGGING_HOST:PORT (default 127.0.0.1:9222); any process may start it.

The desktop is provided by the computer-use worker at AIO_COMPUTER_USE_URL (default http://127.0.0.1:18100). aiod only forwards /v2/computer/* to it and never touches a display itself. The worker is separate because it needs a desktop session.

On Windows the difference is explicit: aiod can run as a Session 0 service, but computer-use must run in the interactive logon session (see Windows).

Dependencies and capabilities Copy Chapter

aiod always starts. At boot and on each capability check, it probes the dependencies and reports the result in capabilities: