Nexus Sandbox Codebase Dossier

Nexus Sandbox is a compute-plane service for isolated code execution. It exposes sessions, command execution, workspace files, artifact export, and microVM snapshots through a FastAPI API, with a React Sandbox Console for local operation.

Read first

• Product and system overview
• Backend and runtime deep dive
• Data and artifact model
• Security and safety
• Interview preparation

System map

flowchart TD
  classDef default fill:#1e293b,stroke:#38bdf8,stroke-width:2px,color:#f8fafc
  classDef highlight fill:#065f46,stroke:#34d399,stroke-width:2px,color:#f0fdf4
  Client["Nexus worker or Console"]:::highlight --> API["FastAPI API"]
  API --> DB["SQLite metadata"]
  API --> Runtime{"Runtime adapter"}
  Runtime --> Local["Local subprocess"]
  Runtime --> MSB["Microsandbox microVM"]
  API --> Workspace["Scratch workspace"]
  API --> Artifacts["Artifact store"]
  MSB --> Snapshots["VM snapshots"]
  linkStyle default stroke:#64748b,stroke-width:2px

Top facts

• Sessions have TTLs, heartbeats, explicit stop/delete, and background cleanup.
• Runtime adapters share a protocol for lifecycle, execution, and snapshots.
• Local mode is development-only; microsandbox is the isolation-oriented backend.
• Every host filesystem path is resolved under a session root with traversal and symlink checks.
• Commands capture stdout/stderr to bounded log files and expose offset reads.
• Workspaces support individual files and tar/zip archive upload/download.
• Artifacts are copied to a separate export namespace with hashes.
• Snapshots persist VM disk state and optionally a workspace archive.
• Optional bearer auth protects every API route.
• SQLite stores metadata while the workspace/artifact trees store bytes.

Validation

uv run pytest
cd frontend && pnpm build
make -C projects/sandbox consolidate