trailofbits / trailofbits/coop

Garbage collection for orphaned resources

Open
#18 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

Add a coop gc command that discovers and cleans up orphaned resources: stale stopped instances, orphaned Lima VMs, dangling TAP devices, and leftover SSH config entries.

Motivation

Resources can become orphaned through crashes, manual deletion of instance directories, or simply forgetting about stopped VMs. There is no way to discover or clean these up short of manual inspection.

Behavior

coop gc runs in two phases:

Discovery (always runs):

  • Stopped instances (optionally filtered by --max-age <days>)
  • Corrupted instance directories (missing or invalid instance.json)
  • Orphaned Lima VMs (~/.lima/coop-* with no matching coop instance) on macOS
  • Orphaned TAP devices attached to br0 with no matching running instance on Linux
  • SSH config entries (~/.ssh/config coop marker blocks) for instances that no longer exist
  • Stale Lima builder VM (coop-builder) left from a crashed setup

Cleanup (with --yes):

  • Destroys stale instances using existing destroy logic
  • Removes corrupted instance directories
  • Deletes orphaned Lima VMs via limactl delete --force
  • Removes orphaned TAP devices and tears down bridge if empty
  • Strips stale SSH config entries

Default behavior is dry-run — shows what would be cleaned up without taking action. --yes executes the cleanup.

Age-based filtering requires tracking a last_started timestamp on instances.

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 at the CLI entry point for the new coop gc command and inspect the existing instance-destroy logic. Map discovery and cleanup for instances, Lima VMs, TAP devices, SSH marker blocks, and the builder VM on each platform; done means a dry-run by default, --yes cleanup, and the specified age filtering.

Written by the indexing model from the issue text.

Assessment

Tech stack
linux, macos, 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.