# unixshells/clone architecture

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

- Interactive diagram: https://gitdiagram.com/unixshells/clone
- Repository: https://github.com/unixshells/clone

## Overview

#### Purpose and Entry Points
Clone is a Linux/KVM virtual-machine monitor optimized for high-density, isolated workloads. It cold-boots templates, snapshots them, then forks copy-on-write VM instances using Shadow Clone memory mappings. The primary CLI and single-binary entry point is `src/main.rs`; VM runtime orchestration begins in `src/vmm/mod.rs`. Supporting in-guest binaries are `crates/guest-agent/src/main.rs` and `crates/clone-init/src/main.rs`.

#### VM Boot and Hardware Model
The VMM constructs guest memory, KVM state, vCPU threads, MMIO devices, serial I/O, and lifecycle state in `src/vmm/mod.rs`, `src/vmm/vcpu.rs`, and `src/vmm/serial.rs`. Boot preparation loads kernel/initrd images, builds guest page tables and ACPI metadata, and optionally verifies measured boot hashes through `src/boot/mod.rs`, `src/boot/acpi.rs`, and `src/boot/measured.rs`.

#### Snapshot, Shadow Fork, and Migration
Template snapshots capture memory and CPU/register state; forked VMs map snapshot memory privately so pages diverge only on write. Template identity and fork-specific guest state are handled by `src/boot/template.rs` and `src/boot/identity.rs`, with lifecycle coordination in `src/vmm/mod.rs`. Pre-copy live migration transfers memory and final CPU state over TCP in `src/migration/mod.rs`, separating source and receiver command paths exposed by the CLI/control layer.

#### Memory Efficiency
Guest memory management combines sparse/overcommitted allocation, cross-VM KSM eligibility, split regions around x86 PCI MMIO space, and virtio-balloon reclamation. These mechanisms reside in `src/memory/mod.rs`, `src/memory/overcommit.rs`, and `src/memory/balloon.rs`; guest-facing balloon transport is `src/virtio/balloon.rs`. This is the central boundary between guest-visible RAM and host physical-memory consumption.

#### Devices, Storage, and Host Integration
Virtio transports provide block, networking, filesystem sharing, vsock, and balloon devices through `src/virtio/mod.rs`, `src/virtio/mmio.rs`, and `src/virtio/queue.rs`. Backends include raw/qcow2 disks in `src/storage/mod.rs` and `src/storage/qcow2.rs`, TAP/bridge/NAT host networking in `src/net/mod.rs`, and inline virtio-fs in `src/virtio/fs.rs`. PCI ECAM and VFIO passthrough are implemented in `src/pci/mod.rs` and `src/pci/vfio.rs`, requiring host devices bound to `vfio-pci`.

#### Control Plane and Guest Communication
The CLI supports direct per-VM operation and a multi-VM daemon. Unix-socket protocol, daemon orchestration, synchronization server, metrics, and optional jailer are grouped in `src/control/protocol.rs`, `src/control/daemon.rs`, and `src/control/jailer.rs`. Host-to-guest exec, heartbeat, shutdown, and post-fork recovery cross userspace vsock via `src/vmm/agent_listener.rs`, `src/virtio/vsock.rs`, and `crates/guest-agent/src/main.rs`.

#### Root Filesystems and Runtime Boundaries
`src/rootfs.rs` creates boot plumbing for disk-rootfs mode, including the minimal init and agent; `src/rootfs_create.rs` builds/imports Alpine, Ubuntu, Debian, and Docker-derived images. The VMM runs on Linux with `/dev/kvm`; networking needs `/dev/net/tun`, while KVM, Linux memory APIs, namespaces/capabilities, seccomp BPF, and VFIO are material host-kernel dependencies. The project intentionally has no libvirt, QEMU, or external virtiofs daemon dependency.

