One Open Source Project a Day (No. 226): AIO Sandbox — Browser, Shell, File, MCP, and VSCode Server in One Docker Container

Introduction

"What an agent needs isn't five tools each doing their own thing — it's one environment where every tool can see the same file."

This is the 226th article in the "One Open Source Project a Day" series. Today's project is AIO Sandbox.

Setting up an execution environment for AI agents runs into a small but persistent annoyance: browser automation lives in one container, code execution in another sandbox, file storage in a third service. Passing files and state between them means hand-writing glue code — a file downloaded in the browser can't be read by a shell script without an extra hop; results generated in Jupyter need to be manually relocated before a browser tool can use them. Every new tool you add means another round of custom integration work.

AIO Sandbox (full project name agent-infra/sandbox) is built to solve exactly this "tool island" problem. It packs browser automation, a shell terminal, file operations, MCP servers, and VSCode Server into a single Docker container. Its core selling point is a unified filesystem shared across all tools — a file downloaded in the browser is immediately usable via shell commands or file APIs, with zero relocation step in between.

6.0k Stars, Apache-2.0 License, with working integrations verified against Browser Use, LangChain, OpenAI Assistants, and MiniMax.

What You Will Learn

• AIO Sandbox's layered architecture: browser/VNC layer, dev tools layer, MCP integration layer, infrastructure layer
• How the "unified filesystem" eliminates data-relocation costs between tools
• The four built-in MCP servers: browser, file, shell, and markitdown
• How to deploy it three ways: Docker, Docker Compose, and Kubernetes
• How it actually integrates with frameworks like Browser Use, LangChain, and OpenAI Assistants

Prerequisites

• Familiarity with basic Docker operations (run, compose)
• Basic understanding of MCP (Model Context Protocol)
• Optional: basic understanding of Chrome DevTools Protocol (CDP) and browser automation

Project Background

What It Is

AIO Sandbox's official positioning: "an all-in-one agent sandbox environment that unifies Browser, Shell, File, MCP operations, and VSCode Server in a single Docker container," built on cloud-native lightweight sandbox technology. The project documentation directly names the pain point of traditional sandboxes: "traditional sandboxes are typically single-purpose (browser, code, or shell), making file sharing and functional coordination extremely challenging" — AIO Sandbox is the unified answer to that exact pain point.

Team and Background

• Organization: agent-infra
• License: Apache License 2.0
• Deployment: Docker container (Kubernetes also supported)
• Official SDKs: Python (agent-sandbox), TypeScript/JavaScript (@agent-infra/sandbox), Go (agent-sandbox-sdk-go)

Project Stats

• ⭐ GitHub Stars: 6,000+
• 🍴 Forks: 534
• 👀 Watchers: 32
• 📄 License: Apache-2.0
• 📊 Commits: 130 (main branch)

What It Does

The Problem It Solves

Building an agent environment without AIO Sandbox:
  Browser automation → container A (Playwright/Puppeteer)
  Code execution     → container B (Jupyter/Sandbox Fusion)
  File storage       → a separate file service C
  ↑ the three don't talk to each other — files downloaded by the browser
    need manual relocation before container B can use them
  ↑ every new tool integrated means rewriting cross-container data-passing
    logic from scratch
 
AIO Sandbox's approach:
  Browser + Shell + File + MCP + VSCode all packed into one container
  ↓ a unified filesystem as the shared underlying layer
  Browser downloads a file → shell reads it directly → Jupyter processes
  it directly → file API writes it back directly
  ↑ every tool sees the same filesystem, no relocation needed

Use Cases

1. AI agent tool execution and browser automation

   • An agent needs to open web pages, click through interactions, scrape content, and also execute code to process what it scraped

2. Web-page-to-Markdown processing pipelines

   • The official example: use Playwright over CDP to scrape a page → convert HTML via Jupyter's markdownify → read the result back through the file API, all inside the same container

3. Agent development that needs visual debugging

   • Watch browser automation execute live through a VNC remote desktop, or debug sandbox code directly via VSCode Server

4. A unified execution backend for multiple framework integrations

   • Serve as the shared execution backend for Browser Use, LangChain, OpenAI Assistants, and other frameworks, instead of building a separate execution environment for each

Quick Start

One-command Docker launch:

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

Once running, access:

• /v1/docs — API documentation
• /vnc/index.html — VNC remote desktop
• /code-server/ — VSCode Server
• /mcp — MCP service entry point

Users in mainland China can substitute an alternate mirror registry for ghcr.io. For production, use a pinned version tag (e.g., 1.11.0) instead of latest to keep deployments reproducible.

Install the SDK:

# Python
pip install agent-sandbox
 
# TypeScript/JavaScript
npm install @agent-infra/sandbox
 
# Go
go get github.com/agent-infra/sandbox-sdk-go

Core Features

1. Unified Filesystem

Shared across the browser, shell, file operations, and Jupyter — the core design of the entire project, eliminating the glue code needed to pass files between tools.

2. Four Built-in MCP Servers

3. Multiple Access Interfaces

