# aeroxy/cage-bro architecture

> Architecture diagram of the GitHub repository aeroxy/cage-bro, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aeroxy/cage-bro
- Repository: https://github.com/aeroxy/cage-bro

## Overview

1. **Top-level shape**
   - This is a polyrepo-style workspace centered on one Rust server binary, `cage-bro`, plus supporting crates, language SDKs, CLIs, docs, examples, and two marketing/demo sites.
   - The architectural core is the Rust server; everything else either calls it, embeds its UI, or packages it for distribution.

2. **Core runtime boundary**
   - The main production artifact is `crates/cage-bro`, built from `src/main.rs`, `src/server.rs`, and subsystem modules under `src/api`, `src/browser`, and `src/mcp`.
   - That binary exposes the control plane over HTTP, serves the dashboard, and coordinates the execution subsystems.

3. **Execution and sandboxing layer**
   - `crates/cage-bro-runtime` is the low-level process/session/isolation layer.
   - It owns the mechanics for shell execution, PTY/session handling, filesystem access, local filesystem adapters, and Linux-focused isolation primitives such as Landlock plus `rlimit` caps.
   - The README makes the key boundary explicit: untrusted code runs as child processes before `exec`, with filesystem confinement and resource limits, but network/syscall filtering is left to the deployment environment.

4. **Code execution subsystem**
   - `crates/cage-bro-code` packages code-runner support, including Jupyter integration.
   - The server exposes code execution APIs, while this crate handles the language/runtime-specific execution model, especially the stateful Jupyter path versus stateless Python/Node execution.

5. **Shell and terminal subsystem**
   - Shell execution is a first-class path in the API and is backed by PTY/session primitives in the runtime crate.
   - There is also a WebSocket terminal test (`tests/ws_terminal.rs`), which indicates interactive shell sessions are exposed over a real-time channel rather than only request/response HTTP.

6. **Filesystem subsystem**
   - File operations are separated into a dedicated API module and runtime filesystem abstractions.
   - The system treats the workspace as the main writable boundary: read/write/edit/list/search operations are scoped to the sandbox workspace, and snapshots operate on that workspace tree only.

7. **Browser subsystem**
   - `src/browser` contains a browser manager and CDP client code, which points to a separate browser process or sidecar controlled through Chrome DevTools Protocol.
   - The README states the browser is “Obscura” stealth mode, so browser automation is not embedded directly in the Rust process; it is orchestrated through a browser-control boundary.

8. **MCP and agent-tooling boundary**
   - `src/mcp` implements an MCP server, with both stdio and HTTP/SSE modes mentioned in the README.
   - This makes cage-bro usable as a tool provider for Claude Desktop, Cursor, and other MCP-aware agents, while the REST API remains the native control plane.

9. **E2B compatibility layer**
   - `src/api/e2b.rs` and the README show an E2B-compatible sandbox lifecycle API at the server root.
   - This layer is about sandbox orchestration: create/list/get/kill sandboxes, plus a cage-bro-specific `/exec` extension for running commands inside a tracked sandbox.

10. **HTTP API surface**
   - `src/api` is split by capability: browser, code, file, shell, sandbox, and E2B.
   - That separation matters architecturally because consumers can use narrow tool-specific endpoints instead of a generic “run arbitrary command” interface, which matches the agent/tooling design.

11. **Dashboard as embedded UI**
   - The dashboard is a separate React/Vite app under `crates/cage-bro/dashboard`, but the README says it is embedded into the Rust binary.
   - It provides local operator UI for terminal, code, files, and browser views, with the server serving both the API and the UI from the same origin.

12. **Client and distribution layer**
   - `sdk/python` and `sdk/typescript` are thin client libraries for the HTTP API.
   - `cli-python`, `cli-typescript`, Cargo packaging, and the Homebrew formula under `Formula/` are distribution wrappers around the same server functionality, not separate execution engines.

13. **Demo and documentation surfaces**
   - `landing-page` is the public marketing site, while `wiki/`, `GUIDE.md`, and the examples under `examples/` document integration patterns and common use cases.
   - These are important for architecture diagrams only insofar as they show the intended integration modes: direct HTTP, MCP, SDKs, and external agents.

