trailofbits / trailofbits/coop
Firecracker VM pause and resume
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 243
- Forks
- 13
- Avg merge
- 1d 20h
- Merged PRs (30d)
- 30
Description
Summary
Add coop suspend and coop resume commands that pause and unpause Firecracker VMs via the existing API socket, providing near-instant resume instead of full cold boot.
Motivation
Cold-booting a Firecracker VM takes 30-60 seconds. For the common workflow of pausing work and coming back later, this is unnecessarily slow. Firecracker natively supports pausing and resuming VMs — vCPUs freeze in place and resume exactly where they left off.
A second phase could add snapshot-to-disk support, where the full VM state (memory + CPU) is written to disk, allowing the Firecracker process to exit and free memory. Snapshot restore takes ~28ms via memory-mapped loading.
Behavior
Phase 1: In-memory pause/resume
coop suspend <name>sendsPATCH /vm {"state": "Paused"}to the Firecracker API socket. The VM process stays alive but vCPUs stop executing. Memory remains resident.coop resume <name>sendsPATCH /vm {"state": "Resumed"}. vCPUs resume instantly. SSH connections survive if the pause was short (under TCP timeout).coop statusdistinguishes "Paused" from "Running".
Phase 2: Snapshot to disk (future)
coop suspend --snapshot <name>pauses the VM, writes a full snapshot (state file + memory file) to the instance directory, then terminates the Firecracker process. Memory is freed.coop resume <name>detects the snapshot, starts a new Firecracker process, loads the snapshot via/snapshot/load, and resumes. TAP device is re-created before loading.
Limitations
- macOS/Lima only has cold boot. Apple's Virtualization.framework does not support save/restore for Linux guests.
coop suspendon Lima would return an error or fall back tocoop stop. - Clock skew: The guest clock jumps forward on resume. NTP corrects this, but applications may observe a time discontinuity.
- Network connections: Long pauses cause TCP timeouts. SSH sessions will need to reconnect after extended pauses.
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
Start with the existing coop command entry points and the Firecracker API-socket integration, then trace how coop status determines VM state. Implement Phase 1 suspend and resume behavior, including the Lima limitation, and verify that status distinguishes Paused from Running; snapshot support is explicitly a future phase.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- cli, operating-systems
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100