VNC (remote desktop), VSCode Server, Jupyter Notebook, WebSocket terminal — the same sandbox can be accessed in whatever way best fits the current task.

4. Core REST API

Endpoints like /v1/sandbox, /v1/shell/exec, /v1/file/read, /v1/file/write, /v1/browser/screenshot, and /v1/jupyter/execute cover the common execution needs of an agent.

5. Three Deployment Options

6. Authentication Mechanism

Enabled via the SANDBOX_API_KEY environment variable, supporting header, Bearer token, or query-parameter auth uniformly across API, JupyterLab, and VNC access; leaving it unset keeps services open (for backward compatibility).

A Deeper Look

Layered Architecture: From Visualization Down to Infrastructure

AIO Sandbox's architecture can be understood as a four-layer stack:

Browser + VNC layer (visualization)
  ↓
VSCode Server + Shell terminal + File operations layer (dev layer)
  ↓
MCP Hub + Sandbox Fusion layer (integration layer)
  ↓
Preview Proxy + Service monitoring layer (infrastructure layer)

All layers share the same container and the same filesystem. The key insight in this design: it doesn't stitch multiple independent services together over a network interface — it runs them all within the same process environment and filesystem namespace. This eliminates the serialization overhead and consistency problems that come with cross-container/cross-service communication — there's no need to solve the classic distributed-systems question of "when will the shell container see the file the browser container just wrote."

The Real Pain Point the Unified Filesystem Solves

Look at the typical workflow the official docs describe, and the design choice becomes concrete:

1. Use Playwright over CDP, connected to the sandbox's browser, to scrape a page
2. The page content → written directly to the sandbox filesystem
3. Call Jupyter's markdownify inside the sandbox to convert HTML to Markdown
4. The converted result → read back directly through the file API

In a traditional multi-container setup, steps 2 and 3 require a cross-container file transfer — maybe a volume mount, an object-storage relay, or an API call carrying the file content as payload. In AIO Sandbox, this step is just an ordinary file write and read within the same filesystem — no extra transport layer, no extra failure point.

Why MCP as the Unified Access Protocol Matters

AIO Sandbox chose to wrap its browser, file, shell, and markitdown tools in the MCP protocol rather than defining its own bespoke REST API spec for each. The benefit: any agent framework that already supports an MCP client (Claude Code, or any other MCP-compatible tool) can plug into the sandbox's full capability set with "zero configuration" — no adapter layer needs to be written specifically for AIO Sandbox. Compared to the traditional pattern where "every sandbox defines its own private API, and integrating a new tool means writing a new adapter layer," this eliminates a large amount of repeated integration work.

How Framework Integrations Actually Work

The README shows several typical framework integrations, and the pattern reveals the sandbox's design intent: to be called as an execution backend, not to become its own agent orchestration framework:

This "content to be an execution layer, not competing for the orchestration seat" positioning means it can be grafted broadly onto existing agent ecosystems without requiring users to give up an orchestration framework they're already using.

How It Compares to Traditional Single-Purpose Sandboxes

Project Links and Resources

Official Resources

• 🌟 GitHub: https://github.com/agent-infra/sandbox
• 📄 License: Apache License 2.0
• 🐛 Issues: GitHub Issues
• 💬 Community: GitHub Discussions

Related Resources

• Model Context Protocol — The standard protocol AIO Sandbox uses to wrap its tool capabilities
• Chrome DevTools Protocol — The underlying protocol behind the sandbox's browser automation capability
• Browser Use — A browser automation framework with a verified integration into AIO Sandbox

Summary

Key Takeaways

1. A unified filesystem is the core design: eliminates the file-relocation cost between the browser, shell, and code execution, with all tools sharing the same filesystem
2. Same-container architecture instead of cross-container orchestration: browser, shell, file, MCP, and VSCode all run inside the same process environment, avoiding distributed consistency problems
3. MCP as the unified access protocol: all four built-in tools (browser/file/shell/markitdown) are exposed via MCP, compatible with the existing MCP client ecosystem
4. Content to be an execution backend: its integrations with Browser Use, LangChain, OpenAI Assistants, and MiniMax are all about "being called," not "replacing" — it doesn't compete with existing orchestration frameworks
5. Three deployment tiers cover different scenarios: a complete deployment path from a single local command to a Kubernetes production cluster

Who This Is For

• AI agent developers: who need one unified execution environment instead of building separate infrastructure for browser automation, code execution, and file storage
• Teams using multiple frameworks: already using LangChain, Browser Use, and similar tools, and want a shared execution backend instead of reinventing it
• Scenarios needing visual debugging: watch an agent's execution live via VNC/VSCode Server instead of only reading logs
• Users of the MCP ecosystem: who want an out-of-the-box set of MCP servers covering browser/file/shell without maintaining their own

One-Line Verdict

AIO Sandbox isn't trying to build a smarter agent framework — it's solving a more foundational problem first: making sure the tools an agent uses can at least see the same filesystem.

Check out PrimeSkills — a curated marketplace of AI agents and skills that have been validated in real-world, enterprise-grade workflows. No fluff, just what actually works.

Find more useful knowledge and interesting products on my Homepage