How shudza/claude-vm works
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 CLI commands · launch.sh Launch VM · build.sh Build base image · snapshot.sh Project snapshot
Components 20
Command interface
- CLI commands
claude-vm
Image lifecycle
- Build base image
lib/build.sh - Cloud-init setup
lib/cloud-init.sh - Flavor base image
- Project snapshot
lib/snapshot.sh - Rebase state
lib/rebase.sh
VM runtime
- Launch VM
lib/launch.sh - Project filesystem mount
lib/virtiofs.sh - Host config sync
lib/launch.sh - QEMU virtual machine
- SSH access
lib/launch.sh - Stop VM
lib/shutdown.sh
Project management
- Configuration
lib/config.sh - Status and display
lib/ui.sh - Destroy artifacts
claude-vm - Copy into VM
claude-vm - List snapshots
claude-vm
Other components
- Developer
- Host project directory
- Claude Code session
Connections 22
- 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