# agent-infra/sandbox architecture

> Architecture diagram of the GitHub repository agent-infra/sandbox, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/agent-infra/sandbox
- Repository: https://github.com/agent-infra/sandbox

## Overview

1. **What this repo is**
   This is a monorepo for an “all-in-one” sandbox product: a Dockerized runtime that exposes multiple agent-facing capabilities, plus language SDKs, docs, examples, and an evaluation harness. The actual sandbox service is consumed as a container image; the repo mostly contains the client surfaces, packaging, and surrounding tooling.

2. **Primary runtime boundary**
   The deployable unit is a single container listening on **port 8080**. From that one runtime, users reach:
   - HTTP APIs under `/v1`
   - VNC browser access
   - VSCode Server (`/code-server/`)
   - MCP endpoints (`/mcp`)
   The README and compose file emphasize a **shared filesystem** and a unified execution environment inside the container.

3. **Core service domains**
   The API is organized into capability-specific resource groups, not a single generic command endpoint. The main domains are:
   - sandbox context / environment info
   - shell sessions and process control
   - file operations
   - browser automation
   - code execution
   - Jupyter and Node.js runtimes
   - proxy management
   - MCP tool access
   - skills registration/content
   - browser state, cookies, network, tabs, captcha, page actions

4. **Shared workspace as the main data plane**
   A key architectural feature is the **single shared workspace** inside the container. Data produced in one subsystem is immediately available to others:
   - browser downloads can be read by file APIs
   - shell commands can manipulate the same files
   - Jupyter/Node.js can write artifacts into the workspace
   This shared state is the main integration boundary across the whole product.

5. **Browser subsystem**
   Browser support is broader than “open a page”: it includes page actions, tabs, cookies, network inspection/routing, screenshots, recording, captcha handling, and state persistence. The README also shows CDP/VNC usage, so browser automation can be driven both programmatically and visually. In diagrams, this is a major user-facing lane separate from shell/file.

6. **Shell and terminal subsystem**
   Shell support is session-based and includes create/list/exec/write/view/wait/kill/cleanup flows. The README calls out a web terminal, which implies interactive process sessions rather than only one-shot command execution. This subsystem is the primary path for command-line work inside the sandbox.

7. **Code execution runtimes**
   Python and Node.js are modeled as dedicated execution services, not just shell commands:
   - **Jupyter** for notebook-style Python execution and session management
   - **Node.js** for JS execution and session lifecycle
   These are separate from shell, which matters for architecture because they imply isolated runtime contexts with their own session state and outputs.

8. **File and content tooling**
   The file API is a first-class subsystem with read/write/list/search/grep/glob/find/replace/upload/download operations. The presence of search, replace-in-file, and str-replace-editor endpoints suggests the file layer is designed for agent editing workflows, not just basic storage access.

9. **MCP and skills as the agent integration layer**
   MCP is positioned as the tool-execution boundary for agents, with servers/tools for browser, file, shell, and markdown conversion. Skills management is a separate capability for registering, listing, retrieving, and clearing reusable skills/metadata. In an architecture diagram, these sit between the core sandbox services and external agent frameworks.

10. **Proxy and connectivity control**
   There is an explicit proxy subsystem for mappings, excludes, and diagnosis. This is important because the sandbox is meant to access external websites and services while staying within controlled networking rules. The README’s environment variables for proxy and DNS-over-HTTPS reinforce that outbound connectivity is a managed concern.

11. **SDK surfaces**
   The repo ships generated client SDKs for **JavaScript/TypeScript** and **Python**, and references a Go SDK as well. The JS SDK has a shared fetch/core layer and per-resource clients; the Python SDK uses generated client wrappers and typed models. These SDKs are the main consumer-facing boundary to the HTTP API.

12. **Examples and integration patterns**
   The `examples/` tree is not core runtime code; it is a set of isolated sample projects showing how to combine the sandbox with external tools like Playwright, Browser Use, OpenAI, LangGraph, and S3. These examples are useful for understanding intended data flows, especially browser-to-file-to-code workflows.

13. **Documentation and API contract**
   The `website/` package is a full docs site in English and Chinese, with guides, examples, API pages, and the published OpenAPI spec in `public/v1/openapi.json`. This means the repo treats the API contract as a first-class artifact, and the docs site is part of the product boundary.

14. **Evaluation and release pipeline**
   The `evaluation/` directory contains benchmark datasets, an agent loop, parsing, and captured results, so there is a separate validation pipeline for sandbox capabilities. GitHub Actions build/publish the container image and SDKs, indicating the repo’s outputs are split into runtime image, SDK packages, and documentation releases.

