๐ 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.outputfrom 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 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.
We welcome contributions! Please see our Contributing Guide for details.
AIO Sandbox is released under the Apache License 2.0.
Built with โค๏ธ by the Agent Infra team. Special thanks to all contributors and the open-source community.
- ๐ Documentation
- ๐ฌ GitHub Discussions
- ๐ Issue Tracker
Ready to revolutionize your AI development workflow?
โญ Star us on GitHub โข
๐ Read the Docs โข
๐ Report Issues






