AIO Sandbox Documentation

AIO Sandbox is an integrated environment for AI Agents that combines multiple capabilities into a single container to prevent environment fragmentation. Key features include:

• Integrated Capabilities: Browser (CDP, screenshots, GUI), code execution, terminal, and MCP protocol support.
• Fast Startup: Second-level startup with millisecond-level performance after pre-caching.
• Customization: Supports on-demand expansion of tools and dependencies via a unified image base.
• Human Takeover: Provides VNC for browsers, Code Server, and Terminal for manual debugging and interaction.
• Proxy & Forwarding: Supports forward proxy with authentication and wildcard domain mapping ({port}-{domain}) or path-based proxying (/proxy|/absproxy/{port}).
• Security: JWT Bearer access control and Short-Lived Tickets for link-based access.

AIO Sandbox is an all-in-one environment that combines Browser, Shell, File, MCP operations, and VSCode Server within a single Docker container. It provides a unified file system where files downloaded in the browser are immediately accessible via Shell and File operations.

Multi-Interface Access

• VNC: Visual browser interaction at /vnc/index.html
• Code Server: Full VSCode experience at /code-server/
• Terminal: WebSocket terminal at /v1/shell/ws
• Bash: Pipe-based command execution at /v1/bash/*
• Code Runtimes: Python and JavaScript execution through /v1/code/*, /v1/jupyter/*, and /v1/nodejs/*
• MCP Hub: Aggregated services at /mcp

AIO Sandbox is an all-in-one environment designed for AI agents, providing a unified workspace that includes a Browser, Terminal, and File system. It operates within a single Docker container with a shared filesystem, ensuring that files downloaded in the browser are immediately accessible in the Terminal and VSCode.

Key features include:

• Built-in Tools: VNC browser, VS Code, Jupyter, file manager, and terminal, all accessible via API/SDK.
• Secure Execution: Isolated sandboxes for Python and Node.js.
• Agent-Ready: Pre-configured MCP (Model Context Protocol) Server with Browser, File, Terminal, and Markdown capabilities.
• Developer Features: Cloud-based VSCode with persistent terminals and intelligent port forwarding (using ${Port}-${domain}/ or /proxy) for instant previews.

AIO Sandbox supports two integration modes depending on where your agent orchestration logic and credentials reside:

Agent Call Sandbox

• Agent Location: Host machine, local service, remote service, or notebook.
• Interaction: Via REST API, Python/TypeScript SDKs, or MCP.
• Best For: SaaS agents, remote development, multi-sandbox orchestration, and connecting existing agent frameworks via MCP.
• Network: Agent must reach the sandbox entry port (e.g., http://localhost:8080).

Agent In Sandbox

• Agent Location: Inside the sandbox container.
• Interaction: Via local commands, localhost REST API, or the aio CLI.
• Best For: Coding agents, CI/CD, and scenarios where the agent and task must share the same filesystem and process environment.
• Network: Agent calls 127.0.0.1:8080 directly.

The AIO Sandbox provides two ways to execute commands. Choose the appropriate mode based on your use case:

For users in mainland China, use the pinned mirror to pull the image.

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

AIO Sandbox APIs expose errors at multiple layers. To build a robust client, follow this recommended order of operations:

1. Check the HTTP status code: Verify the request reached the server successfully.
2. Check the success field: If the response is JSON, inspect the success boolean.
3. Inspect execution domain fields: For execution APIs (Shell, Bash, Jupyter, Node.js), inspect status, exit_code, stdout, and stderr within the data object.
4. Handle streaming/WebSockets: For WebSocket and streaming APIs, handle connection closures and partial output as distinct events.

When using display recording in AIO Sandbox, follow these best practices:

• Retrieval: Store recordings within the workspace or another known directory to ensure they can be retrieved using the file API.
• File Integrity: Always call the stop action before deleting the container to ensure you receive a complete, playable MP4 file.
• Performance: Use short recordings for debugging and acceptance tests to keep file sizes manageable.

AIO Sandbox provides a Jupyter kernel execution endpoint for Python code. This is ideal for data processing, generating charts, and workflows requiring stateful Python execution. Use the /v1/jupyter/execute endpoint with a POST request containing the code string.

curl -X POST "http://localhost:8080/v1/jupyter/execute" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "x = 40 + 2\nprint(x)"
  }'