// never run npm install on your machine again
Plenty of tools can boot you an isolated VM. machine boots one your agent
can actually work in: Docker, Node, gh, signed git, Claude Code with
plugins — provisioned from version-controlled templates, disposable when it
gets weird. Your private keys never enter the VM; secrets live in tmpfs.
Saying yes to everything is finally a safe answer.
requires macOS 13+ · apple silicon or intel · guests are ubuntu 24.04
// section 01 — the promise
Your Mac is the thin client: terminal, browser, SSH agent, password manager, machine.
Each project gets a real Linux VM with its own filesystem, tools, services, ports,
secrets, and agent sessions. Destroy it when it gets weird. Recreate it when you need it again.
Buy a new laptop, install Homebrew and machine, and your projects come back as machines —
not as a pile of global runtimes and forgotten setup steps.
// section 02 — architecture
Your Mac stays small. The CLI drives Lima. Lima boots one Linux VM per project. The VM gets the repo and the tools; the host keeps your keys, dotfiles, browser, and life.
ssh-agent is forwarded into the guest at exec time. The key file never leaves the host — the guest can use the keys while connected, never read them.$XDG_RUNTIME_DIR/dev-secrets, a tmpfs that's wiped at shutdown.mountType is disabled. The VM can't read your ~/ or anything else.// section 03 — why bother
Claude Code and Codex ship in the base image, wired to the official Claude marketplace and a curated plugin set. They run inside the same Linux environment as the repo. Permission auto-mode is on by default — safe by construction, because there's nothing of yours in there to lose.
machine claude blog
One VM per project. No host filesystem mount. No shared project volumes. Your SSH agent is forwarded in for auth and signing — private keys never leave the host, though the VM can use them while you're connected (gate or drop that grant per project: restricting the forwarded agent). The blast radius of a bad dependency or over-eager agent is one disposable machine.
machine up blog
No project runtimes, databases, browser deps, global CLIs, package caches, or mystery setup on your Mac. Install machine once; put the mess in project VMs.
brew install katspaugh/machine/machine
Machines are built from version-controlled Lima templates and provision scripts. Destroy one, rebuild it, or bring the same setup to a new laptop.
machine destroy blog && machine up blog
// section 04 — threat model
The point of a project machine is the boundary. Your repo, selected secrets, SSH agent, and forwarded ports cross it. Your home directory, dotfiles, keychain, browser profile, and other projects do not.
.envrc$XDG_RUNTIME_DIR/dev-secrets (tmpfs)machine destroy && machine up is cheap.// section 05 — why not just containers?
Devcontainers are great for declaring tools and services. machine gives them a clean place
to run: a disposable Linux VM per project, with no host filesystem mount and no
cross-project bleed. Use both — a project VM can run Docker and devcontainers inside Linux,
while your Mac only runs machine.
And Claude Code's built-in sandbox? It fences single commands on your host;
a VM hands the agent a separate machine with nothing of yours on it. The two
compose — the full comparison (built-in sandboxing, devcontainers, Tart,
Apple's container) is in
Sandboxing Claude Code.
// section 06 — profiles
Profiles are the only setup you repeat. Pick a base, layer extras like Playwright, Cypress,
Supabase, or Fly, or write your own as a small template + provision script. The result lives
in the project machine, not in /opt/homebrew, ~/Library, or some
forgotten global npm install.
Chrome (or Chromium on arm64), Xvfb, and the lib deps Cypress needs. Node lands from the base image.
The OS libs Playwright's browsers need, pre-installed. Each repo's npx playwright install then works without sudo.
The two CLIs you actually use when shipping a backend. Docker comes from the base image.
A profile is a Lima template and a shell script. Copy any of the above, point it at a new script, reference it in projects.toml.
// section 07 — demo
A VHS replay of the CLI surface — list, up, secrets, ssh, down. The first up is the slow one; subsequent boots are warm restarts.
// section 08 — lifecycle
Twelve commands, no manifesto. Most days: up, ssh in, work, down.
Machines are meant to be boring — boot one, run Claude, run tests, and destroy it
when the state no longer deserves trust.
projects.toml — repos, profiles, shell — or edit an existing entry.claude in a tmux session — detach and it keeps working; re-run to reattach.machine run wallet hx opens Helix to edit the project.machine up — scripts re-run on boot.machine up to start fresh.~/.cache/machine that up reuses.op CLI.$XDG_RUNTIME_DIR/dev-secrets (tmpfs) for this project.projects.toml to ~/.config/machine/ (or to the repo root in dev mode).// section 09 — editors
Use VS Code Remote-SSH, Cursor, JetBrains Gateway, Emacs TRAMP, or plain ssh.
The project machine is a normal SSH host, so your tools don't need a machine plugin.
Add Include ~/.lima/*/ssh.config to ~/.ssh/config once; Lima maintains the per-VM configs. Cursor and JetBrains Gateway pick them up too. Prefer a terminal editor? machine run wallet hx runs Helix (or vim / nvim) right inside the machine — no plugin, nothing editor-shaped on the host.
Install from the Homebrew tap, run machine init, then machine up.
Requires macOS 13 or newer, Apple Silicon or Intel — the VM layer is Apple's Virtualization framework, so Linux and Windows hosts aren't supported. Prefer to clone? git clone the repo — same code, dev mode. Read the formula or verify the release before installing.