Firebreak

Firebreak is a VM-first control plane for running coding agents with a small public interface.

Firebreak CLI

firebreak vms
firebreak run codex
firebreak run codex --shell
firebreak run claude-code -- --help

firebreak vms lists the public VM workloads. firebreak run <vm> launches one of them through the existing Firebreak VM packages.

Local Workloads

• nix run .#firebreak-codex launches Codex in the local Firebreak VM
• nix run .#firebreak-claude-code launches Claude Code in the local Firebreak VM
• FIREBREAK_VM_MODE=shell nix run .#firebreak-codex reaches the maintenance shell for the same VM package
• supported local host systems: x86_64-linux, aarch64-linux, and Apple Silicon aarch64-darwin

NPX Launcher

Firebreak ships a thin Node launcher so users can run the Nix-backed CLI with npx firebreak ....

npx firebreak vms
npx firebreak run codex
npx firebreak doctor
npx firebreak init

The launcher:

• checks that the host is Linux on x86_64 or aarch64, or Apple Silicon macOS on arm64
• checks that nix is installed and callable
• checks that /dev/kvm is usable before non-diagnostic commands on Linux hosts
• uses the local Firebreak checkout automatically when you run it inside a cloned Firebreak repo
• falls back to github:skadaai/firebreak when no local Firebreak checkout is present
• forwards all arguments to the existing Bash Firebreak CLI through nix run

Project Defaults

firebreak init is interactive by default and writes a project-local .firebreak.env file tailored to the answers you choose. The file uses the same KEY=VALUE spelling as the public environment variables, and real environment variables take precedence over file values.

nix run .#firebreak -- init
nix run .#firebreak -- init --non-interactive
nix run .#firebreak -- doctor

Example .firebreak.env:

AGENT_CONFIG=workspace
# FIREBREAK_VM_MODE=run
# CODEX_CONFIG=workspace
# CLAUDE_CONFIG=workspace

Diagnostics

firebreak doctor reports:

• project root and config-file resolution
• host platform and selected local runtime path
• public VM mode resolution
• Codex and Claude Code config resolution
• current working directory compatibility
• KVM availability when relevant, plus primary-checkout state

Use nix run .#firebreak -- doctor --json for machine-readable output.