Skip to content

feat: VM snapshot and restore for warm starts #3

@razvanz

Description

@razvanz

Add nixbox snapshot and nixbox restore (or nixbox up --snapshot) using cloud-hypervisor's snapshot API for near-instant warm starts.

Why: Every nixbox up boots fresh. For JVM/Scala projects, the first session needs sbt update (5-15 min) + sbt compile (2-10 min) + docker compose pull (1-5 min). Snapshots capture the full VM state after warming, allowing sub-5s restore.

Workflow:

nixbox up
nixbox shell
> sbt update compile && docker compose pull
> exit
nixbox snapshot              # freeze VM state
# later...
nixbox up --snapshot         # restore in ~2-5s

Key challenges:

  1. virtiofsd sockets must match — guest kernel remembers virtiofs tags from original boot. On restore, virtiofsd instances must start with the same socket paths before VM resumes.
  2. Host-side state recreation — TAP device, nftables, dnsmasq must be re-created on restore (not captured in snapshot).
  3. Credential safety — wipe credentials inside VM before snapshot. Re-inject via env disk or SSH after restore. Snapshots must be credential-free.
  4. Persistent volume — disk state must match snapshot. Use CoW (btrfs snapshot) or simple copy.

cloud-hypervisor API:

  • PUT /api/v1/vm.pause
  • PUT /api/v1/vm.snapshot with {"destination_url": "file:///path"}
  • PUT /api/v1/vm.restore with {"source_url": "file:///path"}

CLI:

nixbox snapshot              # pause + snapshot running VM
nixbox up --snapshot         # restore if available, else fresh boot
nixbox snapshot --list       # list snapshots
nixbox snapshot --delete     # remove snapshot

Target: < 5s from restore to SSH-ready.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions