# Sandbox

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

- **Type:** MCP server
- **Install:** `agentstack add mcp-agent-infra-sandbox`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [agent-infra](https://agentstack.voostack.com/s/agent-infra)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [agent-infra](https://github.com/agent-infra)
- **Source:** https://github.com/agent-infra/sandbox
- **Website:** https://sandbox.agent-infra.com

## Install

```sh
agentstack add mcp-agent-infra-sandbox
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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

  
  
  
  

## 🚀 Quick Start

Get up and running in 30 seconds:

```bash
# 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:latest
```

For users in mainland China:

```bash
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:latest
```

Use a specific version in the format `agent-infra/sandbox:${version}`, for example, to use version 1.11.0:

```bash
docker run --security-opt seccomp=unconfined --rm -it \
  -p 127.0.0.1:8080:8080 ghcr.io/agent-infra/sandbox:1.11.0
# or users in mainland China
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.0
```

These 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](https://sandbox.agent-infra.com/guide/start/cloud-deployment).

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"
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:
      - "127.0.0.1:${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'])
```

### MiniMax Integration

MiniMax provides an OpenAI-compatible API, so you can use the same `openai` SDK with a different `base_url`:

```python
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](examples/minimax-integration) for more details.

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

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [agent-infra](https://github.com/agent-infra)
- **Source:** [agent-infra/sandbox](https://github.com/agent-infra/sandbox)
- **License:** Apache-2.0
- **Homepage:** https://sandbox.agent-infra.com

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** yes
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-agent-infra-sandbox
- Seller: https://agentstack.voostack.com/s/agent-infra
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.