Main entry points: [`README.md`](https://github.com/agent-infra/sandbox/blob/main/README.md) (HTTP API), [`sdk/js/src/api/resources/mcp`](https://github.com/agent-infra/sandbox/tree/main/sdk/js/src/api/resources/mcp) (MCP tools), [`sdk/js/src/api/resources/file`](https://github.com/agent-infra/sandbox/tree/main/sdk/js/src/api/resources/file) (File tools), [`sdk/js/src/api/resources/browserPage`](https://github.com/agent-infra/sandbox/tree/main/sdk/js/src/api/resources/browserPage) (Browser automation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Sandbox runtime"]
  node_container["Sandbox image<br/>container runtime<br/>[README.md]"]
  node_api["HTTP API<br/>service API<br/>[README.md]"]
  node_workspace[("Shared workspace<br/>data plane<br/>[README.md]")]
  node_shell["Shell sessions<br/>process control"]
  node_files["File tools<br/>file service"]
  node_browser["Browser automation<br/>browser service"]
  node_browser_net["Network control<br/>browser network"]
  node_browser_state["Browser state<br/>browser persistence"]
  node_browser_tabs["Tabs<br/>browser navigation"]
  node_code_exec["Code execution<br/>code service"]
  node_jupyter["Jupyter<br/>python runtime"]
  node_nodejs["Node.js<br/>js runtime"]
  node_proxy["Proxy control<br/>network policy"]
  node_mcp["MCP tools<br/>agent tools"]
  node_skills["Skills<br/>agent metadata"]
end

subgraph group_clients["SDK clients"]
  node_js_sdk["JS SDK<br/>generated client"]
  node_py_sdk["Python SDK<br/>generated client"]
  node_go_sdk["Go SDK<br/>sdk surface"]
end

subgraph group_platform["Product surface"]
  node_website["Docs site<br/>documentation site"]
  node_examples["Examples<br/>sample projects"]
  node_eval["Evaluation<br/>benchmark harness"]
  node_ci["GitHub Actions<br/>release pipeline<br/>[workflows]"]
end

node_container -->|"exposes"| node_api
node_container -->|"hosts"| node_workspace
node_api -->|"routes to"| node_shell
node_api -->|"routes to"| node_files
node_api -->|"routes to"| node_browser
node_api -->|"routes to"| node_browser_net
node_api -->|"routes to"| node_browser_state
node_api -->|"routes to"| node_browser_tabs
node_api -->|"routes to"| node_code_exec
node_api -->|"routes to"| node_jupyter
node_api -->|"routes to"| node_nodejs
node_api -->|"routes to"| node_proxy
node_api -->|"routes to"| node_mcp
node_api -->|"routes to"| node_skills
node_shell -->|"reads/writes"| node_workspace
node_files -->|"reads/writes"| node_workspace
node_browser -->|"exports to"| node_workspace
node_jupyter -->|"writes artifacts"| node_workspace
node_nodejs -->|"writes artifacts"| node_workspace
node_mcp -.->|"wraps"| node_shell
node_mcp -.->|"wraps"| node_files
node_mcp -.->|"wraps"| node_browser
node_js_sdk -->|"consumes"| node_api
node_py_sdk -->|"consumes"| node_api
node_go_sdk -.->|"consumes"| node_api
node_website -->|"documents"| node_api
node_examples -->|"shows usage"| node_js_sdk
node_examples -->|"demonstrates"| node_browser
node_examples -->|"demonstrates"| node_files
node_eval -->|"benchmarks"| node_container
node_ci -->|"builds"| node_container
node_ci -->|"publishes"| node_js_sdk
node_ci -->|"publishes"| node_py_sdk

click node_container "https://github.com/agent-infra/sandbox/blob/main/README.md"
click node_api "https://github.com/agent-infra/sandbox/blob/main/README.md"
click node_workspace "https://github.com/agent-infra/sandbox/blob/main/README.md"
click node_shell "https://github.com/agent-infra/sandbox/tree/main/sdk/js/src/api/resources/shell"
click node_files "https://github.com/agent-infra/sandbox/tree/main/sdk/js/src/api/resources/file"
click node_browser "https://github.com/agent-infra/sandbox/tree/main/sdk/js/src/api/resources/browserPage"
click node_browser_net "https://github.com/agent-infra/sandbox/tree/main/sdk/js/src/api/resources/browserNetwork"
click node_browser_state "https://github.com/agent-infra/sandbox/tree/main/sdk/js/src/api/resources/browserState"
click node_browser_tabs "https://github.com/agent-infra/sandbox/tree/main/sdk/js/src/api/resources/browserTabs"
click node_code_exec "https://github.com/agent-infra/sandbox/tree/main/sdk/js/src/api/resources/code"
click node_jupyter "https://github.com/agent-infra/sandbox/tree/main/sdk/js/src/api/resources/jupyter"
click node_nodejs "https://github.com/agent-infra/sandbox/tree/main/sdk/js/src/api/resources/nodejs"
click node_proxy "https://github.com/agent-infra/sandbox/tree/main/sdk/js/src/api/resources/proxy"
click node_mcp "https://github.com/agent-infra/sandbox/tree/main/sdk/js/src/api/resources/mcp"
click node_skills "https://github.com/agent-infra/sandbox/tree/main/sdk/js/src/api/resources/skills"
click node_js_sdk "https://github.com/agent-infra/sandbox/tree/main/sdk/js"
click node_py_sdk "https://github.com/agent-infra/sandbox/tree/main/sdk/python"
click node_go_sdk "https://github.com/agent-infra/sandbox/tree/main/sdk/go"
click node_website "https://github.com/agent-infra/sandbox/tree/main/website/docs"
click node_examples "https://github.com/agent-infra/sandbox/tree/main/examples"
click node_eval "https://github.com/agent-infra/sandbox/tree/main/evaluation"
click node_ci "https://github.com/agent-infra/sandbox/blob/main/.github/workflows"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_container,node_api,node_workspace,node_shell,node_files,node_browser,node_browser_net,node_browser_state,node_browser_tabs,node_code_exec,node_jupyter,node_nodejs,node_proxy,node_mcp,node_skills toneBlue
class node_js_sdk,node_py_sdk,node_go_sdk toneAmber
class node_website,node_examples,node_eval,node_ci toneMint
```

## Components

### Sandbox runtime

Deployable container and its exposed capability domains.

- [Sandbox image](https://github.com/agent-infra/sandbox/blob/main/README.md): container runtime · Single Dockerized service on port 8080 exposing HTTP, VNC, code-server, and MCP. · `README.md`
- [HTTP API](https://github.com/agent-infra/sandbox/blob/main/README.md): service API · Primary /v1 control plane for sandbox capabilities. · `README.md`
- [Shared workspace](https://github.com/agent-infra/sandbox/blob/main/README.md): data plane · Common filesystem used by shell, browser downloads, code runtimes, and file APIs. · `README.md`
- [Shell sessions](https://github.com/agent-infra/sandbox/tree/main/sdk/js/src/api/resources/shell): process control · Session-based terminal execution, output, wait, kill, and cleanup flows. · `sdk/js/src/api/resources/shell`
- [File tools](https://github.com/agent-infra/sandbox/tree/main/sdk/js/src/api/resources/file): file service · Read/write/list/search/replace/upload/download operations over the shared filesystem. · `sdk/js/src/api/resources/file`
- [Browser automation](https://github.com/agent-infra/sandbox/tree/main/sdk/js/src/api/resources/browserPage): browser service · Page actions, tabs, screenshots, recording, and browser state interactions. · `sdk/js/src/api/resources/browserPage`
- [Network control](https://github.com/agent-infra/sandbox/tree/main/sdk/js/src/api/resources/browserNetwork): browser network · Proxying, routing, headers, request capture, cookies, and HAR export for browser traffic. · `sdk/js/src/api/resources/browserNetwork`
- [Browser state](https://github.com/agent-infra/sandbox/tree/main/sdk/js/src/api/resources/browserState): browser persistence · Persist and restore browser session state across agent runs. · `sdk/js/src/api/resources/browserState`
- [Tabs](https://github.com/agent-infra/sandbox/tree/main/sdk/js/src/api/resources/browserTabs): browser navigation · Create, activate, list, and close browser tabs. · `sdk/js/src/api/resources/browserTabs`
- [Code execution](https://github.com/agent-infra/sandbox/tree/main/sdk/js/src/api/resources/code): code service · Dedicated code execution boundary distinct from shell. · `sdk/js/src/api/resources/code`
- [Jupyter](https://github.com/agent-infra/sandbox/tree/main/sdk/js/src/api/resources/jupyter): python runtime · Notebook-style Python sessions, execution, and lifecycle management. · `sdk/js/src/api/resources/jupyter`
- [Node.js](https://github.com/agent-infra/sandbox/tree/main/sdk/js/src/api/resources/nodejs): js runtime · Managed JavaScript sessions with execute and session lifecycle APIs. · `sdk/js/src/api/resources/nodejs`
- [Proxy control](https://github.com/agent-infra/sandbox/tree/main/sdk/js/src/api/resources/proxy): network policy · Outbound mapping, exclusions, and diagnosis for managed connectivity. · `sdk/js/src/api/resources/proxy`
- [MCP tools](https://github.com/agent-infra/sandbox/tree/main/sdk/js/src/api/resources/mcp): agent tools · Tool execution boundary for browser, file, shell, and markdown conversion tools. · `sdk/js/src/api/resources/mcp`
- [Skills](https://github.com/agent-infra/sandbox/tree/main/sdk/js/src/api/resources/skills): agent metadata · Register, list, retrieve, and clear reusable skill metadata/content. · `sdk/js/src/api/resources/skills`

### SDK clients

Generated client surfaces for the HTTP API.

- [JS SDK](https://github.com/agent-infra/sandbox/tree/main/sdk/js): generated client · Generated TypeScript/JavaScript client with core fetch layer and per-resource wrappers. · `sdk/js`
- [Python SDK](https://github.com/agent-infra/sandbox/tree/main/sdk/python): generated client · Generated Python client package with typed models and resource clients. · `sdk/python`
- [Go SDK](https://github.com/agent-infra/sandbox/tree/main/sdk/go): sdk surface · Referenced Go client surface for the same API boundary. · `sdk/go`

### Product surface

Documentation, examples, and evaluation tooling around the runtime.

- [Docs site](https://github.com/agent-infra/sandbox/tree/main/website/docs): documentation site · Bilingual documentation site and published OpenAPI contract. · `website/docs`
- [Examples](https://github.com/agent-infra/sandbox/tree/main/examples): sample projects · Isolated integration examples for browser, code, agents, storage, and providers. · `examples`
- [Evaluation](https://github.com/agent-infra/sandbox/tree/main/evaluation): benchmark harness · Datasets, agent loop, parsing, and captured benchmark results. · `evaluation`
- [GitHub Actions](https://github.com/agent-infra/sandbox/blob/main/.github/workflows): release pipeline · Build, publish, and SDK CI workflows for runtime image and client releases. · `.github/workflows`

## Connections

- Sandbox image → HTTP API: exposes · The container is the single runtime boundary for the API and interactive surfaces.
- Sandbox image → Shared workspace: hosts · All major capabilities share one filesystem inside the container.
- HTTP API → Shell sessions: routes to · Shell endpoints manage persistent terminal/process sessions.
- HTTP API → File tools: routes to · File endpoints operate on the shared workspace.
- HTTP API → Browser automation: routes to · Browser endpoints drive page-level automation and stateful interactions.
- HTTP API → Network control: routes to · Network endpoints manage browser traffic controls and captures.
- HTTP API → Browser state: routes to · State endpoints persist and restore browser context.
- HTTP API → Tabs: routes to · Tab endpoints manage browser windows and page lifecycle.
- HTTP API → Code execution: routes to · Dedicated code execution boundary for programmatic workloads.
- HTTP API → Jupyter: routes to · Python notebook sessions are managed separately from shell.
- HTTP API → Node.js: routes to · JavaScript sessions are managed separately from shell.
- HTTP API → Proxy control: routes to · Proxy endpoints control external connectivity.
- HTTP API → MCP tools: routes to · MCP endpoints expose sandbox tools to agents.
- HTTP API → Skills: routes to · Skills endpoints manage reusable agent content and metadata.
- Shell sessions → Shared workspace: reads/writes · Terminal sessions manipulate the same filesystem as other subsystems.
- File tools → Shared workspace: reads/writes · File tools are the direct filesystem interface.
- Browser automation → Shared workspace: exports to · Browser downloads and artifacts land in shared storage.
- Jupyter → Shared workspace: writes artifacts · Python notebooks can create files visible to shell and file tools.
- Node.js → Shared workspace: writes artifacts · Node.js execution can persist outputs into the shared filesystem.
- MCP tools → Shell sessions: wraps · Tool boundary can invoke shell capabilities for agents.
- MCP tools → File tools: wraps · Tool boundary can invoke file capabilities for agents.
- MCP tools → Browser automation: wraps · Tool boundary can invoke browser capabilities for agents.
- JS SDK → HTTP API: consumes · Generated JS/TS client is the main typed consumer of the HTTP API.
- Python SDK → HTTP API: consumes · Generated Python client is the main typed consumer of the HTTP API.
- Go SDK → HTTP API: consumes · Go SDK mirrors the same API surface.
- Docs site → HTTP API: documents · Docs site publishes guides and the OpenAPI contract.
- Examples → JS SDK: shows usage · Examples demonstrate API usage patterns through client SDKs.
- Examples → Browser automation: demonstrates · Examples cover browser automation flows.
- Examples → File tools: demonstrates · Examples cover file-centric workflows.
- Evaluation → Sandbox image: benchmarks · Evaluation harness measures behavior of the sandbox image.
- GitHub Actions → Sandbox image: builds · Workflows publish the container image.
- GitHub Actions → JS SDK: publishes · Workflows test and publish the JS SDK.
- GitHub Actions → Python SDK: publishes · Workflows test and publish the Python SDK.
