trailofbits / trailofbits/coop
Immutable OS image with in-place upgrade
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 243
- Forks
- 13
- Avg merge
- 1d 20h
- Merged PRs (30d)
- 30
Description
Summary
Separate the OS image (read-only, shared) from instance data (writable, per-instance) using two disks per VM. This enables a coop upgrade command that swaps the OS image while preserving all user data.
Relates to #4 (persistent volumes across VM restarts).
Motivation
Currently each instance is a mutable clone of the golden template. Upgrading the base image (new packages, new Claude Code version, security patches) requires destroying the instance and losing all in-guest state — Docker images, shell history, installed tools, workspace changes.
auditbox solves this with an immutable NixOS image plus a persistent /persist volume. The OS can be swapped atomically while work survives.
Design
Two disks per instance:
- OS disk (read-only): Points directly at the golden template image. Shared across instances using the same image. No per-instance copy needed.
- Data disk (read-write): Per-instance volume mounted at
/persist. Contains bind-mounted directories for/home/ubuntu,/workspace,/var/lib/docker, and SSH host keys.
coop upgrade <name>:
- Stop the instance
- Build or fetch the new golden image
- Update the OS disk reference to point to the new image
- Start the instance — boots into new OS, data volume mounts automatically
Both backends support this natively:
- Firecracker: multiple entries in the
drivesJSON config, withis_read_only: truefor the OS drive - Lima:
additionalDisks:in the YAML template
Guest-side changes:
- Systemd units or init scripts to mount the data volume and create bind-mounts
- First-boot initialization of the data volume (directory structure, formatting)
Migration: Existing single-disk instances would need a one-time migration to extract user data into the new data volume format.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
No files or tests are named. Start by locating the Firecracker drive configuration and Lima additionalDisks template handling, then trace current single-disk creation and guest initialization. Done means an upgrade can swap the OS image while preserving the listed data, with a migration path for existing single-disk instances.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- cli, infrastructure, operating-systems
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100