# shudza/claude-vm architecture

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

- Interactive diagram: https://gitdiagram.com/shudza/claude-vm
- Repository: https://github.com/shudza/claude-vm

## Overview

claude-vm is a Bash manager for isolated, per-project QEMU VMs running Claude Code. The documented workflow builds a provisioned base image, creates a linked project snapshot, mounts the project with virtiofs, syncs selected host configuration, and connects the terminal over SSH. The graph also includes documented lifecycle and management commands. Relationships are based on the README and file names; source excerpts were unavailable, so internal call wiring is not asserted beyond documented behavior.

Main entry points: [`claude-vm`](https://github.com/shudza/claude-vm/blob/master/claude-vm) (CLI commands), [`lib/launch.sh`](https://github.com/shudza/claude-vm/blob/master/lib/launch.sh) (Launch VM), [`lib/build.sh`](https://github.com/shudza/claude-vm/blob/master/lib/build.sh) (Build base image), [`lib/snapshot.sh`](https://github.com/shudza/claude-vm/blob/master/lib/snapshot.sh) (Project snapshot)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["Command interface"]
  node_cli["CLI commands"]
end

subgraph group_images["Image lifecycle"]
  node_build["Build base image<br/>[build.sh]"]
  node_provision["Cloud-init setup<br/>[cloud-init.sh]"]
  node_base[("Flavor base image")]
  node_snapshot[("Project snapshot<br/>[snapshot.sh]")]
  node_rebase["Rebase state<br/>[rebase.sh]"]
end

subgraph group_runtime["VM runtime"]
  node_launch["Launch VM<br/>[launch.sh]"]
  node_virtiofs["Project filesystem mount<br/>[virtiofs.sh]"]
  node_configsync["Host config sync<br/>[launch.sh]"]
  node_qemu["QEMU virtual machine"]
  node_ssh["SSH access<br/>[launch.sh]"]
  node_shutdown["Stop VM<br/>[shutdown.sh]"]
end

subgraph group_management["Project management"]
  node_config[("Configuration<br/>[config.sh]")]
  node_ui["Status and display<br/>[ui.sh]"]
  node_destroy["Destroy artifacts"]
  node_copy["Copy into VM"]
  node_list["List snapshots"]
end

node_user(("Developer"))
node_hostproject[("Host project directory")]
node_claude["Claude Code session"]

node_user -->|"runs command"| node_cli
node_cli -->|"builds image"| node_build
node_build -->|"provisions image"| node_provision
node_build -->|"creates"| node_base
node_cli -->|"launches sandbox"| node_launch
node_launch -->|"creates or resumes"| node_snapshot
node_snapshot -->|"uses backing image"| node_base
node_launch -->|"starts VM"| node_qemu
node_launch -->|"mounts project"| node_virtiofs
node_virtiofs -->|"shares at /workspace"| node_hostproject
node_launch -->|"syncs settings"| node_configsync
node_launch -->|"connects terminal"| node_ssh
node_ssh -->|"opens session"| node_qemu
node_qemu -->|"runs"| node_claude
node_cli -->|"stops VM"| node_shutdown
node_cli -->|"rebases image"| node_rebase
node_rebase -->|"rebuilds base"| node_base
node_cli -->|"reads or updates"| node_config
node_cli -->|"shows status"| node_ui
node_cli -->|"removes artifacts"| node_destroy
node_cli -->|"copies files"| node_copy
node_cli -->|"lists projects"| node_list

click node_cli "https://github.com/shudza/claude-vm/blob/master/claude-vm"
click node_build "https://github.com/shudza/claude-vm/blob/master/lib/build.sh"
click node_provision "https://github.com/shudza/claude-vm/blob/master/lib/cloud-init.sh"
click node_snapshot "https://github.com/shudza/claude-vm/blob/master/lib/snapshot.sh"
click node_rebase "https://github.com/shudza/claude-vm/blob/master/lib/rebase.sh"
click node_launch "https://github.com/shudza/claude-vm/blob/master/lib/launch.sh"
click node_virtiofs "https://github.com/shudza/claude-vm/blob/master/lib/virtiofs.sh"
click node_configsync "https://github.com/shudza/claude-vm/blob/master/lib/launch.sh"
click node_ssh "https://github.com/shudza/claude-vm/blob/master/lib/launch.sh"
click node_shutdown "https://github.com/shudza/claude-vm/blob/master/lib/shutdown.sh"
click node_config "https://github.com/shudza/claude-vm/blob/master/lib/config.sh"
click node_ui "https://github.com/shudza/claude-vm/blob/master/lib/ui.sh"
click node_destroy "https://github.com/shudza/claude-vm/blob/master/claude-vm"
click node_copy "https://github.com/shudza/claude-vm/blob/master/claude-vm"
click node_list "https://github.com/shudza/claude-vm/blob/master/claude-vm"

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 toneBlue
class node_build,node_provision,node_base,node_snapshot,node_rebase,node_hostproject toneAmber
class node_launch,node_virtiofs,node_configsync,node_qemu,node_ssh,node_shutdown toneMint
class node_config,node_ui,node_destroy,node_copy,node_list toneRose
class node_user,node_claude toneIndigo
```

## Components

### Command interface

- [CLI commands](https://github.com/shudza/claude-vm/blob/master/claude-vm): `claude-vm`

### Image lifecycle

- [Build base image](https://github.com/shudza/claude-vm/blob/master/lib/build.sh): `lib/build.sh`
- [Cloud-init setup](https://github.com/shudza/claude-vm/blob/master/lib/cloud-init.sh): `lib/cloud-init.sh`
- **Flavor base image**
- [Project snapshot](https://github.com/shudza/claude-vm/blob/master/lib/snapshot.sh): `lib/snapshot.sh`
- [Rebase state](https://github.com/shudza/claude-vm/blob/master/lib/rebase.sh): `lib/rebase.sh`

### VM runtime

- [Launch VM](https://github.com/shudza/claude-vm/blob/master/lib/launch.sh): `lib/launch.sh`
- [Project filesystem mount](https://github.com/shudza/claude-vm/blob/master/lib/virtiofs.sh): `lib/virtiofs.sh`
- [Host config sync](https://github.com/shudza/claude-vm/blob/master/lib/launch.sh): `lib/launch.sh`
- **QEMU virtual machine**
- [SSH access](https://github.com/shudza/claude-vm/blob/master/lib/launch.sh): `lib/launch.sh`
- [Stop VM](https://github.com/shudza/claude-vm/blob/master/lib/shutdown.sh): `lib/shutdown.sh`

### Project management

- [Configuration](https://github.com/shudza/claude-vm/blob/master/lib/config.sh): `lib/config.sh`
- [Status and display](https://github.com/shudza/claude-vm/blob/master/lib/ui.sh): `lib/ui.sh`
- [Destroy artifacts](https://github.com/shudza/claude-vm/blob/master/claude-vm): `claude-vm`
- [Copy into VM](https://github.com/shudza/claude-vm/blob/master/claude-vm): `claude-vm`
- [List snapshots](https://github.com/shudza/claude-vm/blob/master/claude-vm): `claude-vm`

### Other components

- **Developer**
- **Host project directory**
- **Claude Code session**

## Connections

- Developer → CLI commands: runs command
- CLI commands → Build base image: builds image
- Build base image → Cloud-init setup: provisions image
- Build base image → Flavor base image: creates
- CLI commands → Launch VM: launches sandbox
- Launch VM → Project snapshot: creates or resumes
- Project snapshot → Flavor base image: uses backing image
- Launch VM → QEMU virtual machine: starts VM
- Launch VM → Project filesystem mount: mounts project
- Project filesystem mount → Host project directory: shares at /workspace
- Launch VM → Host config sync: syncs settings
- Launch VM → SSH access: connects terminal
- SSH access → QEMU virtual machine: opens session
- QEMU virtual machine → Claude Code session: runs
- CLI commands → Stop VM: stops VM
- CLI commands → Rebase state: rebases image
- Rebase state → Flavor base image: rebuilds base
- CLI commands → Configuration: reads or updates
- CLI commands → Status and display: shows status
- CLI commands → Destroy artifacts: removes artifacts
- CLI commands → Copy into VM: copies files
- CLI commands → List snapshots: lists projects