coop

Isolated VM environments for running Claude Code and Codex.

Pronunciation: "coop" (/kuːp/) — one syllable, rhymes with "loop", like the thing you keep chickens in. Not "co-op".

coop is a Rust CLI that manages disposable virtual machines where Claude Code and Codex have full tool access: Docker, git, compilers, package managers, all without risk to your host machine. Each VM is isolated, reproducible, and cheap to create and destroy. On Linux, coop runs Firecracker microVMs backed by KVM. On macOS, it uses Lima with Apple's Virtualization.framework. The backend is selected automatically based on platform.

Quick start

Install:

curl -fsSL https://raw.githubusercontent.com/trailofbits/coop/main/install.sh | bash

Or build from source (requires Rust):

cargo build --release
cp target/release/coop /usr/local/bin/

Set up the VM template, start an instance, and launch an agent CLI:

export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-proj-...
coop setup
cd ~/code/my-project
coop up
coop claude
# or
coop codex

That gives you a Claude Code or Codex session running inside an isolated VM with your project synced in. coop up is re-runnable: it creates an environment for the current project the first time, reuses it if it is already running, and restarts it after coop stop. During startup, coop writes ~/.claude/settings.json in the guest with defaultMode: bypassPermissions and skipDangerousModePermissionPrompt: true, so Claude Code runs without permission prompts — the VM itself is the isolation boundary. Pass --ask to coop claude to restore prompts for that session (--permission-mode default).

Features

• Two backends: Firecracker microVMs (Linux/KVM) and Lima VMs (macOS/Virtualization.framework), auto-detected by platform
• Workspace sync: copy or mount a local project directory into the VM with coop up
• Profiles: customizable guest environments with apt packages and install scripts; built-in profiles for Python, Node, C, Rust, Go, and fuzzing; coop up --profile python,node builds the matching image on demand
• Named images: build multiple template images with different profiles (coop setup --image ml-dev --profile python)
• Claude Code integration: API key forwarding, CLAUDE.md injection, plugin/marketplace support, MCP server configuration
• Codex integration: API key forwarding, ~/.codex config sync, MCP server configuration, dedicated coop codex launcher
• VS Code remote SSH: coop vscode opens VS Code connected to the guest
• Multi-instance: run multiple VMs side by side, each with its own name and disk
• Reconfigure in place: change a stopped instance's disk, memory, or vCPUs with coop resize (e.g. coop resize --size +20 --mem 8192 --vcpus 4) — no destroy/recreate
• Commit and restore: save a stopped instance's filesystem as a reusable image with coop commit, and roll an instance back to it in place with coop restore — a docker container commit-style checkpoint for risky agent runs
• Config optional: works with sensible defaults; customize via ~/.coop/config.toml when needed

Commands

Shell completion

coop completions <bash|zsh|fish|powershell|elvish> prints a static completion script. Adding source <(COMPLETE=<shell> coop) to your rc additionally completes instance, image, and profile names live. Full setup recipes are in docs/shell-completion.md.

Updating

coop update replaces the running binary with the latest release from
github.com/trailofbits/coop. It downloads the tarball matching the current
host triple, verifies the SHA-256 against the release's SHA256SUMS, and
(when gh is installed) verifies the GitHub build-provenance attestation
before swapping the binary atomically.

No authentication is required. When gh is
authenticated against github.com or GITHUB_TOKEN is set, coop update
uses it, which helps avoid GitHub API rate limits.

coop update --check             # report whether a newer release exists
coop update                     # prompt, then install the latest release
coop update --yes               # skip confirmation
coop update --version v0.3.2    # pin to a specific release
coop update --force             # reinstall the current version

If coop is installed in a protected directory (e.g. /usr/local/bin), run
with sudo. Dev builds (built from an untagged or dirty tree) refuse to
self-update; use install.sh to replace them.

By default, coop checks for a newer release in the background at most once
per day and prints a one-line notice on stderr when an update is available.
Opt out with either:

• updates.mode = "off" in ~/.coop/config.toml, or
• COOP_NO_UPDATE_CHECK=1 in the environment.

The check is also silent when CI=true or when stdin is not a TTY.

Verifying a release

Every release tarball is published with a Sigstore build-provenance
attestation via actions/attest-build-provenance.
The attestation proves the artifact was built from this repository by the
tagged release workflow.

Both install.sh and coop update run this verification automatically
when the GitHub CLI is installed. Without gh,
they fall back to checksum verification against the release's SHA256SUMS
and print a note explaining what was and wasn't verified.

To verify a downloaded tarball manually:

gh attestation verify coop-<version>-<triple>.tar.gz --repo trailofbits/coop

Requirements

Tested on macOS arm64 (Apple Silicon) and Linux x86_64. Linux arm64 builds are available but untested.

macOS (Lima backend)

• macOS with Apple Silicon
• Lima with limactl on your PATH (installed automatically by coop setup)
• Rosetta 2 for x86_64 guests on Apple Silicon: softwareupdate --install-rosetta

Linux (Firecracker backend)

• x86_64 or arm64 architecture
• KVM access (/dev/kvm must exist and be writable by your user)
• sudo privileges (Firecracker uses jailer and TAP networking)
• curl, tar, e2fsprogs (for mkfs.ext4, resize2fs)

Documentation

• Getting started
• Command reference
• Configuration reference
• Images and profiles
• Workspace sync
• Claude Code integration
• Codex integration
• VS Code integration
• Multi-instance
• Platform backends
• Shell completion