https://github.com/agent-infra/sandbox

All-in-One Sandbox for AI Agents that combines Browser, Shell, File, MCP and VSCode Server in a single Docker container.
https://github.com/agent-infra/sandbox

agent all-in-one browser filesystem mcp sandbox shell

Last synced: 4 months ago
JSON representation

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

Host: GitHub
URL: https://github.com/agent-infra/sandbox
Owner: agent-infra
License: apache-2.0
Created: 2025-08-06T14:51:05.000Z (10 months ago)
Default Branch: main
Last Pushed: 2026-02-25T05:11:22.000Z (4 months ago)
Last Synced: 2026-02-25T10:40:19.920Z (4 months ago)
Topics: agent, all-in-one, browser, filesystem, mcp, sandbox, shell
Language: Python
Homepage: https://sandbox.agent-infra.com
Size: 38.6 MB
Stars: 2,619
Watchers: 24
Forks: 233
Open Issues: 47
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE

Awesome Lists containing this project

awesome-claude-code - agent-infra/sandbox - infra/sandbox?style=flat-square&logo=github) | All-in-one Docker sandbox combining browser, shell, file, MCP, and VSCode for agents | (Agent Orchestration)
awesome-harness-engineering - AIO Sandbox - in-one agent sandbox combining browser, shell, filesystem, MCP servers, and VSCode Server in a single Docker container. Native MCP support exposes sandbox capabilities to LLMs via the standard protocol, and files downloaded in the browser are instantly accessible in terminal and VSCode. Optimized startup (4–8s depending on config) with Claude Skills mounting support. The fastest path to a fully-featured agent development environment. ![Stars](https://img.shields.io/github/stars/agent-infra/sandbox?style=flat-square&label=★&color=yellow) (Reference Implementations / Demo Harnesses)
awesome-mcp - agent-infra/sandbox - agent-infra/sandbox is an all-in-one sandbox environment combining Browser, Shell, File, MCP, and VSCode Server in a single Docker container, providing a unified, secure, and agent-ready platform for AI agent development and testing. (MCP Servers / Browser Automation)
awesome-claude-code-security - agent-infra/sandbox - All-in-one Docker sandbox for AI agents: browser, shell, file, MCP, and VS Code server in a container. (📦 Sandboxing and Isolation / Anthropic Engineering & Blog)
awesome-LLM-resources - SandBox - in-One Sandbox for AI Agents that combines Browser, Shell, File, MCP and VSCode Server in a single Docker container. (智能体 Agents)
my-awesome - agent-infra/sandbox - in-one,browser,filesystem,mcp,sandbox,shell pushed_at:2026-05 star:4.9k fork:0.4k All-in-One Sandbox for AI Agents that combines Browser, Shell, File, MCP and VSCode Server in a single Docker container. (Python)
StarryDivineSky - agent-infra/sandbox - infra/sandbox"，是一个专为AI代理开发设计的集成化沙箱环境，通过Docker容器将浏览器、命令行终端、文件系统、消息传递组件（MCP）和VSCode Server等核心功能整合到单一容器中。其核心特色在于通过容器化技术实现开发环境的即开即用，开发者无需单独配置复杂环境即可获得完整的开发工具链。工作原理基于Docker容器技术，将多个独立服务整合为统一的运行环境，用户通过docker run命令即可启动沙箱，容器内部自动初始化浏览器环境（如Chrome）、命令行交互接口（如Bash）、文件存储系统、AI代理间通信协议（MCP）以及基于VSCode的远程开发服务器。该项目特别适用于需要隔离测试环境的AI代理开发场景，可同时支持浏览器自动化、系统命令执行、文件操作、跨代理通信等复杂功能。使用时需注意Docker环境依赖，容器启动后会自动映射端口并创建必要目录，开发者可通过环境变量自定义配置。沙箱采用root权限运行，需确保宿主机Docker服务已正确配置。该方案通过容器化技术解决了传统AI代理开发中环境配置复杂、依赖管理困难等问题，为AI代理的快速开发和测试提供了标准化的运行环境。 (A01_文本生成_文本对话 / 大语言对话模型及数据)
awesome - agent-infra/sandbox - All-in-One Sandbox for AI Agents that combines Browser, Shell, File, MCP and VSCode Server in a single Docker container. (Python)
awesome - agent-infra/sandbox - All-in-One Sandbox for AI Agents that combines Browser, Shell, File, MCP and VSCode Server in a single Docker container. (<a name="Python"></a>Python)
awesome-ai-sandbox - AIO Sandbox - Full-featured Docker sandbox with shell, browser, files, Jupyter, VS Code server, and MCP. (Containers, LXC, and packaged runtimes / Multiplatform)
awesome-ai-agents - agent-infra/sandbox - agent-infra/sandbox is an all-in-one sandbox environment combining browser, shell, file system, MCP services, and VSCode Server in a single Docker container to provide a unified, secure, and versatile platform for AI agents and developers. (Agent Integration & Deployment Tools / AI Agent Development)
awesome-openclaw-skills - agent-infra/sandbox - in-One Sandbox for AI Agents that combines Browser, Shell, File, MCP and VSCode Server in a sing... | 3.5k | (MCP Servers & Protocol)

README

          # AIO Sandbox - All-in-One Agent Sandbox Environment



  





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







        🌐 Website&nbsp&nbsp

        | &nbsp&nbsp🔌 API&nbsp&nbsp

        | &nbsp&nbsp📑 Paper&nbsp&nbsp

        | &nbsp&nbsp🌟 Examples&nbsp&nbsp

        | &nbsp&nbsp📊 Evaluation &nbsp&nbsp







  

  

  

  



![](./website/docs/public/images/aio-index.png)

## 🚀 Quick Start

Get up and running in 30 seconds:

```bash

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

```

For users in mainland China:

```bash

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:

```bash

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.



  



### 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**

```bash

pip install agent-sandbox

```

**TypeScript/JavaScript**

```bash

npm install @agent-infra/sandbox

```

**Golang**

```bash

go get github.com/agent-infra/sandbox-sdk-go

```

### Basic Usage

**Python Example**

```python

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

```typescript

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:



  



### 🌐 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



  



### 💻 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



  



### 🤖 MCP Integration

Pre-configured Model Context Protocol servers:

- **Browser** - Web automation and scraping

- **File** - File system operations

- **Shell** - Command execution

- **Markitdown** - Document processing



  



## 📚 Complete Example

Convert a webpage to Markdown with embedded screenshot:

```python

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

```



  



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

```yaml

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

```yaml

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

```python

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

```python

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

```python

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](CONTRIBUTING.md) for details.

## 📄 License

AIO Sandbox is released under the [Apache License 2.0](LICENSE).

## 🙏 Acknowledgments

Built with ❤️ by the Agent Infra team. Special thanks to all contributors and the open-source community.

## 📞 Support

- 📖 [Documentation](https://sandbox.agent-infra.com)

- 💬 [GitHub Discussions](https://github.com/agent-infra/sandbox/discussions)

- 🐛 [Issue Tracker](https://github.com/agent-infra/sandbox/issues)

---



  Ready to revolutionize your AI development workflow?


  ⭐ Star us on GitHub •

  📚 Read the Docs •

  🐛 Report Issues

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/agent-infra/sandbox

Awesome Lists containing this project

README