14. **State model and lifecycle**
   - The server’s sandbox registry and snapshot index are in-memory and scoped to a running process.
   - That means lifecycle state is ephemeral by design: restart the server and the registry/snapshot index is rebuilt fresh; snapshots are filesystem-state only, not process-memory state.

15. **Key external dependencies and trust boundaries**
   - External boundaries that materially affect the architecture are the host kernel/filesystem, a separate browser process reachable via CDP, and optional Jupyter infrastructure for notebook-style execution.
   - The repo is designed so the Rust binary is the orchestration hub, but security guarantees depend on the surrounding VM/container/host policy for network isolation and syscall filtering.

Main entry points: [`crates/cage-bro/src/api/mod.rs`](https://github.com/aeroxy/cage-bro/blob/main/crates/cage-bro/src/api/mod.rs) (API), [`crates/cage-bro/src/server.rs`](https://github.com/aeroxy/cage-bro/blob/main/crates/cage-bro/src/server.rs) (Server), [`crates/cage-bro-runtime/src/lib.rs`](https://github.com/aeroxy/cage-bro/blob/main/crates/cage-bro-runtime/src/lib.rs) (Runtime), [`examples/claude-desktop/README.md`](https://github.com/aeroxy/cage-bro/blob/main/examples/claude-desktop/README.md) (Examples)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Rust Core"]
  node_cage_bro_bin["cage-bro<br/>Rust server binary<br/>[main.rs]"]
  node_server["Server<br/>control plane<br/>[server.rs]"]
  node_runtime["Runtime<br/>process/session layer<br/>[lib.rs]"]
  node_processes["Processes<br/>child exec<br/>[process.rs]"]
  node_sessions["Sessions<br/>pty/session<br/>[session.rs]"]
  node_fs_layer["Filesystem<br/>fs abstraction<br/>[filesystem.rs]"]
  node_isolation["Isolation<br/>sandboxing<br/>[isolation.rs]"]
  node_code_runtime["Code Runtime<br/>jupyter/code runner<br/>[lib.rs]"]
end

subgraph group_interfaces["Interfaces"]
  node_api_mod["API<br/>HTTP routes<br/>[mod.rs]"]
  node_shell_api["Shell API<br/>interactive exec<br/>[shell.rs]"]
  node_file_api["Files API<br/>workspace fs<br/>[file.rs]"]
  node_code_api["Code API<br/>code execution<br/>[code.rs]"]
  node_sandbox_api["Sandbox API<br/>lifecycle<br/>[sandbox.rs]"]
  node_e2b_api["E2B API<br/>compat layer<br/>[e2b.rs]"]
  node_browser_api["Browser API<br/>browser control<br/>[browser.rs]"]
  node_mcp_server["MCP Server<br/>tool server<br/>[server.rs]"]
  node_browser_mgr["Browser Mgmt<br/>browser orchestrator<br/>[manager.rs]"]
  node_cdp_client["CDP Client<br/>browser transport<br/>[cdp.rs]"]
  node_dashboard["Dashboard<br/>embedded UI<br/>[App.tsx]"]
end

subgraph group_distribution["Distribution"]
  node_python_sdk["Python SDK<br/>HTTP client<br/>[client.py]"]
  node_ts_sdk["TS SDK<br/>HTTP client<br/>[index.ts]"]
  node_py_cli["Py CLI<br/>wrapper<br/>[__init__.py]"]
  node_ts_cli["TS CLI<br/>wrapper<br/>[cage-bro.js]"]
end

subgraph group_docs["Docs & Demos"]
  node_examples["Examples<br/>integration samples<br/>[README.md]"]
  node_wiki["Wiki<br/>documentation<br/>[overview.md]"]
  node_landing["Landing Page<br/>marketing site<br/>[App.tsx]"]
end

node_cage_bro_bin -->|"boots"| node_server
node_server -->|"routes"| node_api_mod
node_api_mod -->|"shell"| node_shell_api
node_api_mod -->|"files"| node_file_api
node_api_mod -->|"code"| node_code_api
node_api_mod -->|"sandboxes"| node_sandbox_api
node_api_mod -->|"e2b"| node_e2b_api
node_api_mod -->|"browser"| node_browser_api
node_server -->|"executes"| node_runtime
node_runtime -->|"spawns"| node_processes
node_runtime -->|"pty"| node_sessions
node_runtime -->|"scopes"| node_fs_layer
node_runtime -->|"confines"| node_isolation
node_code_api -->|"runs on"| node_code_runtime
node_browser_api -->|"controls"| node_browser_mgr
node_browser_mgr -->|"uses"| node_cdp_client
node_server -->|"serves"| node_mcp_server
node_server -->|"embeds"| node_dashboard
node_python_sdk -->|"calls"| node_api_mod
node_ts_sdk -->|"calls"| node_api_mod
node_py_cli -->|"wraps"| node_api_mod
node_ts_cli -->|"wraps"| node_api_mod
node_examples -->|"demonstrate"| node_mcp_server
node_examples -->|"demonstrate"| node_api_mod
node_wiki -->|"documents"| node_api_mod
node_landing -->|"presents"| node_server

click node_cage_bro_bin "https://github.com/aeroxy/cage-bro/blob/main/crates/cage-bro/src/main.rs"
click node_server "https://github.com/aeroxy/cage-bro/blob/main/crates/cage-bro/src/server.rs"
click node_api_mod "https://github.com/aeroxy/cage-bro/blob/main/crates/cage-bro/src/api/mod.rs"
click node_shell_api "https://github.com/aeroxy/cage-bro/blob/main/crates/cage-bro/src/api/shell.rs"
click node_file_api "https://github.com/aeroxy/cage-bro/blob/main/crates/cage-bro/src/api/file.rs"
click node_code_api "https://github.com/aeroxy/cage-bro/blob/main/crates/cage-bro/src/api/code.rs"
click node_sandbox_api "https://github.com/aeroxy/cage-bro/blob/main/crates/cage-bro/src/api/sandbox.rs"
click node_e2b_api "https://github.com/aeroxy/cage-bro/blob/main/crates/cage-bro/src/api/e2b.rs"
click node_browser_api "https://github.com/aeroxy/cage-bro/blob/main/crates/cage-bro/src/api/browser.rs"
click node_mcp_server "https://github.com/aeroxy/cage-bro/blob/main/crates/cage-bro/src/mcp/server.rs"
click node_browser_mgr "https://github.com/aeroxy/cage-bro/blob/main/crates/cage-bro/src/browser/manager.rs"
click node_cdp_client "https://github.com/aeroxy/cage-bro/blob/main/crates/cage-bro/src/browser/cdp.rs"
click node_runtime "https://github.com/aeroxy/cage-bro/blob/main/crates/cage-bro-runtime/src/lib.rs"
click node_processes "https://github.com/aeroxy/cage-bro/blob/main/crates/cage-bro-runtime/src/process.rs"
click node_sessions "https://github.com/aeroxy/cage-bro/blob/main/crates/cage-bro-runtime/src/session.rs"
click node_fs_layer "https://github.com/aeroxy/cage-bro/blob/main/crates/cage-bro-runtime/src/filesystem.rs"
click node_isolation "https://github.com/aeroxy/cage-bro/blob/main/crates/cage-bro-runtime/src/isolation.rs"
click node_code_runtime "https://github.com/aeroxy/cage-bro/blob/main/crates/cage-bro-code/src/lib.rs"
click node_dashboard "https://github.com/aeroxy/cage-bro/blob/main/crates/cage-bro/dashboard/src/App.tsx"
click node_python_sdk "https://github.com/aeroxy/cage-bro/blob/main/sdk/python/cage_bro/client.py"
click node_ts_sdk "https://github.com/aeroxy/cage-bro/blob/main/sdk/typescript/src/index.ts"
click node_py_cli "https://github.com/aeroxy/cage-bro/blob/main/cli-python/cage_bro_cli/__init__.py"
click node_ts_cli "https://github.com/aeroxy/cage-bro/blob/main/cli-typescript/bin/cage-bro.js"
click node_examples "https://github.com/aeroxy/cage-bro/blob/main/examples/claude-desktop/README.md"
click node_wiki "https://github.com/aeroxy/cage-bro/blob/main/wiki/overview.md"
click node_landing "https://github.com/aeroxy/cage-bro/blob/main/landing-page/src/App.tsx"

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_cage_bro_bin,node_server,node_runtime,node_processes,node_sessions,node_fs_layer,node_isolation,node_code_runtime toneBlue
class node_api_mod,node_shell_api,node_file_api,node_code_api,node_sandbox_api,node_e2b_api,node_browser_api,node_mcp_server,node_browser_mgr,node_cdp_client,node_dashboard toneAmber
class node_python_sdk,node_ts_sdk,node_py_cli,node_ts_cli toneMint
class node_examples,node_wiki,node_landing toneRose
```

## Components

### Rust Core

Primary server binary and execution crates

- [cage-bro](https://github.com/aeroxy/cage-bro/blob/main/crates/cage-bro/src/main.rs): Rust server binary · Main orchestrator that exposes HTTP, dashboard, and agent-tooling entry points · `crates/cage-bro/src/main.rs`
- [Server](https://github.com/aeroxy/cage-bro/blob/main/crates/cage-bro/src/server.rs): control plane · Coordinates requests, sandbox lifecycle, and subsystem routing · `crates/cage-bro/src/server.rs`
- [Runtime](https://github.com/aeroxy/cage-bro/blob/main/crates/cage-bro-runtime/src/lib.rs): process/session layer · Low-level execution, PTY, filesystem, and isolation boundary · `crates/cage-bro-runtime/src/lib.rs`
- [Processes](https://github.com/aeroxy/cage-bro/blob/main/crates/cage-bro-runtime/src/process.rs): child exec · Shell process spawning and execution mechanics · `crates/cage-bro-runtime/src/process.rs`
- [Sessions](https://github.com/aeroxy/cage-bro/blob/main/crates/cage-bro-runtime/src/session.rs): pty/session · Interactive terminal and session lifecycle primitives · `crates/cage-bro-runtime/src/session.rs`
- [Filesystem](https://github.com/aeroxy/cage-bro/blob/main/crates/cage-bro-runtime/src/filesystem.rs): fs abstraction · Workspace filesystem abstraction and adapters · `crates/cage-bro-runtime/src/filesystem.rs`
- [Isolation](https://github.com/aeroxy/cage-bro/blob/main/crates/cage-bro-runtime/src/isolation.rs): sandboxing · Landlock and resource-limit confinement primitives · `crates/cage-bro-runtime/src/isolation.rs`
- [Code Runtime](https://github.com/aeroxy/cage-bro/blob/main/crates/cage-bro-code/src/lib.rs): jupyter/code runner · Language execution support including Jupyter integration · `crates/cage-bro-code/src/lib.rs`

### Interfaces

APIs, MCP, dashboard, and browser control

- [API](https://github.com/aeroxy/cage-bro/blob/main/crates/cage-bro/src/api/mod.rs): HTTP routes · Capability-specific REST surface for shell, files, code, browser, sandbox, and E2B · `crates/cage-bro/src/api/mod.rs`
- [Shell API](https://github.com/aeroxy/cage-bro/blob/main/crates/cage-bro/src/api/shell.rs): interactive exec · Shell and terminal-oriented command execution endpoints · `crates/cage-bro/src/api/shell.rs`
- [Files API](https://github.com/aeroxy/cage-bro/blob/main/crates/cage-bro/src/api/file.rs): workspace fs · Workspace-scoped read/write/list/search/edit operations · `crates/cage-bro/src/api/file.rs`
- [Code API](https://github.com/aeroxy/cage-bro/blob/main/crates/cage-bro/src/api/code.rs): code execution · Code-runner endpoints for language execution and notebook flows · `crates/cage-bro/src/api/code.rs`
- [Sandbox API](https://github.com/aeroxy/cage-bro/blob/main/crates/cage-bro/src/api/sandbox.rs): lifecycle · Creates, tracks, and tears down sandbox sessions · `crates/cage-bro/src/api/sandbox.rs`
- [E2B API](https://github.com/aeroxy/cage-bro/blob/main/crates/cage-bro/src/api/e2b.rs): compat layer · E2B-compatible sandbox lifecycle surface plus exec extension · `crates/cage-bro/src/api/e2b.rs`
- [Browser API](https://github.com/aeroxy/cage-bro/blob/main/crates/cage-bro/src/api/browser.rs): browser control · HTTP surface for browser sessions and automation · `crates/cage-bro/src/api/browser.rs`
- [MCP Server](https://github.com/aeroxy/cage-bro/blob/main/crates/cage-bro/src/mcp/server.rs): tool server · MCP transport and tool exposure for agent clients · `crates/cage-bro/src/mcp/server.rs`
- [Browser Mgmt](https://github.com/aeroxy/cage-bro/blob/main/crates/cage-bro/src/browser/manager.rs): browser orchestrator · Manages external browser processes and session state · `crates/cage-bro/src/browser/manager.rs`
- [CDP Client](https://github.com/aeroxy/cage-bro/blob/main/crates/cage-bro/src/browser/cdp.rs): browser transport · Chrome DevTools Protocol client used to control the browser boundary · `crates/cage-bro/src/browser/cdp.rs`
- [Dashboard](https://github.com/aeroxy/cage-bro/blob/main/crates/cage-bro/dashboard/src/App.tsx): embedded UI · Embedded operator UI for terminal, code, files, and browser views · `crates/cage-bro/dashboard/src/App.tsx`

### Distribution

SDKs and CLI wrappers

- [Python SDK](https://github.com/aeroxy/cage-bro/blob/main/sdk/python/cage_bro/client.py): HTTP client · Python client library for the server API · `sdk/python/cage_bro/client.py`
- [TS SDK](https://github.com/aeroxy/cage-bro/blob/main/sdk/typescript/src/index.ts): HTTP client · TypeScript client library for the server API · `sdk/typescript/src/index.ts`
- [Py CLI](https://github.com/aeroxy/cage-bro/blob/main/cli-python/cage_bro_cli/__init__.py): wrapper · Python command-line wrapper around the server capabilities · `cli-python/cage_bro_cli/__init__.py`
- [TS CLI](https://github.com/aeroxy/cage-bro/blob/main/cli-typescript/bin/cage-bro.js): wrapper · TypeScript command-line wrapper around the server capabilities · `cli-typescript/bin/cage-bro.js`

### Docs & Demos

Examples, wiki, and marketing site

- [Examples](https://github.com/aeroxy/cage-bro/blob/main/examples/claude-desktop/README.md): integration samples · Representative agent and application integrations · `examples/claude-desktop/README.md`
- [Wiki](https://github.com/aeroxy/cage-bro/blob/main/wiki/overview.md): documentation · Architecture and usage guidance · `wiki/overview.md`
- [Landing Page](https://github.com/aeroxy/cage-bro/blob/main/landing-page/src/App.tsx): marketing site · Public marketing and product positioning site · `landing-page/src/App.tsx`

## Connections

- cage-bro → Server: boots · Binary initializes the server runtime
- Server → API: routes · Server dispatches requests into capability-specific HTTP modules
- API → Shell API: shell · Shell endpoints
- API → Files API: files · Filesystem endpoints
- API → Code API: code · Code execution endpoints
- API → Sandbox API: sandboxes · Sandbox lifecycle endpoints
- API → E2B API: e2b · Compatibility surface
- API → Browser API: browser · Browser control endpoints
- Server → Runtime: executes · Server relies on the runtime layer for process and session management
- Runtime → Processes: spawns · Child process execution
- Runtime → Sessions: pty · Interactive terminal sessions
- Runtime → Filesystem: scopes · Workspace filesystem access
- Runtime → Isolation: confines · Filesystem and resource isolation
- Code API → Code Runtime: runs on · Code API delegates language-specific execution to code runtime support
- Browser API → Browser Mgmt: controls · Browser API manages browser sessions through the browser manager
- Browser Mgmt → CDP Client: uses · Browser manager speaks CDP to the external browser process
- Server → MCP Server: serves · Server exposes MCP tooling entry points
- Server → Dashboard: embeds · Server serves the embedded dashboard UI
- Python SDK → API: calls · Python SDK consumes the HTTP API
- TS SDK → API: calls · TypeScript SDK consumes the HTTP API
- Py CLI → API: wraps · Python CLI wraps server capabilities
- TS CLI → API: wraps · TypeScript CLI wraps server capabilities
- Examples → MCP Server: demonstrate · Examples show agent-tooling integration paths
- Examples → API: demonstrate · Examples also show direct API integration
- Wiki → API: documents · Documentation explains API and integration patterns
- Landing Page → Server: presents · Marketing site represents the overall product