devvm Documentation

Pages

1. OverviewPublic entry points, per-project VM sandbox architecture, runtime assumptions, and primary documentation routes.
2. InstallationInstall devvm on macOS and Linux via Homebrew or the signed release installer, verify Minisign signatures, and validate host readiness with devvm doctor.
3. QuickstartConfigure initial defaults with devvm setup, launch a project VM with auto-detected toolchains and agents, and verify isolation in the guest shell.
4. VM lifecycle and stateHow project paths map to VM names and 8-hex hashes, state persistence in vm.json, layout version checks, and in-place vs. remake transitions.
5. Images, layers, and content keysDeterministic SHA-256 key computation for base images, built-in and custom layers (docker, nix, desktop), and read-only EROFS shared tool images.
6. Network tiers and host proxyTraffic confinement across allowlist, open, and offline tiers, host-side TLS SNI and HTTP inspection via devvm _proxy, and per-VM CA rotation.
7. Host and Git isolation boundariesRead-only .git mount protection, symlink and hardlink containment, set-id file audits, secret placeholder injection, and isolated repo clones.
8. Backend contract and Lima driverThe four-role backend.Backend interface (Host, Images, Machines, Housekeeping), capability requirement checks (Caps), and the Lima driver implementation.
9. Configure coding agents and credentialsRun Claude Code, Codex, and opencode inside VMs, import and save agent settings, complete OAuth or API-key logins, and bind host secrets to allowed hosts.
10. Manage toolchains and custom layersAdd, remove, and update shared mise toolchains (node, python, rust, go, dotnet) and author custom image layers with network policies via devvm layer new.
11. Use devcontainer.json and OCI base imagesTranslate .devcontainer/devcontainer.json properties into VM plans and build bootable VM base images from OCI/Docker container references with --from.
12. Connect VMs with links, groups, and port forwardsForward guest ports to host 127.0.0.1, publish ports and link VMs under *.devvm hostnames, and join VMs into mutually reachable groups.
13. Connect SSH, VS Code, and VNC desktopUse generated ~/.ssh/config entries, configure per-VM SSH agents, launch VS Code Remote-SSH via devvm code, and connect to the VNC desktop relay.
14. Isolate work with repository clonesCreate VMs with independent Git clones using devvm --clone, switch existing VMs between mounted folders and clones, and fetch VM branches to the host.
15. CLI reference: VM and workspace commandsSyntax, flags, exit codes, and examples for devvm (up), ls, restart, stop, update, rm, adopt, size, ports, host, code, desktop, and history.
16. CLI reference: network, security, and agent commandsSyntax, subcommands, and flags for devvm network, secret, agent, git-protect, clone, ssh-agent, link, and group.
17. CLI reference: images, storage, and host commandsSyntax, subcommands, and flags for devvm build, rebuild, images, layer, tools, space, gc, retention, setup, doctor, upgrade, completion, and limactl.
18. Configuration (config.toml) and --json schema referenceComplete reference for ~/.config/devvm/config.toml keys, settings.json precedence, environment variables, state directory layout, and version 1 --json payloads.
19. Diagnose host, boot, and SSH failuresResolve devvm doctor host problems, Ubuntu cloud image boot fallbacks, SSH host-key verification errors, run logs, and moved project directories with devvm adopt.
20. Troubleshoot network policies, CAs, and disk spaceInspect blocked requests with devvm network log, configure corporate HTTP/HTTPS proxies and custom CAs in ~/.config/devvm/ca, and recover disk space.
21. Manage disk retention, garbage collection, and upgradesConfigure automatic retention policies for run logs, agent history exports, unused tools, orphaned state, and Nix caches, and upgrade devvm installations.
22. Codebase invariants, testscript stubs, and E2E suiteEnforce single-owner and layer rules in internal/structure, write deterministic CLI testscript tests with internal/stubtest, and run real-VM E2E suites.
23. Pinning, release signing, and supply-chain verificationMaintain SHA-256 download pins and Ubuntu PGP archive checks with scripts/bump.sh, build and sign releases with Minisign, and publish artifacts.