Skip to content
/
Tier B A9 Sandbox substrate

agent-infra sandbox

agent-infra-sandbox · agent-infra/sandbox · ★ 4.8k · last commit 2026-05-22

Primitive shape 1 total
MCP tools 1
00

Summary

agent-infra Sandbox (AIO Sandbox) — Summary

AIO Sandbox is an All-in-One Docker container sandbox for AI agents that combines Browser (VNC-accessible Chromium), Terminal (shell commands), File operations, Jupyter notebooks, VSCode Server, and MCP services in a single Docker container. Access is via a unified REST API + MCP protocol at port 8080, with VNC browser view, VSCode Server, Jupyter, and API docs all reachable at the same host. The SDK ships in Python (pip install agent-sandbox), TypeScript (npm install @agent-infra/sandbox), and Golang. Published with an arXiv paper (https://arxiv.org/pdf/2509.02544). Docker startup is docker run --security-opt seccomp=unconfined -p 8080:8080.

AIO Sandbox is a secondary sandbox framework, most comparable to e2b-desktop (both provide browser + file + shell) but running on Docker (not MicroVM), self-hosted (not cloud API), and extending to VSCode Server + Jupyter + MCP integration in one container. Among Phase B Batch 18/33 canonical sandboxes, it fills the "all-in-one self-hosted" niche that E2B (cloud MicroVM) and Daytona (persistent dev environment) do not.

01

Overview

agent-infra Sandbox — Overview

Origin

AIO Sandbox is from the agent-infra organization. An arXiv paper (2509.02544) documents its design and evaluation. The project appears to be from a Chinese research/engineering team (alternative Docker registry for mainland China provided).

Philosophy

From the README:

"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."

The key opinion: single-purpose sandboxes create coordination friction; a unified shared filesystem across all surfaces eliminates it.

Unique Feature: Unified File System

Files downloaded in the browser are immediately available for shell commands, file operations, and code execution — no copying between sandboxes. This is the primary differentiator vs. running separate browser/shell/code sandboxes.

arXiv Paper

Section 2.2 of arXiv paper 2509.02544 describes the AIO Sandbox architecture and evaluation methodology.

02

Architecture

agent-infra Sandbox — Architecture

Distribution

  • Docker: docker run --security-opt seccomp=unconfined -p 8080:8080 ghcr.io/agent-infra/sandbox:latest
  • Python SDK: pip install agent-sandbox
  • TypeScript SDK: npm install @agent-infra/sandbox
  • Golang SDK: go get github.com/agent-infra/sandbox-sdk-go

Directory Structure

sdk/            # SDK packages (Python, TypeScript, Go)
cli/            # CLI tooling
docker/         # Docker container definitions
examples/       # Usage examples
evaluation/     # Benchmark evaluation code
website/        # Documentation website

Container Services (all at port 8080)

URL Service
http://localhost:8080/v1/docs OpenAPI documentation
http://localhost:8080/vnc/index.html?autoconnect=true VNC Browser view
http://localhost:8080/code-server/ VSCode Server
http://localhost:8080/mcp MCP services endpoint
Jupyter Also accessible (port details not specified)

Required Runtime

  • Docker (with --security-opt seccomp=unconfined)
  • No local dependencies for users — everything in the container

Install Complexity

One-liner Docker run. Multi-step for SDK-based usage.

Container Architecture

Docker container (single port 8080)
  ├── Chromium browser (VNC accessible)
  ├── Shell (bash terminal)
  ├── File system (shared across all surfaces)
  ├── VSCode Server
  ├── Jupyter
  ├── MCP server
  └── REST API proxy (unified access layer)

Versions

Available as specific versions: ghcr.io/agent-infra/sandbox:1.0.0.150

03

Components

agent-infra Sandbox — Components

Python SDK (agent_sandbox)

Sandbox Client

  • Sandbox(base_url="http://localhost:8080") — Initialize
  • client.sandbox.get_context() — Get sandbox context (home_dir, etc.)

Shell API

  • client.shell.exec_command(command=...) — Execute shell command
  • Returns result.data.output

File API

  • client.file.read_file(file=...) — Read file
  • Returns result.data.content

Browser API

  • client.browser.screenshot() — Capture screenshot
  • Additional browser automation (full API in docs)

Jupyter API

  • Notebook execution (details in docs)

TypeScript SDK (@agent-infra/sandbox)

Sandbox Client

  • new Sandbox({ baseURL: 'http://localhost:8080' }) — Initialize

Shell API

  • sandbox.shell.exec({ command: '...' }) — Execute shell command

File API

  • sandbox.file.read({ path: '/path' }) — Read file

MCP Services

  • MCP endpoint at http://localhost:8080/mcp
  • Pre-configured MCP servers included in container
  • Zero-config for MCP-compatible agents

Golang SDK

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

Docker Image

  • ghcr.io/agent-infra/sandbox:latest (international)
  • enterprise-public-cn-beijing.cr.volces.com/vefaas-public/all-in-one-sandbox:latest (China mirror)
05

Prompts

agent-infra Sandbox — Prompts

Verbatim Excerpt 1: Python SDK Usage (from README)

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

Technique: Client/server SDK pattern. No pre-authored agent behavior prompts. The sandbox is infrastructure; all agent cognition is user-defined.

Verbatim Excerpt 2: TypeScript SDK (from README)

import { Sandbox } from '@agent-infra/sandbox';

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' });

Technique: Async TypeScript mirror of Python API. Infrastructure client pattern.

Observations

AIO Sandbox ships zero pre-authored agent behavior prompts. The MCP endpoint enables MCP-compatible agents to use sandbox tools without any custom SDK code — the MCP protocol itself defines the tool interface. All agent cognition and decision logic is user-defined.

09

Uniqueness

agent-infra Sandbox — Uniqueness

Differs From Seeds

AIO Sandbox is most comparable to e2b-desktop in this batch (both provide browser + shell + file in one place) but differs: AIO is self-hosted Docker (not cloud API), and extends to VSCode Server + Jupyter + MCP integration in a single container. Among Phase B canonical sandboxes (E2B, Daytona, microsandbox, cubesandbox, capsule), AIO fills the "all-in-one self-hosted Docker with MCP" niche. The built-in MCP endpoint (/mcp) makes it the most MCP-native sandbox in the corpus — agents can use all surfaces as MCP tools without SDK code. The unified shared filesystem across all surfaces (browser + shell + file) is the core architectural opinion not found in any seed.

Positioning

The zero-configuration, all-in-one Docker sandbox for teams who want browser + terminal + file + IDE + Jupyter + MCP in one container, self-hosted without cloud API dependency.

Observable Failure Modes

  1. No per-agent isolation: All agents sharing one container share the filesystem and processes — security risk for multi-tenant scenarios
  2. seccomp=unconfined required: Reduces syscall filtering; weaker isolation than OpenShell or Tensorlake
  3. Container = state: All work is lost when container stops (no built-in persistence)
  4. Single port 8080: All services behind one port creates routing complexity; no port separation for security
  5. Docker resource overhead: Full container with browser + IDE + Jupyter is heavier than purpose-specific sandboxes

What Makes It Interesting

The built-in MCP server at /mcp with zero configuration — any MCP-compatible agent (Claude Code, Codex, OpenCode, etc.) can immediately use browser, shell, file, and IDE surfaces via protocol, without writing SDK code. The arXiv paper documentation suggests serious research behind the design.

04

Workflow

agent-infra Sandbox — Workflow

Typical Workflow

Phase Artifact Description
Start Container Running sandbox docker run -p 8080:8080 ghcr.io/agent-infra/sandbox:latest
Init SDK Sandbox(base_url=...) Connect SDK to container
Shell Operations Command output client.shell.exec_command(...)
File Operations File contents client.file.read_file(...)
Browser Operations Screenshots, DOM client.browser.screenshot()
MCP Integration Tool calls Agent calls MCP endpoint directly
Stop Container destroyed docker stop

Unified File System Advantage

browser.download("https://example.com/data.csv")
# Immediately available in shell:
shell.exec("python process.py /home/user/downloads/data.csv")
# No file copy needed

MCP Workflow

Agents can connect directly to http://localhost:8080/mcp using any MCP-compatible client — no SDK required for MCP usage.

Approval Gates

None — programmatic API only.

Container Lifecycle

Single container = one sandbox environment. Multiple agents can share the same container via different SDK clients (no per-agent isolation).

VNC Access

Human-in-the-loop via VNC browser at http://localhost:8080/vnc/index.html?autoconnect=true — can observe and interact with the browser in real-time.

06

Memory Context

agent-infra Sandbox — Memory & Context

State Storage

  • Unified container filesystem: All surfaces (browser downloads, shell writes, file ops) share the same filesystem — this IS the persistent state
  • No agent-specific memory or context management built-in

Persistence

Container filesystem persists for the container lifetime. Destroyed when container stops (unless Docker volume mounts are used externally).

Cross-Surface State Sharing

The key feature: files written via any surface (browser, shell, file API) are immediately readable by all other surfaces in the same container. This eliminates inter-surface state transfer overhead.

Cross-Session Handoff

None natively. Users can mount Docker volumes to persist state across container restarts.

Context Compaction

Not handled — delegated to consuming agent.

MCP Session State

Each MCP connection is independent. No persisted session state on the MCP server.

Notes

The unified filesystem is the memory model — shared between all surfaces without copying.

07

Orchestration

agent-infra Sandbox — Orchestration

Multi-Agent Support

No isolation between agents — a single container is shared by all connecting agents. No built-in multi-agent coordination.

Orchestration Pattern

None built-in. The container is a shared execution environment.

Isolation Mechanism

Container (Docker). However, unlike OpenShell or Tensorlake, there is no per-agent isolation — the entire container is one shared environment. --security-opt seccomp=unconfined is required, which reduces syscall filtering.

Subagent Definition Format

Not applicable.

Multi-Model Usage

Not applicable.

Execution Mode

Continuous — the container runs as a persistent daemon until explicitly stopped.

Startup Time

Docker container startup (seconds for first pull + start).

Consensus Mechanism

None.

Crash Recovery

No — container restart loses state unless Docker volumes are used.

Streaming Output

VNC provides real-time screen streaming. API is synchronous (REST, not streaming SSE).

MCP Protocol

The built-in MCP server at /mcp enables tool calls over MCP protocol — enabling any MCP client to use sandbox surfaces without writing custom SDK code.

08

Ui Cli Surface

agent-infra Sandbox — UI / CLI Surface

CLI

A cli/ directory exists in the repo — details not fully documented in README. The primary interface is the Docker container + SDK/MCP API.

Local Web UI

Yes — multiple web surfaces at port 8080:

URL Surface Type
/v1/docs OpenAPI spec API documentation
/vnc/index.html?autoconnect=true VNC Browser Desktop streaming
/code-server/ VSCode Server Web-based IDE
/mcp MCP services Protocol endpoint
Jupyter Notebook interface Interactive computing

The VNC browser provides real-time visual access to the sandbox — humans can observe and interact.

Website Documentation

https://sandbox.agent-infra.com/ — project website https://sandbox.agent-infra.com/api — API documentation

Cross-Tool Portability

High — MCP endpoint works with any MCP-compatible agent. REST API works with any HTTP client. SDKs in Python/TypeScript/Go.

Observability

  • VNC stream for visual monitoring
  • OpenAPI docs at /v1/docs
  • No built-in logging/tracing beyond what Docker provides

IDE Integration

VSCode Server (/code-server/) built into container — agents can access a full VS Code web environment inside the sandbox.

Related frameworks

same archetype · same primary tool · same memory type

Daytona ★ 72k
A9 Sandbox substrate

Provide secure, elastic, sub-90ms sandbox compute infrastructure for running AI-generated code, accessible via multi-language…

CUA ★ 17k
A9 Sandbox substrate

Unified SDK for building, benchmarking, and deploying agents that interact with full OS GUIs via isolated VMs.

E2B ★ 12k
A9 Sandbox substrate

Run AI-generated code safely in cloud-hosted isolated sandboxes via a 3-line SDK integration.

OpenSandbox ★ 11k
A9 Sandbox substrate

Protocol-first general-purpose sandbox platform for AI applications with multi-language SDKs and pluggable isolation backends.

Microsandbox ★ 6.3k
A9 Sandbox substrate

Spawn hardware-isolated microVMs as child processes directly from application code, with no server setup, in under 100ms.

CubeSandbox ★ 5.9k
A9 Sandbox substrate

Sub-60ms KVM microVM sandboxes for AI agents with E2B drop-in compatibility and <5MB memory overhead.