AIO Sandbox

What is AIO Sandbox about?

AIO Sandbox offers a unified execution environment where browsing, terminal commands, file manipulation, Jupyter notebooks, and VSCode IDE are all available within one Docker container. It eliminates the friction of switching between isolated tools by sharing a common filesystem and pre‑configured MCP APIs.

How to use AIO Sandbox?

1. Quick start with Docker

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

   For users in mainland China, replace the image with the regional registry URL.
2. Access the interfaces
   • 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
3. Interact via SDKs (Python, TypeScript, Go) to call shell, file, browser, or Jupyter endpoints. Example (Python):

   from agent_sandbox import Sandbox
   client = Sandbox(base_url="http://localhost:8080")
   result = client.shell.exec_command(command="ls -la")
   print(result.data.output)
   

4. Deploy with Docker Compose or Kubernetes using the provided sample configurations for production setups.

Key Features of AIO Sandbox

• Unified Filesystem – Files created in the browser are instantly accessible to shell and file APIs.
• Multiple Interfaces – VNC visual browser, CDP programmatic control, VSCode Server, Jupyter Notebook, and WebSocket terminal.
• Secure Sandboxed Execution – Isolated Python and Node.js runtimes with safety guarantees.
• Zero Configuration – All MCP services (browser, file, shell, markdown) are pre‑installed and ready.
• Agent‑Ready APIs – Direct MCP endpoints for seamless integration with AI agents, LangChain, OpenAI tools, etc.
• Port Forwarding & Preview – Smart preview for web apps running inside the sandbox.

Use Cases of AIO Sandbox

• Agent Development – Build and test autonomous agents that need to browse, download files, and run code without leaving the sandbox.
• Web Scraping & Data Extraction – Use the browser automation API to navigate pages, take screenshots, and store results for downstream processing.
• Rapid Prototyping – Write and execute Jupyter notebooks or VSCode projects directly in the sandbox, then share artifacts via the shared filesystem.
• CI/CD for AI Workflows – Containerized environment ensures reproducible execution of scripts, model evaluations, and reporting.
• Educational Labs – Provide students with a safe, pre‑configured environment that includes all necessary development tools.

FAQ from the AIO Sandbox

Q: Do I need to install anything locally besides Docker? A: No. The entire stack runs inside the Docker container; optional SDKs can be installed via pip, npm, or go get for programmatic access.

Q: How is data persisted between container restarts? A: By default the container is stateless. Use Docker volumes (as shown in the compose example) to map host directories into /home/gem for persistence.

Q: Can I run multiple sandboxes simultaneously? A: Yes. Deploy multiple containers on different host ports or use the provided Kubernetes manifest with replicas.

Q: What languages are supported for code execution? A: Python (via Jupyter) and Node.js are pre‑installed; additional runtimes can be added by extending the Docker image.

Q: Is there any authentication for the MCP APIs? A: The container supports JWT‑based auth via the JWT_PUBLIC_KEY environment variable; omit it for open local testing.

AIO Sandbox - All-in-One Agent Sandbox Environment

🚀 Quick Start

Get up and running in 30 seconds:

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

For users in mainland China:

docker run --rm -it -p 8080:8080 enterprise-public-cn-beijing.cr.volces.com/vefaas-public/all-in-one-sandbox:latest

Use a specific version in the format agent-infra/sandbox:${version}, for example, to use version 1.0.0.125:

docker run --rm -it -p 8080:8080 ghcr.io/agent-infra/sandbox:1.0.0.125
# or users in mainland China
docker run --rm -it -p 8080:8080 enterprise-public-cn-beijing.cr.volces.com/vefaas-public/all-in-one-sandbox:1.0.0.125

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?

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?

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

SDK Installation

Python

pip install agent-sandbox

TypeScript/JavaScript

npm install @agent-infra/sandbox

Golang

go get github.com/agent-infra/sandbox-sdk-go

Basic Usage

Python Example

from agent_sandbox import Sandbox

# Initialize client
client = Sandbox(base_url="http://localhost:8080")
home_dir = c.sandbox.get_sandbox_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

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:

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_sandbox_context().home_dir

    # Browser: Automation to download HTML
    async with async_playwright() as p:
        browser_info = c.browser.get_browser_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_jupyter_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

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

🛠️ API Reference

Core APIs

Endpoint	Description
/v1/sandbox	Get sandbox environment information
/v1/shell/exec	Execute shell commands
/v1/file/read	Read file contents
/v1/file/write	Write file contents
/v1/browser/screenshot	Take browser screenshot
/v1/jupyter/execute	Execute Jupyter code

MCP Servers

Server	Tools Available
browser	navigate, screenshot, click, type, scroll
file	read, write, list, search, replace
shell	exec, create_session, kill
markitdown	convert, extract_text, extract_images

🚢 Deployment

Docker Compose

version: '3.8'
services:
  sandbox:
    container_name: aio-sandbox
    image: ghcr.io/agent-infra/sandbox:latest
    volumes:
      - /tmp/gem/vite-project:/home/gem/vite-project
    security_opt:
      - seccomp:unconfined
    extra_hosts:
      - "host.docker.internal:host-gateway"
    restart: "unless-stopped"
    shm_size: "2gb"
    ports:
      - "${HOST_PORT:-8080}:8080"
    environment:
      PROXY_SERVER: ${PROXY_SERVER:-host.docker.internal:7890}
      JWT_PUBLIC_KEY: ${JWT_PUBLIC_KEY:-}
      DNS_OVER_HTTPS_TEMPLATES: ${DNS_OVER_HTTPS_TEMPLATES:-}
      WORKSPACE: ${WORKSPACE:-"/home/gem"}
      HOMEPAGE: ${HOMEPAGE:-}
      BROWSER_EXTRA_ARGS: ${BROWSER_EXTRA_ARGS:-}
      TZ: ${TZ:-Asia/Singapore}
      WAIT_PORTS: ${WAIT_PORTS:-}

Kubernetes

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

🤝 Integration Examples

LangChain Integration

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

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_jupyter_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'])

🤝 Contributing

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

📄 License

AIO Sandbox is released under the Apache License 2.0.

🙏 Acknowledgments

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

📞 Support

• 📖 Documentation
• 💬 GitHub Discussions
• 🐛 Issue Tracker

---