🌐 Browser | 💻 Terminal | 📁 File | 🔧 VSCode | 📊 Jupyter | 🤖 MCP
🌐 Website | 🔌 API | 📑 Paper | 🌟 Examples | 📊 Evaluation
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:latestFor 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.0For 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.0These 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
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.
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
|
Python pip install agent-sandbox |
TypeScript/JavaScript npm install @agent-infra/sandbox |
Golang go get github.com/agent-infra/sandbox-sdk-go |
|
Python Example 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 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(); |
All components run in the same container with a shared filesystem, enabling seamless workflows:
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
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
Pre-configured Model Context Protocol servers:
- Browser - Web automation and scraping
- File - File system operations
- Shell - Command execution
- Markitdown - Document processing
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_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"
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!")
┌─────────────────────────────────────────────────────────────┐
│ 🌐 Browser + VNC │
├─────────────────────────────────────────────────────────────┤
│ 💻 VSCode Server │ 🐚 Shell Terminal │ 📁 File Ops │
├─────────────────────────────────────────────────────────────┤
│ 🔗 MCP Hub + 🔒 Sandbox Fusion │
├─────────────────────────────────────────────────────────────┤
│ 🚀 Preview Proxy + 📊 Service Monitoring │
└─────────────────────────────────────────────────────────────┘
| 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 |
| 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 |
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: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"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())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