π Browser | π» Terminal | π File | π§ VSCode | π Jupyter | π€ MCP
π WebsiteΒ Β | Β Β π APIΒ Β | Β Β π PaperΒ Β | Β Β π ExamplesΒ Β | Β Β π Evaluation Β Β
Get up and running in 30 seconds:
docker run --security-opt seccomp=unconfined --rm -it -p 8080:8080 ghcr.io/agent-infra/sandbox:latestFor users in mainland China:
docker run --security-opt seccomp=unconfined --rm -it -p 8080:8080 enterprise-public-cn-beijing.cr.volces.com/vefaas-public/all-in-one-sandbox:latestUse a specific version in the format agent-infra/sandbox:${version}, for example, to use version 1.0.0.150:
docker run --security-opt seccomp=unconfined --rm -it -p 8080:8080 ghcr.io/agent-infra/sandbox:1.0.0.150 # or users in mainland China docker run --security-opt seccomp=unconfined --rm -it -p 8080:8080 enterprise-public-cn-beijing.cr.volces.com/vefaas-public/all-in-one-sandbox:1.0.0.150Once 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 |
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:-}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'])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





