local_fire_departmentHoneystax
search⌘K
loginLog Inperson_addSign Up
layers
HONEYSTAX TERMINAL v1.0
HomeNewsSavedSubmit
Back to the live board
S

sandbox

MCP Server

All-in-One Sandbox for AI Agents that combines Browser, Shell, File, MCP and VSCode Server in a single Docker container.

Copy the install, test the workflow, then decide if it earns a permanent slot.

3,138
Why nowMoving now

Fresh repo activity plus visible builder pull. This is the kind of tool people test before it turns obvious.

DecisionHigh-conviction move

Copy the install, test the workflow, then decide if it earns a permanent slot.

Trial costMedium lift

Testable in one sitting, but you will likely touch real infra or local setup before you know if it sticks.

Risk38/100

GitHub health 50/100. no security policy. 83 open issues make this testable, but not something to trust blind.

What You Are Adopting

AI Agent

Universal

Model

Multiple

Build Time

Minutes

Test This In Your Stack

One command inClean rollbackLow commitment
settingsRegistryAdds a named entry to Claude config. One command to remove.

Fastest way to find out if sandbox belongs in your setup.

Copy the install command, run a real test, and back it out cleanly if it slows you down.

Try now
claude mcp add sandbox -- npx sandbox

Run this first. You will know quickly if the workflow earns a permanent slot.

Back out
claude mcp remove sandbox

No messy cleanup loop. If it misses, remove it and keep moving.

Install Location

~/  └─ .claude.json    └─ mcp_servers/      └─ sandbox ← registers here

About

All-in-One Sandbox for AI Agents that combines Browser, Shell, File, MCP and VSCode Server in a single Docker container.. An open-source mcp server for the AI coding ecosystem.

README

AIO Sandbox - All-in-One Agent Sandbox Environment

logo

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

🌐 Website   |   🔌 API   |   📑 Paper   |   🌟 Examples   |   📊 Evaluation   

Release License PyPI npm

🚀 Quick Start

Get up and running in 30 seconds:

docker run --security-opt seccomp=unconfined --rm -it -p 8080:8080 ghcr.io/agent-infra/sandbox:latest

For 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:latest

Use 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.150

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.

AIO Sandbox Architecture

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 = 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();

🌟 Key Features

🔗 Unified Environment

All components run in the same container with a shared filesystem, enabling seamless workflows:

Unified Environment

🌐 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

Browser Automation

💻 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

VSCode Server

🤖 MCP Integration

Pre-configured Model Context Protocol servers:

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

MCP Integration

📚 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_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![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

🏗️ 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
  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"

🤝 Integration Examples

Browser Use Integration

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())

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_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

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

Tech Stack

GoTypeScriptJavaScriptPythonOpenAILangChainGPTLLMDockerKubernetesVite
Open Live ProjectAudit Repo

Reviews0

Log in to write a review.

ActiveLast commit 19d ago
bug_report83open issues
Submitted August 6, 2025

auto_awesomeYour strongest next moves after sandbox