# sallespro/litebox architecture

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

- Interactive diagram: https://gitdiagram.com/sallespro/litebox
- Repository: https://github.com/sallespro/litebox

## Overview

LiteBox is a security-focused library OS: a North-side ABI shim pairs with a South-side platform to run guest programs while reducing their direct host interface. A representative workflow is an unmodified Linux program entering the Linux shim, using LiteBox services, and executing through a selected platform; runners configure concrete combinations. The workspace also includes Windows and OP-TEE shims, multiple platform implementations, and broker components. The graph preserves documented capabilities and indexed core modules; unsampled subsystem internals and connections are shown only where the README or source index supports them.

Main entry points: [`litebox_shim_linux/src/lib.rs`](https://github.com/sallespro/litebox/blob/main/litebox_shim_linux/src/lib.rs) (Linux shim), [`litebox_platform_macos_userland/src/lib.rs`](https://github.com/sallespro/litebox/blob/main/litebox_platform_macos_userland/src/lib.rs) (macOS platform), [`litebox_platform_macos_userland/src/hvf_backend.rs`](https://github.com/sallespro/litebox/blob/main/litebox_platform_macos_userland/src/hvf_backend.rs) (HVF backend), [`litebox_common_linux/src/lib.rs`](https://github.com/sallespro/litebox/blob/main/litebox_common_linux/src/lib.rs) (Linux ABI types)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_north["Guest interfaces"]
  node_linux_shim["Linux shim<br/>[lib.rs]"]
  node_linux_file["Linux file calls<br/>[file.rs]"]
  node_linux_process["Linux process calls<br/>[process.rs]"]
  node_windows_shim["Windows shim<br/>[lib.rs]"]
  node_windows_section["Windows sections<br/>[section.rs]"]
  node_optee_shim["OP-TEE shim<br/>[lib.rs]"]
end

subgraph group_core["LiteBox core"]
  node_litebox_core["LiteBox services<br/>[lib.rs]"]
  node_common_linux["Linux ABI types<br/>[lib.rs]"]
  node_linux_memory["Linux memory support<br/>[mm.rs]"]
  node_physical_ptrs["Physical pointers"]
  node_virtual_map["Virtual mapping<br/>[vmap.rs]"]
  node_broker["Broker services<br/>[lib.rs]"]
end

subgraph group_south["Execution platforms"]
  node_mac_platform["macOS platform<br/>[lib.rs]"]
  node_mac_guest["Guest management<br/>[guest.rs]"]
  node_darwin["Darwin bindings<br/>[darwin.rs]"]
  node_hvf_backend["HVF backend<br/>[hvf_backend.rs]"]
  node_hvf_probe["HVF probe<br/>[hvf.rs]"]
  node_hvf_memory["HVF memory<br/>[hvf_memory.rs]"]
  node_hvf_vcpu["HVF vCPU<br/>[hvf_vcpu.rs]"]
  node_hvf_counters["HVF counters"]
  node_mac_vdso["macOS vDSO<br/>[vdso.rs]"]
  node_linux_platform["Linux platforms<br/>[lib.rs]"]
  node_lvbs_platform["LVBS platform<br/>[lib.rs]"]
  node_snp_platform["SEV-SNP platform<br/>[lib.rs]"]
end

subgraph group_runtime["Runners and brokers"]
  node_runner["Platform runners<br/>[main.rs]"]
  node_broker_userland["Broker process<br/>[main.rs]"]
end

node_program(("Guest program"))

node_program -->|"issues Linux calls"| node_linux_shim
node_linux_shim -->|"uses services"| node_litebox_core
node_linux_shim -->|"dispatches file calls"| node_linux_file
node_linux_shim -->|"dispatches process calls"| node_linux_process
node_linux_shim -.->|"uses ABI types"| node_common_linux
node_windows_shim -->|"uses section calls"| node_windows_section
node_common_linux -->|"defines memory support"| node_linux_memory
node_common_linux -->|"defines pointer support"| node_physical_ptrs
node_common_linux -->|"defines virtual mapping"| node_virtual_map
node_physical_ptrs -->|"referenced by"| node_virtual_map
node_virtual_map -->|"uses"| node_linux_memory
node_physical_ptrs -->|"uses"| node_virtual_map
node_linux_shim -->|"pairs with"| node_mac_platform
node_linux_shim -->|"pairs with"| node_linux_platform
node_linux_shim -->|"pairs with"| node_lvbs_platform
node_linux_shim -->|"pairs with"| node_snp_platform
node_optee_shim -->|"runs on"| node_linux_platform
node_runner -.->|"configures"| node_linux_shim
node_mac_platform -->|"uses bindings"| node_darwin
node_mac_platform -->|"uses guest manager"| node_mac_guest
node_mac_platform -->|"uses backend"| node_hvf_backend
node_mac_platform -->|"uses probe"| node_hvf_probe
node_mac_platform -->|"uses memory support"| node_hvf_memory
node_mac_platform -->|"uses vCPU support"| node_hvf_vcpu
node_mac_platform -->|"uses counters"| node_hvf_counters
node_mac_platform -->|"uses vDSO support"| node_mac_vdso
node_hvf_backend -->|"references"| node_hvf_probe
node_hvf_backend -->|"uses memory support"| node_hvf_memory
node_hvf_backend -->|"uses vCPU support"| node_hvf_vcpu
node_hvf_backend -->|"uses counters"| node_hvf_counters
node_hvf_backend -->|"uses vDSO support"| node_mac_vdso
node_broker_userland -.->|"uses broker core"| node_broker

click node_linux_shim "https://github.com/sallespro/litebox/blob/main/litebox_shim_linux/src/lib.rs"
click node_linux_file "https://github.com/sallespro/litebox/blob/main/litebox_shim_linux/src/syscalls/file.rs"
click node_linux_process "https://github.com/sallespro/litebox/blob/main/litebox_shim_linux/src/syscalls/process.rs"
click node_windows_shim "https://github.com/sallespro/litebox/blob/main/litebox_shim_windows/src/lib.rs"
click node_windows_section "https://github.com/sallespro/litebox/blob/main/litebox_shim_windows/src/syscalls/section.rs"
click node_optee_shim "https://github.com/sallespro/litebox/blob/main/litebox_shim_optee/src/lib.rs"
click node_litebox_core "https://github.com/sallespro/litebox/blob/main/litebox/src/lib.rs"
click node_common_linux "https://github.com/sallespro/litebox/blob/main/litebox_common_linux/src/lib.rs"
click node_linux_memory "https://github.com/sallespro/litebox/blob/main/litebox_common_linux/src/mm.rs"
click node_physical_ptrs "https://github.com/sallespro/litebox/blob/main/litebox_common_linux/src/physical_pointers.rs"
click node_virtual_map "https://github.com/sallespro/litebox/blob/main/litebox_common_linux/src/vmap.rs"
click node_broker "https://github.com/sallespro/litebox/blob/main/litebox_broker_core/src/lib.rs"
click node_mac_platform "https://github.com/sallespro/litebox/blob/main/litebox_platform_macos_userland/src/lib.rs"
click node_mac_guest "https://github.com/sallespro/litebox/blob/main/litebox_platform_macos_userland/src/guest.rs"
click node_darwin "https://github.com/sallespro/litebox/blob/main/litebox_platform_macos_userland/src/darwin.rs"
click node_hvf_backend "https://github.com/sallespro/litebox/blob/main/litebox_platform_macos_userland/src/hvf_backend.rs"
click node_hvf_probe "https://github.com/sallespro/litebox/blob/main/litebox_platform_macos_userland/src/hvf.rs"
click node_hvf_memory "https://github.com/sallespro/litebox/blob/main/litebox_platform_macos_userland/src/hvf_memory.rs"
click node_hvf_vcpu "https://github.com/sallespro/litebox/blob/main/litebox_platform_macos_userland/src/hvf_vcpu.rs"
click node_hvf_counters "https://github.com/sallespro/litebox/blob/main/litebox_platform_macos_userland/src/diagnostics_counters.rs"
click node_mac_vdso "https://github.com/sallespro/litebox/blob/main/litebox_platform_macos_userland/src/vdso.rs"
click node_linux_platform "https://github.com/sallespro/litebox/blob/main/litebox_platform_linux_userland/src/lib.rs"
click node_lvbs_platform "https://github.com/sallespro/litebox/blob/main/litebox_platform_lvbs/src/lib.rs"
click node_snp_platform "https://github.com/sallespro/litebox/blob/main/litebox_platform_linux_kernel/src/lib.rs"
click node_runner "https://github.com/sallespro/litebox/blob/main/litebox_runner_linux_on_macos_userland/src/main.rs"
click node_broker_userland "https://github.com/sallespro/litebox/blob/main/litebox_broker_userland/src/main.rs"

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_linux_shim,node_linux_file,node_linux_process,node_windows_shim,node_windows_section,node_optee_shim toneBlue
class node_litebox_core,node_common_linux,node_linux_memory,node_physical_ptrs,node_virtual_map,node_broker toneAmber
class node_mac_platform,node_mac_guest,node_darwin,node_hvf_backend,node_hvf_probe,node_hvf_memory,node_hvf_vcpu,node_hvf_counters,node_mac_vdso,node_linux_platform,node_lvbs_platform,node_snp_platform toneMint
class node_runner,node_broker_userland toneRose
class node_program toneIndigo
```

## Components

### Guest interfaces

- [Linux shim](https://github.com/sallespro/litebox/blob/main/litebox_shim_linux/src/lib.rs): `litebox_shim_linux/src/lib.rs`
- [Linux file calls](https://github.com/sallespro/litebox/blob/main/litebox_shim_linux/src/syscalls/file.rs): `litebox_shim_linux/src/syscalls/file.rs`
- [Linux process calls](https://github.com/sallespro/litebox/blob/main/litebox_shim_linux/src/syscalls/process.rs): `litebox_shim_linux/src/syscalls/process.rs`
- [Windows shim](https://github.com/sallespro/litebox/blob/main/litebox_shim_windows/src/lib.rs): `litebox_shim_windows/src/lib.rs`
- [Windows sections](https://github.com/sallespro/litebox/blob/main/litebox_shim_windows/src/syscalls/section.rs): `litebox_shim_windows/src/syscalls/section.rs`
- [OP-TEE shim](https://github.com/sallespro/litebox/blob/main/litebox_shim_optee/src/lib.rs): `litebox_shim_optee/src/lib.rs`

### LiteBox core

- [LiteBox services](https://github.com/sallespro/litebox/blob/main/litebox/src/lib.rs): `litebox/src/lib.rs`
- [Linux ABI types](https://github.com/sallespro/litebox/blob/main/litebox_common_linux/src/lib.rs): `litebox_common_linux/src/lib.rs`
- [Linux memory support](https://github.com/sallespro/litebox/blob/main/litebox_common_linux/src/mm.rs): `litebox_common_linux/src/mm.rs`
- [Physical pointers](https://github.com/sallespro/litebox/blob/main/litebox_common_linux/src/physical_pointers.rs): `litebox_common_linux/src/physical_pointers.rs`
- [Virtual mapping](https://github.com/sallespro/litebox/blob/main/litebox_common_linux/src/vmap.rs): `litebox_common_linux/src/vmap.rs`
- [Broker services](https://github.com/sallespro/litebox/blob/main/litebox_broker_core/src/lib.rs): `litebox_broker_core/src/lib.rs`

### Execution platforms

- [macOS platform](https://github.com/sallespro/litebox/blob/main/litebox_platform_macos_userland/src/lib.rs): `litebox_platform_macos_userland/src/lib.rs`
- [Guest management](https://github.com/sallespro/litebox/blob/main/litebox_platform_macos_userland/src/guest.rs): `litebox_platform_macos_userland/src/guest.rs`
- [Darwin bindings](https://github.com/sallespro/litebox/blob/main/litebox_platform_macos_userland/src/darwin.rs): `litebox_platform_macos_userland/src/darwin.rs`
- [HVF backend](https://github.com/sallespro/litebox/blob/main/litebox_platform_macos_userland/src/hvf_backend.rs): `litebox_platform_macos_userland/src/hvf_backend.rs`
- [HVF probe](https://github.com/sallespro/litebox/blob/main/litebox_platform_macos_userland/src/hvf.rs): `litebox_platform_macos_userland/src/hvf.rs`
- [HVF memory](https://github.com/sallespro/litebox/blob/main/litebox_platform_macos_userland/src/hvf_memory.rs): `litebox_platform_macos_userland/src/hvf_memory.rs`
- [HVF vCPU](https://github.com/sallespro/litebox/blob/main/litebox_platform_macos_userland/src/hvf_vcpu.rs): `litebox_platform_macos_userland/src/hvf_vcpu.rs`
- [HVF counters](https://github.com/sallespro/litebox/blob/main/litebox_platform_macos_userland/src/diagnostics_counters.rs): `litebox_platform_macos_userland/src/diagnostics_counters.rs`
- [macOS vDSO](https://github.com/sallespro/litebox/blob/main/litebox_platform_macos_userland/src/vdso.rs): `litebox_platform_macos_userland/src/vdso.rs`
- [Linux platforms](https://github.com/sallespro/litebox/blob/main/litebox_platform_linux_userland/src/lib.rs): `litebox_platform_linux_userland/src/lib.rs`
- [LVBS platform](https://github.com/sallespro/litebox/blob/main/litebox_platform_lvbs/src/lib.rs): `litebox_platform_lvbs/src/lib.rs`
- [SEV-SNP platform](https://github.com/sallespro/litebox/blob/main/litebox_platform_linux_kernel/src/lib.rs): `litebox_platform_linux_kernel/src/lib.rs`

### Runners and brokers

- [Platform runners](https://github.com/sallespro/litebox/blob/main/litebox_runner_linux_on_macos_userland/src/main.rs): `litebox_runner_linux_on_macos_userland/src/main.rs`
- [Broker process](https://github.com/sallespro/litebox/blob/main/litebox_broker_userland/src/main.rs): `litebox_broker_userland/src/main.rs`

### Other components

- **Guest program**

## Connections

- Guest program → Linux shim: issues Linux calls (evidence: `README.md`)
- Linux shim → LiteBox services: uses services (evidence: `README.md`)
- Linux shim → Linux file calls: dispatches file calls (evidence: `litebox_shim_linux/src/lib.rs`)
- Linux shim → Linux process calls: dispatches process calls (evidence: `litebox_shim_linux/src/lib.rs`)
- Linux shim → Linux ABI types: uses ABI types
- Windows shim → Windows sections: uses section calls
- Linux ABI types → Linux memory support: defines memory support (evidence: `litebox_common_linux/src/lib.rs`)
- Linux ABI types → Physical pointers: defines pointer support (evidence: `litebox_common_linux/src/lib.rs`)
- Linux ABI types → Virtual mapping: defines virtual mapping (evidence: `litebox_common_linux/src/lib.rs`)
- Physical pointers → Virtual mapping: referenced by (evidence: `litebox_common_linux/src/physical_pointers.rs`)
- Virtual mapping → Linux memory support: uses (evidence: `litebox_common_linux/src/vmap.rs`)
- Physical pointers → Virtual mapping: uses (evidence: `litebox_common_linux/src/physical_pointers.rs`)
- Linux shim → macOS platform: pairs with (evidence: `README.md`)
- Linux shim → Linux platforms: pairs with (evidence: `README.md`)
- Linux shim → LVBS platform: pairs with (evidence: `README.md`)
- Linux shim → SEV-SNP platform: pairs with (evidence: `README.md`)
- OP-TEE shim → Linux platforms: runs on (evidence: `README.md`)
- Platform runners → Linux shim: configures
- macOS platform → Darwin bindings: uses bindings (evidence: `litebox_platform_macos_userland/src/lib.rs`)
- macOS platform → Guest management: uses guest manager (evidence: `litebox_platform_macos_userland/src/lib.rs`)
- macOS platform → HVF backend: uses backend (evidence: `litebox_platform_macos_userland/src/lib.rs`)
- macOS platform → HVF probe: uses probe (evidence: `litebox_platform_macos_userland/src/lib.rs`)
- macOS platform → HVF memory: uses memory support (evidence: `litebox_platform_macos_userland/src/lib.rs`)
- macOS platform → HVF vCPU: uses vCPU support (evidence: `litebox_platform_macos_userland/src/lib.rs`)
- macOS platform → HVF counters: uses counters (evidence: `litebox_platform_macos_userland/src/lib.rs`)
- macOS platform → macOS vDSO: uses vDSO support (evidence: `litebox_platform_macos_userland/src/lib.rs`)
- HVF backend → HVF probe: references (evidence: `litebox_platform_macos_userland/src/hvf_backend.rs`)
- HVF backend → HVF memory: uses memory support (evidence: `litebox_platform_macos_userland/src/hvf_backend.rs`)
- HVF backend → HVF vCPU: uses vCPU support (evidence: `litebox_platform_macos_userland/src/hvf_backend.rs`)
- HVF backend → HVF counters: uses counters (evidence: `litebox_platform_macos_userland/src/hvf_backend.rs`)
- HVF backend → macOS vDSO: uses vDSO support (evidence: `litebox_platform_macos_userland/src/hvf_backend.rs`)
- Broker process → Broker services: uses broker core
