trailofbits / trailofbits/coop

Immutable OS image with in-place upgrade

Open
#21 0 comments 0 reactions 0 assignees View on GitHub

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>:

  1. Stop the instance
  2. Build or fetch the new golden image
  3. Update the OS disk reference to point to the new image
  4. Start the instance — boots into new OS, data volume mounts automatically

Both backends support this natively:

  • Firecracker: multiple entries in the drives JSON config, with is_read_only: true for 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.