trailofbits / trailofbits/coop

Firecracker VM pause and resume

Open
#17 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

priority:low
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> sends PATCH /vm {"state": "Paused"} to the Firecracker API socket. The VM process stays alive but vCPUs stop executing. Memory remains resident.
  • coop resume <name> sends PATCH /vm {"state": "Resumed"}. vCPUs resume instantly. SSH connections survive if the pause was short (under TCP timeout).
  • coop status distinguishes "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 suspend on Lima would return an error or fall back to coop 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

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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.