# superradcompany/microsandbox architecture

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

- Interactive diagram: https://gitdiagram.com/superradcompany/microsandbox
- Repository: https://github.com/superradcompany/microsandbox

## Overview

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: [`crates/runtime/lib/runner`](https://github.com/superradcompany/microsandbox/tree/main/crates/runtime/lib/runner) (VM Runner), [`crates/cli/lib/commands`](https://github.com/superradcompany/microsandbox/tree/main/crates/cli/lib/commands) (CLI Commands), [`crates/runtime/lib/runner/control/executor.rs`](https://github.com/superradcompany/microsandbox/blob/main/crates/runtime/lib/runner/control/executor.rs) (Operation Executor), [`packages/control-client`](https://github.com/superradcompany/microsandbox/tree/main/packages/control-client) (Control Clients)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User Interfaces"]
  node_cli["CLI Commands"]
  node_sdk["Language SDKs"]
  node_control_clients["Control Clients"]
  node_protocol_clients["Protocol Clients"]
end

subgraph group_control["Control Plane"]
  node_control_server["Control Server<br/>[server.rs]"]
  node_dispatcher["Request Dispatcher<br/>[dispatch.rs]"]
  node_handler["Operation Handler<br/>[handler.rs]"]
  node_executor["Operation Executor<br/>[executor.rs]"]
  node_runtime_client["Runtime Client"]
end

subgraph group_execution["Sandbox Execution"]
  node_runner["VM Runner"]
  node_agent["Guest Agent"]
  node_protocol["Agent Protocol"]
  node_filesystem["Filesystem Backends"]
  node_network["Network Engine"]
end

subgraph group_artifacts["Images and Snapshots"]
  node_image["OCI Image Handling<br/>[client.rs]"]
  node_rootfs["Root Filesystem Images<br/>[formatter.rs]"]
  node_checkpoint["Checkpoint and Restore"]
end

subgraph group_services["Host Services"]
  node_database[("Sandbox Catalog")]
  node_metrics["Metrics Collection"]
end

node_operator(("User or Agent"))

node_operator -->|"runs commands"| node_cli
node_operator -->|"embeds runtime"| node_sdk
node_cli -.->|"issues requests"| node_control_clients
node_sdk -.->|"controls sandboxes"| node_control_clients
node_control_clients -.->|"uses framed transport"| node_protocol_clients
node_protocol_clients -.->|"sends requests"| node_control_server
node_control_server -->|"dispatches sessions"| node_dispatcher
node_dispatcher -->|"routes requests"| node_handler
node_handler -->|"executes operations"| node_executor
node_executor -.->|"controls runtime"| node_runtime_client
node_runtime_client -.->|"starts workloads"| node_runner
node_runner -.->|"runs guest agent"| node_agent
node_agent -.->|"exchanges messages"| node_protocol
node_runner -.->|"mounts filesystems"| node_filesystem
node_runner -.->|"configures networking"| node_network
node_cli -->|"pulls images"| node_image
node_image -.->|"builds root filesystems"| node_rootfs
node_cli -->|"saves or restores"| node_checkpoint
node_executor -.->|"coordinates snapshots"| node_checkpoint
node_executor -.->|"updates sandbox state"| node_database
node_runner -.->|"provides runtime samples"| node_metrics

click node_cli "https://github.com/superradcompany/microsandbox/tree/main/crates/cli/lib/commands"
click node_sdk "https://github.com/superradcompany/microsandbox/tree/main/sdk"
click node_control_clients "https://github.com/superradcompany/microsandbox/tree/main/packages/control-client"
click node_protocol_clients "https://github.com/superradcompany/microsandbox/tree/main/packages/protocol-client"
click node_control_server "https://github.com/superradcompany/microsandbox/blob/main/crates/runtime/lib/runner/control/server.rs"
click node_dispatcher "https://github.com/superradcompany/microsandbox/blob/main/crates/runtime/lib/runner/control/dispatch.rs"
click node_handler "https://github.com/superradcompany/microsandbox/blob/main/crates/runtime/lib/runner/control/handler.rs"
click node_executor "https://github.com/superradcompany/microsandbox/blob/main/crates/runtime/lib/runner/control/executor.rs"
click node_runtime_client "https://github.com/superradcompany/microsandbox/tree/main/crates/runtime/lib/client"
click node_runner "https://github.com/superradcompany/microsandbox/tree/main/crates/runtime/lib/runner"
click node_agent "https://github.com/superradcompany/microsandbox/tree/main/crates/agentd/lib"
click node_protocol "https://github.com/superradcompany/microsandbox/tree/main/crates/protocol/lib"
click node_filesystem "https://github.com/superradcompany/microsandbox/tree/main/crates/filesystem/lib/backends"
click node_network "https://github.com/superradcompany/microsandbox/tree/main/crates/network/lib/engine"
click node_image "https://github.com/superradcompany/microsandbox/blob/main/crates/image/lib/registry/client.rs"
click node_rootfs "https://github.com/superradcompany/microsandbox/blob/main/crates/image/lib/ext4/formatter.rs"
click node_checkpoint "https://github.com/superradcompany/microsandbox/tree/main/crates/runtime/lib/checkpoint"
click node_database "https://github.com/superradcompany/microsandbox/tree/main/crates/db/lib"
click node_metrics "https://github.com/superradcompany/microsandbox/tree/main/crates/metrics-collector/lib/core"

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_cli,node_sdk,node_control_clients,node_protocol_clients,node_operator toneBlue
class node_control_server,node_dispatcher,node_handler,node_executor,node_runtime_client toneAmber
class node_runner,node_agent,node_protocol,node_filesystem,node_network toneMint
class node_image,node_rootfs,node_checkpoint toneRose
class node_database,node_metrics toneIndigo
```

## Components

### User Interfaces

- [CLI Commands](https://github.com/superradcompany/microsandbox/tree/main/crates/cli/lib/commands): `crates/cli/lib/commands`
- [Language SDKs](https://github.com/superradcompany/microsandbox/tree/main/sdk): `sdk`
- [Control Clients](https://github.com/superradcompany/microsandbox/tree/main/packages/control-client): `packages/control-client`
- [Protocol Clients](https://github.com/superradcompany/microsandbox/tree/main/packages/protocol-client): `packages/protocol-client`

### Control Plane

- [Control Server](https://github.com/superradcompany/microsandbox/blob/main/crates/runtime/lib/runner/control/server.rs): `crates/runtime/lib/runner/control/server.rs`
- [Request Dispatcher](https://github.com/superradcompany/microsandbox/blob/main/crates/runtime/lib/runner/control/dispatch.rs): `crates/runtime/lib/runner/control/dispatch.rs`
- [Operation Handler](https://github.com/superradcompany/microsandbox/blob/main/crates/runtime/lib/runner/control/handler.rs): `crates/runtime/lib/runner/control/handler.rs`
- [Operation Executor](https://github.com/superradcompany/microsandbox/blob/main/crates/runtime/lib/runner/control/executor.rs): `crates/runtime/lib/runner/control/executor.rs`
- [Runtime Client](https://github.com/superradcompany/microsandbox/tree/main/crates/runtime/lib/client): `crates/runtime/lib/client`

### Sandbox Execution

- [VM Runner](https://github.com/superradcompany/microsandbox/tree/main/crates/runtime/lib/runner): `crates/runtime/lib/runner`
- [Guest Agent](https://github.com/superradcompany/microsandbox/tree/main/crates/agentd/lib): `crates/agentd/lib`
- [Agent Protocol](https://github.com/superradcompany/microsandbox/tree/main/crates/protocol/lib): `crates/protocol/lib`
- [Filesystem Backends](https://github.com/superradcompany/microsandbox/tree/main/crates/filesystem/lib/backends): `crates/filesystem/lib/backends`
- [Network Engine](https://github.com/superradcompany/microsandbox/tree/main/crates/network/lib/engine): `crates/network/lib/engine`

### Images and Snapshots

- [OCI Image Handling](https://github.com/superradcompany/microsandbox/blob/main/crates/image/lib/registry/client.rs): `crates/image/lib/registry/client.rs`
- [Root Filesystem Images](https://github.com/superradcompany/microsandbox/blob/main/crates/image/lib/ext4/formatter.rs): `crates/image/lib/ext4/formatter.rs`
- [Checkpoint and Restore](https://github.com/superradcompany/microsandbox/tree/main/crates/runtime/lib/checkpoint): `crates/runtime/lib/checkpoint`

### Host Services

- [Sandbox Catalog](https://github.com/superradcompany/microsandbox/tree/main/crates/db/lib): `crates/db/lib`
- [Metrics Collection](https://github.com/superradcompany/microsandbox/tree/main/crates/metrics-collector/lib/core): `crates/metrics-collector/lib/core`

### Other components

- **User or Agent**

## Connections

- 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 (evidence: `packages/control-client/typescript/src/json-client.ts`)
- Protocol Clients → Control Server: sends requests
- Control Server → Request Dispatcher: dispatches sessions (evidence: `crates/runtime/lib/runner/control/server.rs`)
- Request Dispatcher → Operation Handler: routes requests (evidence: `crates/runtime/lib/runner/control/dispatch.rs`)
- Operation Handler → Operation Executor: executes operations (evidence: `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