# zerobootdev/zeroboot architecture

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

- Interactive diagram: https://gitdiagram.com/zerobootdev/zeroboot
- Repository: https://github.com/zerobootdev/zeroboot

## Overview

Zeroboot provides isolated code execution by forking copy-on-write KVM VMs restored from Firecracker snapshots. The main workflow is client SDK → HTTP execution API → template selection and VM fork → serial command execution in the guest → captured result; the API also offers batch execution, authentication/rate limiting, health and metrics endpoints. A separate template workflow boots and snapshots a VM. The graph reflects sampled calls and README-documented capabilities; unsampled handler details and TypeScript transport are not inferred.

Main entry points: [`src/api/handlers.rs`](https://github.com/zerobootdev/zeroboot/blob/main/src/api/handlers.rs) (Execution handlers), [`src/main.rs`](https://github.com/zerobootdev/zeroboot/blob/main/src/main.rs) (HTTP API server), [`src/vmm/kvm.rs`](https://github.com/zerobootdev/zeroboot/blob/main/src/vmm/kvm.rs) (KVM CoW fork), [`src/vmm/firecracker.rs`](https://github.com/zerobootdev/zeroboot/blob/main/src/vmm/firecracker.rs) (Firecracker boot and snapshot)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Client SDKs"]
  node_python_sdk["Python SDK<br/>[client.py]"]
  node_node_sdk["TypeScript SDK<br/>[index.ts]"]
end

subgraph group_service["Execution API"]
  node_http_api["HTTP API server<br/>[main.rs]"]
  node_exec_handlers["Execution handlers<br/>[handlers.rs]"]
  node_auth_limits["Auth and limits<br/>[handlers.rs]"]
  node_batch_exec["Batch execution<br/>[handlers.rs]"]
  node_telemetry["Metrics and logs<br/>[handlers.rs]"]
end

subgraph group_templates["Template lifecycle"]
  node_template_cmd["Template creation<br/>[main.rs]"]
  node_firecracker["Firecracker boot and snapshot<br/>[firecracker.rs]"]
  node_snapshot_files["Snapshot files"]
end

subgraph group_runtime["VM runtime"]
  node_vmstate_parse["VM state parser<br/>[vmstate.rs]"]
  node_cow_fork["KVM CoW fork<br/>[kvm.rs]"]
  node_uart["UART emulation<br/>[serial.rs]"]
end

subgraph group_guest["Guest execution"]
  node_guest_agent["Guest command agent<br/>[init.c]"]
end

node_agent(("Agent or caller"))
node_firecracker_service["Firecracker process"]
node_kvm_host["Linux KVM"]

node_agent -->|"calls"| node_python_sdk
node_agent -->|"calls"| node_node_sdk
node_python_sdk -->|"posts execution"| node_http_api
node_node_sdk -.->|"uses API"| node_http_api
node_http_api -->|"routes requests"| node_exec_handlers
node_http_api -->|"routes batch"| node_batch_exec
node_http_api -->|"routes metrics"| node_telemetry
node_exec_handlers -->|"checks access"| node_auth_limits
node_exec_handlers -->|"forks template"| node_cow_fork
node_exec_handlers -->|"records metrics"| node_telemetry
node_batch_exec -.->|"executes items"| node_exec_handlers
node_template_cmd -->|"creates snapshot"| node_firecracker
node_firecracker -->|"configures and boots"| node_firecracker_service
node_firecracker -->|"writes snapshot"| node_snapshot_files
node_template_cmd -->|"loads state"| node_vmstate_parse
node_vmstate_parse -.->|"provides VM state"| node_cow_fork
node_cow_fork -->|"maps memory"| node_snapshot_files
node_cow_fork -->|"creates VM"| node_kvm_host
node_cow_fork -->|"handles UART I/O"| node_uart
node_uart -->|"carries serial I/O"| node_guest_agent
node_exec_handlers -.->|"sends commands"| node_uart

click node_python_sdk "https://github.com/zerobootdev/zeroboot/blob/main/sdk/python/zeroboot/client.py"
click node_node_sdk "https://github.com/zerobootdev/zeroboot/blob/main/sdk/node/src/index.ts"
click node_http_api "https://github.com/zerobootdev/zeroboot/blob/main/src/main.rs"
click node_exec_handlers "https://github.com/zerobootdev/zeroboot/blob/main/src/api/handlers.rs"
click node_auth_limits "https://github.com/zerobootdev/zeroboot/blob/main/src/api/handlers.rs"
click node_batch_exec "https://github.com/zerobootdev/zeroboot/blob/main/src/api/handlers.rs"
click node_telemetry "https://github.com/zerobootdev/zeroboot/blob/main/src/api/handlers.rs"
click node_template_cmd "https://github.com/zerobootdev/zeroboot/blob/main/src/main.rs"
click node_firecracker "https://github.com/zerobootdev/zeroboot/blob/main/src/vmm/firecracker.rs"
click node_vmstate_parse "https://github.com/zerobootdev/zeroboot/blob/main/src/vmm/vmstate.rs"
click node_cow_fork "https://github.com/zerobootdev/zeroboot/blob/main/src/vmm/kvm.rs"
click node_uart "https://github.com/zerobootdev/zeroboot/blob/main/src/vmm/serial.rs"
click node_guest_agent "https://github.com/zerobootdev/zeroboot/blob/main/guest/init.c"

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_python_sdk,node_node_sdk toneBlue
class node_http_api,node_exec_handlers,node_auth_limits,node_batch_exec,node_telemetry toneAmber
class node_template_cmd,node_firecracker,node_snapshot_files toneMint
class node_vmstate_parse,node_cow_fork,node_uart toneRose
class node_guest_agent,node_agent,node_firecracker_service,node_kvm_host toneIndigo
```

## Components

### Client SDKs

- [Python SDK](https://github.com/zerobootdev/zeroboot/blob/main/sdk/python/zeroboot/client.py): `sdk/python/zeroboot/client.py`
- [TypeScript SDK](https://github.com/zerobootdev/zeroboot/blob/main/sdk/node/src/index.ts): `sdk/node/src/index.ts`

### Execution API

- [HTTP API server](https://github.com/zerobootdev/zeroboot/blob/main/src/main.rs): `src/main.rs`
- [Execution handlers](https://github.com/zerobootdev/zeroboot/blob/main/src/api/handlers.rs): `src/api/handlers.rs`
- [Auth and limits](https://github.com/zerobootdev/zeroboot/blob/main/src/api/handlers.rs): `src/api/handlers.rs`
- [Batch execution](https://github.com/zerobootdev/zeroboot/blob/main/src/api/handlers.rs): `src/api/handlers.rs`
- [Metrics and logs](https://github.com/zerobootdev/zeroboot/blob/main/src/api/handlers.rs): `src/api/handlers.rs`

### Template lifecycle

- [Template creation](https://github.com/zerobootdev/zeroboot/blob/main/src/main.rs): `src/main.rs`
- [Firecracker boot and snapshot](https://github.com/zerobootdev/zeroboot/blob/main/src/vmm/firecracker.rs): `src/vmm/firecracker.rs`
- **Snapshot files**

### VM runtime

- [VM state parser](https://github.com/zerobootdev/zeroboot/blob/main/src/vmm/vmstate.rs): `src/vmm/vmstate.rs`
- [KVM CoW fork](https://github.com/zerobootdev/zeroboot/blob/main/src/vmm/kvm.rs): `src/vmm/kvm.rs`
- [UART emulation](https://github.com/zerobootdev/zeroboot/blob/main/src/vmm/serial.rs): `src/vmm/serial.rs`

### Guest execution

- [Guest command agent](https://github.com/zerobootdev/zeroboot/blob/main/guest/init.c): `guest/init.c`

### Other components

- **Agent or caller**
- **Firecracker process**
- **Linux KVM**

## Connections

- Agent or caller → Python SDK: calls (evidence: `README.md`)
- Agent or caller → TypeScript SDK: calls (evidence: `README.md`)
- Python SDK → HTTP API server: posts execution (evidence: `sdk/python/zeroboot/client.py`)
- TypeScript SDK → HTTP API server: uses API (evidence: `README.md`)
- HTTP API server → Execution handlers: routes requests (evidence: `src/main.rs`)
- HTTP API server → Batch execution: routes batch (evidence: `src/main.rs`)
- HTTP API server → Metrics and logs: routes metrics (evidence: `src/main.rs`)
- Execution handlers → Auth and limits: checks access (evidence: `src/api/handlers.rs`)
- Execution handlers → KVM CoW fork: forks template (evidence: `src/api/handlers.rs`)
- Execution handlers → Metrics and logs: records metrics (evidence: `src/api/handlers.rs`)
- Batch execution → Execution handlers: executes items (evidence: `src/api/handlers.rs`)
- Template creation → Firecracker boot and snapshot: creates snapshot (evidence: `src/main.rs`)
- Firecracker boot and snapshot → Firecracker process: configures and boots (evidence: `src/vmm/firecracker.rs`)
- Firecracker boot and snapshot → Snapshot files: writes snapshot (evidence: `src/vmm/firecracker.rs`)
- Template creation → VM state parser: loads state (evidence: `src/main.rs`)
- VM state parser → KVM CoW fork: provides VM state
- KVM CoW fork → Snapshot files: maps memory (evidence: `README.md`)
- KVM CoW fork → Linux KVM: creates VM (evidence: `src/vmm/kvm.rs`)
- KVM CoW fork → UART emulation: handles UART I/O (evidence: `src/vmm/kvm.rs`)
- UART emulation → Guest command agent: carries serial I/O (evidence: `README.md`)
- Execution handlers → UART emulation: sends commands