How superradcompany/microsandbox works
Microsandbox is a cross-platform local microVM platform for isolating untrusted workloads. Users initiate work through the CLI or language SDKs: choose or pull an OCI image, create/run and manage a sandbox, then inspect it, execute commands, or save and restore snapshots. The repository separates host-side control, guest agent and VM execution, image/filesystem handling, networking, and persisted sandbox state. The README documents the product workflow and capabilities; several subsystem links below are dashed where sampled source did not expose their wiring.
Main entry points: runner VM Runner · commands CLI Commands · executor.rs Operation Executor · control-client Control Clients
Components 20
User Interfaces
- CLI Commands
crates/cli/lib/commands - Language SDKs
sdk - Control Clients
packages/control-client - Protocol Clients
packages/protocol-client
Control Plane
- Control Server
crates/runtime/lib/runner/control/server.rs - Request Dispatcher
crates/runtime/lib/runner/control/dispatch.rs - Operation Handler
crates/runtime/lib/runner/control/handler.rs - Operation Executor
crates/runtime/lib/runner/control/executor.rs - Runtime Client
crates/runtime/lib/client
Sandbox Execution
- VM Runner
crates/runtime/lib/runner - Guest Agent
crates/agentd/lib - Agent Protocol
crates/protocol/lib - Filesystem Backends
crates/filesystem/lib/backends - Network Engine
crates/network/lib/engine
Images and Snapshots
- OCI Image Handling
crates/image/lib/registry/client.rs - Root Filesystem Images
crates/image/lib/ext4/formatter.rs - Checkpoint and Restore
crates/runtime/lib/checkpoint
Host Services
- Sandbox Catalog
crates/db/lib - Metrics Collection
crates/metrics-collector/lib/core
Other components
- User or Agent
Connections 21
- User or Agent → CLI Commands: runs commands
- User or Agent → Language SDKs: embeds runtime
- CLI Commands → Control Clients: issues requests
- Language SDKs → Control Clients: controls sandboxes
- Control Clients → Protocol Clients: uses framed transport
packages/control-client/typescript/src/json-client.ts - Protocol Clients → Control Server: sends requests
- Control Server → Request Dispatcher: dispatches sessions
crates/runtime/lib/runner/control/server.rs - Request Dispatcher → Operation Handler: routes requests
crates/runtime/lib/runner/control/dispatch.rs - Operation Handler → Operation Executor: executes operations
crates/runtime/lib/runner/control/handler.rs - Operation Executor → Runtime Client: controls runtime
- Runtime Client → VM Runner: starts workloads
- VM Runner → Guest Agent: runs guest agent
- Guest Agent → Agent Protocol: exchanges messages
- VM Runner → Filesystem Backends: mounts filesystems
- VM Runner → Network Engine: configures networking
- CLI Commands → OCI Image Handling: pulls images
- OCI Image Handling → Root Filesystem Images: builds root filesystems
- CLI Commands → Checkpoint and Restore: saves or restores
- Operation Executor → Checkpoint and Restore: coordinates snapshots
- Operation Executor → Sandbox Catalog: updates sandbox state
- VM Runner → Metrics Collection: provides runtime samples