devvm: one isolated VM per project folder, cloned from a base image, with toolchains and agents shared read-only between VMs. It's a Go CLI that runs its VMs on Lima, behind a backend interface another backend could implement. Read README.md for what it is, and the docs site for how each part works; Contributing covers building, the tools, testscript and writing docs.
Each package's concerns and identifiers: The packages.
| Path | What |
|---|---|
cmd/devvm/ |
the entry point (ui.Main); the only os.Exit |
internal/cli/ |
the command line: one file per Cobra command, the run's services (app.go), argument checks, help, --json, the CLI tests, docgen/; doc.go maps it |
internal/vm/ |
what each command does to a folder's VM, below the command line; doc.go maps the package and its owners |
internal/shell/, internal/vmname/ |
quoting for a POSIX shell; every VM's name (vmname.VM, parsed where it's read) and a project VM's name grammar |
internal/project/, internal/gitprotect/, internal/hostsafety/, internal/hostgit/ |
a project folder; .git protection; the folder's other host checks; every host git command devvm runs |
internal/sshconfig/, internal/sshagent/ |
the ssh config for running VMs by name; each VM's SSH agent and devvm's own |
internal/build/, internal/image/ |
building images and their records; image keys and names, and the shared tools' registry (SharedTools) |
internal/fetch/ |
every HTTP client |
internal/upgrade/ |
devvm upgrade; upgradetest/ (tests only) |
internal/from/ |
--from's references and digests |
internal/redact/ |
passwords out of logs; Secret, the type of every secret's value |
internal/vmlog/ |
every log a VM can drive (but the proxy's own): its rate, its cap while it runs, and the backend's logs, serial consoles' included |
internal/safefile/ |
every read of a file a VM can write or swap |
internal/landlock/ |
Linux's sandbox for the proxy's child: Landlock and the hand-written seccomp filter (Self) |
internal/devcontainer/, internal/jsonc/ |
a project's devcontainer.json; JSON with comments |
internal/tools/ |
the shared tools: the lock, host mise, the daily check, tool image builds, the share |
internal/netpolicy/, internal/secrets/ |
network policy; tokens on the host, the VM's bindings and your own secrets |
internal/trust/ |
your CAs, and each VM's own CA |
internal/agents/ |
the coding agents' registry: one Def each, which every list of the agents derives from |
internal/agentlogin/ |
agents' login and settings files on the host, and their placeholders |
internal/proxy/ |
the proxy: its broker, devvm _proxy, and the child that reads the VM's network, devvm _proxy-child; see its README.md; every host's one form (NormHost); the VM's SSH agent relay, the only way a VM reaches an agent |
internal/daemon/ |
devvm's background processes; the only place a process is signalled by pid |
internal/seatbelt/ |
macOS's sandbox: sandbox-exec, profile strings and real paths, the proxy child's profile |
internal/desktop/ |
devvm desktop's relay on the host |
internal/backend/ |
Backend, its roles, Caps, the registry and its guard; backendtest/, registry/, lima/ |
internal/vmssh/ |
devvm's own ssh to a VM (Checked), the port forwarder (Forwards), each start's host keys |
internal/ui/ |
the only package that prints |
internal/msg/, locales/ |
messages, Reporter and Question |
internal/ports/ |
a VM's ports and the one allocator of host ports |
internal/paths/, internal/state/ |
every folder and file devvm uses; vm.json, the layout version, files written whole |
internal/settings/ |
the defaults: config.toml over settings.json, each value's check |
internal/platform/, internal/ubuntu/, internal/testbuild/ |
build-tagged OS code; Ubuntu's cloud image (never downloads); whether this is a test build |
assets/ |
the files devvm ships, embedded (assets.FS) |
internal/structure/ |
the structure test |
internal/stubtest/, internal/leaktest/, internal/memnet/ |
the test stubs; the goroutine leak checks (Main, Check); the network in memory for synctest bubbles |
testdata/ |
CLI tests, golden fixtures, coverage baselines, each release's frozen state (v<release>/), lint/ |
tests/e2e/, tests/e2e-mise.lock |
end-to-end tests on real VMs |
scripts/, packaging/, .goreleaser.yaml, VERSION, CHANGELOG.md |
pins, releases, the test tasks' scripts, the Homebrew formula, devvm upgrade's key |
install.sh |
curl | bash, asking before doctor's fixes |
docs/ |
the docs site (Hugo + Hextra); content/docs/cli/ is generated, never edit it |
mise.toml, .golangci.yml, .vale*, .markdownlint-cli2.yaml, .github/ |
tools, tasks, linters, CI and Pages |
.agents/skills/security-audit/ |
the security-audit skill, for backend reviews |
.agents/skills/cli/ |
the cli skill: devvm's command line rules, the checklist for adding a command, the tests behind each rule, judgment.md for the rest |
.agents/skills/docs-voice/ |
the docs-voice skill: the voice of the prose and messages, terms, tropes, scan.sh and facts.sh |
.agents/skills/codebase-standards/ |
the codebase-standards skill: the checklist for a commit and a review from what reviews kept finding, matching the codebase's style, every rule's guard |
mise run <task>: fmt, lint (lint:code, lint:docs), test, coverage (commit the baselines it raised with the change), vuln, nilaway (advisory: a new finding gets a fix and a test, or a line in testdata/nilaway-baseline.txt), nilaway:linux (must pass before a push to main), deadcode (anything but the tests' helpers gets a caller or goes), cli-docs (after changing a command's help, flags or docs page; commit the pages), docs, e2e: Tools and tasks.
- The gate:
mise run fmt && mise run lint && mise run test, all passing, before starting a task and before marking it done; a gate failing at the start gets fixed first. Anything touching VMs also passesmise run e2ein the background: the sections for what changed (--only). - Nothing in project folders: state goes in
~/.local/share/devvmand~/.config/devvm. - devvm's own files never get a shared copy on disk: the proxy reads them from the binary, base.yaml and scripts go on stdin,
--from's build writes its scripts into its own temp folder. - Credentials never go into images. Host agent history never goes into VMs.
- Never auto-delete project VMs: they may hold unsaved work. Warn instead.
- Every release's state keeps working until 1.0: a change to state runs its new commands on every frozen
testdata/v<release>/fixture (never edited or regenerated) in the same commit, and a change for existing state gets a Breaking changelog entry (Released state). - The startup check only reports. Never install host software without asking.
- Image keys hash everything that goes into an image, the backend included; a tool image's key is in Building tools.
- Pin every download in
assets/'slayers/,features/,shared-tools/build.sh,oci/build.sh:<tool>_versionand<tool>_sha256_arm64/_amd64at the top, picked with the prelude'sdevvm_sha, fetched withdevvm-fetch(oci/build.sh:sha256sum). Nocurl | sh, no "latest". Upstream-checked exceptions: shared tools (MISE_LOCKED=1), Ubuntu's signedSHA256SUMS, Lima ininstall.sh. Go checks a download's SHA-256 before use. - Shared tools are read-only in VMs: whatever writes into a tool's folder (global installs, self-updates,
corepack enable,rustup component add) is redirected (~/.npm-global,go_set_gobin = false), done inassets/shared-tools/build.sh, or off. - In-VM scripts are bash 3.2-safe and shellcheck-clean (
assets/,install.sh): guard empty arrays (${a[@]+"${a[@]}"}), no associative arrays. Everything else is Go. - The one exception, the docs build's Node script:
docs/render-diagrams.mjs(mise run docs:diagrams) draws the site's diagrams with pele, pinned indocs/package.jsonand its lock and installed withnpm ci --ignore-scripts; no other build script is JavaScript, and no other npm package is installed outside mise's tools. - Docs: an easy-to-follow guide in full, joined sentences, every fact kept, written with the docs-voice skill; every behavior change updates its page in the same task, and the README stays high level (Writing docs).
- Every code change meets the codebase-standards skill (
.agents/skills/codebase-standards/): its checklist before committing, and its review when reviewing one. - Adding or changing a command follows the cli skill (
.agents/skills/cli/): its checklist, then its review. - Adding or changing a shared tool updates its page and follows Contributing's checklist:
using/toolchains.mdfor a toolchain (Adding a toolchain),using/coding-agents.md's Supported agents for an agent (Adding a coding agent). - Docs by reader: user pages name no repo paths, Go identifiers or message names; How it works explains mechanisms; Contributing has the paths and identifiers (Writing docs).
- User pages lead with doing: in
getting-started/,using/,safety/,backends/andcompared/, a task shows its command, and prose never runs to back-to-back paragraphs; one explanatory paragraph is fine, and longer mechanism moves to How it works, linked, every fact kept. - Extend the owner, don't copy it: before adding a helper, parser, path, file reader, message or table, find its owner and extend it (code with no owner yet gets one at its third copy, a judge at its second); a new owner gets a forbidigo rule or a structure-test check only when a second copy would be a bug (Contributing).
- Edit files with the editor tools, not
sed,awk,python, heredocs orcat >. - Ask first before anything outward-facing (publishing, releases, repos, pushing) and before deleting anything you didn't create.
- A task that turns out wrong or incomplete: say so and propose the change; don't quietly do something else.
- Only
internal/uiprints, functions take their caller'sctx, and every//nolintnames its linters and says why; functions stay within revive's limits (Go lint rules). - Fail by returning:
RunEreturns the error andexecutealone prints it; signals, exit codes and the run log: CLI conventions. - Only
cmd/devvmandinternal/cliimportinternal/ui; other packages print and ask through the onemsg.Reportertheir constructors take (Messages). - Arguments and flag values are checked before anything runs, with
args.go's checks, never Cobra's; a usage error exits 2 (Command arguments). - Cleanups: whatever a failure would leave (a build VM, a temp file) registers with the UI's
AddCleanupand is removed once done; one only for interrupts checksInterrupted()and stays once interrupted, as the cleanups run after the command returns. Cleanups get a fresh context. - External commands run with the UI's
LoggedCmd(ctx, step, cmd), a failure after one returned asbackend.Logged(m)(CLI conventions). - OS-specific code goes behind build tags in
internal/platform(*_darwin.go,*_linux.go,*_other.go); packages the proxy imports keep their own (internal/safefile,internal/daemon,internal/proxy,internal/landlock). - Dependencies: the depguard allowlist (cobra, pflag, cobra/doc, go-i18n, BurntSushi/toml, x/text, x/term, x/sys, x/crypto's
blake2bonly (minisign's prehash); go-internal in tests; cobra/doc's own deps never imported directly).internal/proxy,internal/landlock,internal/daemon,internal/safefile,internal/vmname,internal/leaktest,internal/memnetandinternal/redactare stdlib only. Adding one: ask. - A secret's value is a
redact.Secret: eachRevealwith a//nolint:forbidigosaying why, and a file that holds one writes it through its own wire type (Secrets in the code). - External tools are commands, never linked (
limactl,docker,security,git,chflags…); prefer the standard library to shelling out. Strings into a shell are quoted withshell.Quote. - Test seams are fields tests set (
Host,Exec,Runner,OS,Reporter…), never package vars (reassign: no package sets another's);internal/proxy's are itsserver's, which each test makes. - The structure test holds types to 24 methods, bans
func init, limits package vars, checks the layers and keeps each concern in its owner (its failure names the owner: extend that); read The structure test before raising a limit or listing an exception, and regenerate the checks on owners after changing its tables (go test ./internal/structure -run TestOwnersDoc -update). - The CLI reference is generated:
TestReferenceIsCurrentfails on a stale one (mise run cli-docs). CGO_ENABLED=0.internal/proxyandinternal/daemonare unix-only for now (syscall.Kill,Setsid,Flock).
- A backend implements
backend.Backend's four roles, declaresCapsfor every feature and returns errors, never ending the run: How a backend plugs in; a newFeaturegoes inbackend.Featuresand the feature table. - A missing feature fails, naming the VM and what to do; never fall back silently (Missing and unreviewed features).
- Every emulation is refused until reviewed: a design note in
docs/content/docs/internals/design.md, a threat check with the security-audit skill, and e2e checks proving the guarantee; then it's marked reviewed inCaps. - Backend-specific code stays in its package; what isn't (
.gitprotection, the proxy) stays out. - Lima edits only what differs: any
limactl editgives the VM new ssh host keys at its next boot, soStartcompares first and makes one edit (What devvm sets on a VM).
- Every message lives in
locales/en.toml, called through its generated function (go generate ./internal/msgafter editing), with its doc link ininternal/msg/docs.go; prose is never built withfmt(Messages). - Every question declares what answers it (
AnsweredBy,RefusedWith), and callers never check for a terminal (Questions). - Messages use the docs voice, only shorter: the docs-voice skill's Messages and Terms rules; the mechanism goes in the doc link.
- Tests check which message and with what, never its wording (Names mode).
- New logic needs a test: Go table tests next to the code, and CLI tests (testscript against the built binary and the stubs); neither touches the Keychain, real VMs or your folders (Tests).
- Never touch VMs, images or containers devvm's tests didn't make: your own stay as they are. Manual runs:
DEVVM_LIMA_HOME=~/.lt LIMA_HOME=~/.lt XDG_DATA_HOME=/tmp/x/data XDG_CONFIG_HOME=/tmp/x/config DEVVM_SECRET_SERVICE=devvm-sandbox-test(devvm's Lima home is$XDG_DATA_HOME/devvm/limaunlessDEVVM_LIMA_HOME;LIMA_HOMEis for yourlimactl). Add aconfig.tomlwithfeatures = []and pass--network TIERso nothing prompts. Delete test Keychain items. Never use your own tokens or logins: a network-policy VM reads its agent's login file fromHOME, so give it its own (the Keychain needs the realHOME: test it apart). - Timeouts and lifecycles are tested in a
testing/synctestbubble on fakes in memory (memnet, the seams' fields), never by sleeping on the real clock; each kind keeps one real-process test (Time and lifecycles). - Goroutines: a package that starts them calls
leaktest.Mainin itsTestMain, and each function that does is in the structure test'sgoroutineSites, with what waits for them ordetached:and why (Goroutine leaks). - End-to-end:
mise run e2e -- --only SECTIONSin the background for what changed,--frombefore mergingassets/or--fromchanges (End-to-end tests). - Linux hosts:
LIMA_HOME=~/.lt-linux-go, VMlinuxhost, set up as Linux hosts says, apart from any Lima home of your own. - Unreviewed emulations are checked through
DEVVM_UNREVIEWED=backend:feature, in test builds only (Unreviewed emulations). - Delete test VMs and temp files afterwards. Long builds run in the background. Tests that
chflagsreal files unlock them (chflags -R nouchg), only in their own temp folders. - The testscript runner stops the sandbox's proxies (
pkill -fon_proxy -configin the sandbox, then_proxy-child -for): the stub hostagent is gone before they look, so they'd wait 15 minutes. It also stops the sandbox's port forwarders, link sessions and stub ssh masters. limactl shellreads stdin: give it none unless the input is meant for it.- Boot problems: read
<devvm's Lima home>/<vm>/serialv.log(and its.1, past 10 MiB) before restarting; every start overwrites it.
- Lima
vz: raw disks only; clones are APFS copy-on-write (duovercounts). Direct kernel boot needs an uncompressed arm64Image. Stopping sends a GPIO power key, so guests needgpio_keys, or Lima hard-kills them after 30 s. Lima can't shrink disks. virtiofs tags arelima-<hash>. The project mount is/.vol/<dev>/<ino>at its path; vz serves a share by the path it had at the start, so a rename while it runs gives "Operation not permitted". After root touches a directory on a virtiofs mount, the guest sees it as root's for a few seconds (git: "dubious ownership").mounts: []doesn't remove the home mount frombase: template:…: pass--mount-none(or--mount-only) tolimactl create/clone. limactl list --jsonfills in the config: mounts getmountPoint, port forwards aguestIP(127.0.0.1) and host side; compare only what devvm set.--setapplies after--mount-none.limactl createdownloads the image at once (no dry run).limactl shellquotes each argument for the guest's shell, soExecpassessh -cand oneshell.QuoteJoinstring. QEMU's guestfwd command goes through/bin/sh -ctoo, commas doubled.- The ssh socket path limit (103 characters at most: macOS's 104 include the NUL) bounds VM names (
NameMax). - Linux hosts (QEMU): mounts are 9p, and a 9p share mounts once per guest. Debian's tmpfs
/tmphides anything mounted below it during boot. Project VMs' qcow2 disks are overlays of their image's, so never start an image VM or write its disk after it's built. - Shared tools: mise rewrites
latest/24/ltslinks in a tool's folder after any install, so those folders are local in the VM; only version folders are mounted. - Lima can report a failed start for a VM that is running but degraded; starting tolerates it.
- Linux's
pgrep -fmatches the shell running it (procps), so e2e's patterns are written[_]proxy. mise skips minisign on linux/arm64 (no build).
- One commit when each task is complete, its docs and review included. Conventional Commits:
type(scope): summary, typesfeat,fix,docs,test,refactor,build,ci,chore. - Don't commit until the gate passes, with whatever
mise run fmtchanged in the commit. - Task IDs from any tracker never go in commit messages, code comments or docs.
- AGENTS.md stays short: one line per path or rule. Inventories (functions, messages, test names) go in the commit message, not here.