aeroxy/cage-bro

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.