AIO Sandbox: An all-in-one execution environment for AI Agents

12 hours ago 1

logo

🌐 Browser | 💻 Terminal | 📁 File | 🔧 VSCode | 📊 Jupyter | 🤖 MCP

Release License PyPI npm

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:

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.

AIO Sandbox Architecture

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:

Unified Environment

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

Browser Automation

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

VSCode Server

Pre-configured Model Context Protocol servers:

  • Browser - Web automation and scraping
  • File - File system operations
  • Shell - Command execution
  • Markitdown - Document processing

MCP Integration

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!")

Example Output

┌─────────────────────────────────────────────────────────────┐ │ 🌐 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 template: 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

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

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.


Ready to revolutionize your AI development workflow?
⭐ Star us on GitHub📚 Read the Docs🐛 Report Issues

Read Entire Article