Main entry points: [`src/vmm/mod.rs`](https://github.com/unixshells/clone/blob/master/src/vmm/mod.rs) (VMM lifecycle), [`src/virtio/mod.rs`](https://github.com/unixshells/clone/blob/master/src/virtio/mod.rs) (Virtio transport), [`src/memory/mod.rs`](https://github.com/unixshells/clone/blob/master/src/memory/mod.rs) (Guest memory), [`src/main.rs`](https://github.com/unixshells/clone/blob/master/src/main.rs) (Clone CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry & Control"]
  node_cli["Clone CLI<br/>Rust binary<br/>[main.rs]"]
  node_control["Control plane<br/>daemon protocol<br/>[daemon.rs]"]
end

subgraph group_runtime["VMM Runtime"]
  node_vmm["VMM lifecycle<br/>KVM orchestrator<br/>[mod.rs]"]
  node_vcpu["vCPU threads<br/>KVM execution<br/>[vcpu.rs]"]
  node_boot["Boot preparation<br/>guest boot builder<br/>[mod.rs]"]
  node_measured["Measured boot<br/>hash verification<br/>[measured.rs]"]
  node_template["Templates &amp; identity<br/>snapshot metadata<br/>[template.rs]"]
  node_memory["Guest memory<br/>memory manager<br/>[mod.rs]"]
  node_balloon["Memory reclamation<br/>balloon manager<br/>[balloon.rs]"]
  node_migration["Live migration<br/>TCP pre-copy<br/>[mod.rs]"]
  node_virtio["Virtio transport<br/>MMIO device bus<br/>[mod.rs]"]
  node_agent_listener["Agent listener<br/>vsock control<br/>[agent_listener.rs]"]
end

subgraph group_guest["Guest Runtime"]
  node_guest_agent["Guest agent<br/>in-guest binary<br/>[main.rs]"]
  node_rootfs["Rootfs builder<br/>image provisioning<br/>[rootfs_create.rs]"]
end

subgraph group_host["Host Services"]
  node_storage[("Disk backends<br/>raw/qcow2 storage<br/>[mod.rs]")]
  node_network["Host networking<br/>TAP/bridge/NAT<br/>[mod.rs]"]
  node_pci["PCI &amp; VFIO<br/>passthrough<br/>[mod.rs]"]
  node_linux{{"Linux host kernel<br/>kernel interfaces"}}
end

node_cli -->|"daemon commands"| node_control
node_cli -->|"direct VM commands"| node_vmm
node_control -->|"manages VMs"| node_vmm
node_vmm -->|"starts"| node_vcpu
node_vmm -->|"prepares boot"| node_boot
node_boot -.->|"optionally verifies"| node_measured
node_vmm -->|"snapshots and forks"| node_template
node_template -->|"private COW mappings"| node_memory
node_vmm -->|"creates guest RAM"| node_memory
node_memory -->|"reclaims pages"| node_balloon
node_vmm -->|"source/receiver lifecycle"| node_migration
node_vmm -->|"attaches devices"| node_virtio
node_virtio -->|"block I/O"| node_storage
node_virtio -->|"network I/O"| node_network
node_virtio -->|"balloon transport"| node_balloon
node_vmm -->|"PCI and passthrough"| node_pci
node_agent_listener -->|"userspace vsock"| node_guest_agent
node_vmm -->|"guest control"| node_agent_listener
node_rootfs -->|"installs agent"| node_guest_agent
node_vmm -->|"/dev/kvm and host APIs"| node_linux
node_memory -->|"host memory APIs"| node_linux
node_network -->|"/dev/net/tun"| node_linux
node_pci -->|"VFIO"| node_linux

click node_cli "https://github.com/unixshells/clone/blob/master/src/main.rs"
click node_control "https://github.com/unixshells/clone/blob/master/src/control/daemon.rs"
click node_vmm "https://github.com/unixshells/clone/blob/master/src/vmm/mod.rs"
click node_vcpu "https://github.com/unixshells/clone/blob/master/src/vmm/vcpu.rs"
click node_boot "https://github.com/unixshells/clone/blob/master/src/boot/mod.rs"
click node_measured "https://github.com/unixshells/clone/blob/master/src/boot/measured.rs"
click node_template "https://github.com/unixshells/clone/blob/master/src/boot/template.rs"
click node_memory "https://github.com/unixshells/clone/blob/master/src/memory/mod.rs"
click node_balloon "https://github.com/unixshells/clone/blob/master/src/memory/balloon.rs"
click node_migration "https://github.com/unixshells/clone/blob/master/src/migration/mod.rs"
click node_virtio "https://github.com/unixshells/clone/blob/master/src/virtio/mod.rs"
click node_storage "https://github.com/unixshells/clone/blob/master/src/storage/mod.rs"
click node_network "https://github.com/unixshells/clone/blob/master/src/net/mod.rs"
click node_pci "https://github.com/unixshells/clone/blob/master/src/pci/mod.rs"
click node_agent_listener "https://github.com/unixshells/clone/blob/master/src/vmm/agent_listener.rs"
click node_guest_agent "https://github.com/unixshells/clone/blob/master/crates/guest-agent/src/main.rs"
click node_rootfs "https://github.com/unixshells/clone/blob/master/src/rootfs_create.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_cli,node_control toneBlue
class node_vmm,node_vcpu,node_boot,node_measured,node_template,node_memory,node_balloon,node_migration,node_virtio,node_agent_listener toneAmber
class node_guest_agent,node_rootfs toneMint
class node_storage,node_network,node_pci,node_linux toneRose
```

## Components

### Entry & Control

- [Clone CLI](https://github.com/unixshells/clone/blob/master/src/main.rs): Rust binary · Single-binary VM and daemon command entry point. · `src/main.rs`
- [Control plane](https://github.com/unixshells/clone/blob/master/src/control/daemon.rs): daemon protocol · Unix-socket commands, multi-VM orchestration, metrics, and jailer. · `src/control/daemon.rs`

### VMM Runtime

- [VMM lifecycle](https://github.com/unixshells/clone/blob/master/src/vmm/mod.rs): KVM orchestrator · Coordinates boot, templates, forks, devices, and VM lifecycle. · `src/vmm/mod.rs`
- [vCPU threads](https://github.com/unixshells/clone/blob/master/src/vmm/vcpu.rs): KVM execution · `src/vmm/vcpu.rs`
- [Boot preparation](https://github.com/unixshells/clone/blob/master/src/boot/mod.rs): guest boot builder · Loads images and creates page tables and ACPI metadata. · `src/boot/mod.rs`
- [Measured boot](https://github.com/unixshells/clone/blob/master/src/boot/measured.rs): hash verification · `src/boot/measured.rs`
- [Templates & identity](https://github.com/unixshells/clone/blob/master/src/boot/template.rs): snapshot metadata · Captures template identity and fork-specific guest state. · `src/boot/template.rs`
- [Guest memory](https://github.com/unixshells/clone/blob/master/src/memory/mod.rs): memory manager · Sparse allocation, overcommit, KSM eligibility, and PCI-MMIO splits. · `src/memory/mod.rs`
- [Memory reclamation](https://github.com/unixshells/clone/blob/master/src/memory/balloon.rs): balloon manager · `src/memory/balloon.rs`
- [Live migration](https://github.com/unixshells/clone/blob/master/src/migration/mod.rs): TCP pre-copy · Transfers memory followed by final CPU state. · `src/migration/mod.rs`
- [Virtio transport](https://github.com/unixshells/clone/blob/master/src/virtio/mod.rs): MMIO device bus · Provides block, network, filesystem, vsock, and balloon devices. · `src/virtio/mod.rs`
- [Agent listener](https://github.com/unixshells/clone/blob/master/src/vmm/agent_listener.rs): vsock control · Relays exec, heartbeat, shutdown, and recovery commands. · `src/vmm/agent_listener.rs`

### Guest Runtime

- [Guest agent](https://github.com/unixshells/clone/blob/master/crates/guest-agent/src/main.rs): in-guest binary · `crates/guest-agent/src/main.rs`
- [Rootfs builder](https://github.com/unixshells/clone/blob/master/src/rootfs_create.rs): image provisioning · Builds or imports Linux root filesystem images. · `src/rootfs_create.rs`

### Host Services

- [Disk backends](https://github.com/unixshells/clone/blob/master/src/storage/mod.rs): raw/qcow2 storage · `src/storage/mod.rs`
- [Host networking](https://github.com/unixshells/clone/blob/master/src/net/mod.rs): TAP/bridge/NAT · `src/net/mod.rs`
- [PCI & VFIO](https://github.com/unixshells/clone/blob/master/src/pci/mod.rs): passthrough · ECAM model and vfio-pci device passthrough. · `src/pci/mod.rs`
- **Linux host kernel**: kernel interfaces · Supplies KVM, memory APIs, TUN, namespaces, seccomp, and VFIO.

## Connections

- Clone CLI → Control plane: daemon commands
- Clone CLI → VMM lifecycle: direct VM commands
- Control plane → VMM lifecycle: manages VMs
- VMM lifecycle → vCPU threads: starts
- VMM lifecycle → Boot preparation: prepares boot
- Boot preparation → Measured boot: optionally verifies
- VMM lifecycle → Templates & identity: snapshots and forks
- Templates & identity → Guest memory: private COW mappings
- VMM lifecycle → Guest memory: creates guest RAM
- Guest memory → Memory reclamation: reclaims pages
- VMM lifecycle → Live migration: source/receiver lifecycle
- VMM lifecycle → Virtio transport: attaches devices
- Virtio transport → Disk backends: block I/O
- Virtio transport → Host networking: network I/O
- Virtio transport → Memory reclamation: balloon transport
- VMM lifecycle → PCI & VFIO: PCI and passthrough
- Agent listener → Guest agent: userspace vsock
- VMM lifecycle → Agent listener: guest control
- Rootfs builder → Guest agent: installs agent
- VMM lifecycle → Linux host kernel: /dev/kvm and host APIs
- Guest memory → Linux host kernel: host memory APIs
- Host networking → Linux host kernel: /dev/net/tun
- PCI & VFIO → Linux host kernel: VFIO