# devvm Documentation

> Technical documentation and CLI/configuration reference for devvm, an isolated per-project virtual machine sandbox on Lima with read-only shared toolchains, coding agents, and host-enforced network and Git protections.

This is a Grok-Wiki source-grounded repository documentation set. Use the complete Markdown link when an agent needs the full repo context.

## Context Links

- [Complete Markdown docs](https://grok-wiki.com/public/docs/devvmhq-devvm-4242986d2853/llms-full.txt)
- [Complete Markdown alias](https://grok-wiki.com/public/docs/devvmhq-devvm-4242986d2853.md)
- [Human interactive docs](https://grok-wiki.com/public/docs/devvmhq-devvm-4242986d2853)
- [GitHub repository](https://github.com/devvmhq/devvm)

## Repository

- Repository: devvmhq/devvm

- Generated: 2026-11-07T23:01:02.161Z
- Updated: 2026-11-08T01:21:57.983Z
- Runtime: Antigravity CLI
- Format: Documentation
- Pages: 23

## Pages

- [Overview](https://grok-wiki.com/public/docs/devvmhq-devvm-4242986d2853/pages/01-overview.md): Public entry points, per-project VM sandbox architecture, runtime assumptions, and primary documentation routes.
- [Installation](https://grok-wiki.com/public/docs/devvmhq-devvm-4242986d2853/pages/02-installation.md): Install devvm on macOS and Linux via Homebrew or the signed release installer, verify Minisign signatures, and validate host readiness with devvm doctor.
- [Quickstart](https://grok-wiki.com/public/docs/devvmhq-devvm-4242986d2853/pages/03-quickstart.md): Configure initial defaults with devvm setup, launch a project VM with auto-detected toolchains and agents, and verify isolation in the guest shell.
- [VM lifecycle and state](https://grok-wiki.com/public/docs/devvmhq-devvm-4242986d2853/pages/04-vm-lifecycle-and-state.md): How project paths map to VM names and 8-hex hashes, state persistence in vm.json, layout version checks, and in-place vs. remake transitions.
- [Images, layers, and content keys](https://grok-wiki.com/public/docs/devvmhq-devvm-4242986d2853/pages/05-images-layers-and-content-keys.md): Deterministic SHA-256 key computation for base images, built-in and custom layers (docker, nix, desktop), and read-only EROFS shared tool images.
- [Network tiers and host proxy](https://grok-wiki.com/public/docs/devvmhq-devvm-4242986d2853/pages/06-network-tiers-and-host-proxy.md): Traffic confinement across allowlist, open, and offline tiers, host-side TLS SNI and HTTP inspection via devvm _proxy, and per-VM CA rotation.
- [Host and Git isolation boundaries](https://grok-wiki.com/public/docs/devvmhq-devvm-4242986d2853/pages/07-host-and-git-isolation-boundaries.md): Read-only .git mount protection, symlink and hardlink containment, set-id file audits, secret placeholder injection, and isolated repo clones.
- [Backend contract and Lima driver](https://grok-wiki.com/public/docs/devvmhq-devvm-4242986d2853/pages/08-backend-contract-and-lima-driver.md): The four-role backend.Backend interface (Host, Images, Machines, Housekeeping), capability requirement checks (Caps), and the Lima driver implementation.
- [Configure coding agents and credentials](https://grok-wiki.com/public/docs/devvmhq-devvm-4242986d2853/pages/09-configure-coding-agents-and-credentials.md): Run 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.
- [Manage toolchains and custom layers](https://grok-wiki.com/public/docs/devvmhq-devvm-4242986d2853/pages/10-manage-toolchains-and-custom-layers.md): Add, remove, and update shared mise toolchains (node, python, rust, go, dotnet) and author custom image layers with network policies via devvm layer new.
- [Use devcontainer.json and OCI base images](https://grok-wiki.com/public/docs/devvmhq-devvm-4242986d2853/pages/11-use-devcontainer.json-and-oci-base-images.md): Translate .devcontainer/devcontainer.json properties into VM plans and build bootable VM base images from OCI/Docker container references with --from.
- [Connect VMs with links, groups, and port forwards](https://grok-wiki.com/public/docs/devvmhq-devvm-4242986d2853/pages/12-connect-vms-with-links-groups-and-port-forwards.md): Forward guest ports to host 127.0.0.1, publish ports and link VMs under *.devvm hostnames, and join VMs into mutually reachable groups.
- [Connect SSH, VS Code, and VNC desktop](https://grok-wiki.com/public/docs/devvmhq-devvm-4242986d2853/pages/13-connect-ssh-vs-code-and-vnc-desktop.md): Use generated ~/.ssh/config entries, configure per-VM SSH agents, launch VS Code Remote-SSH via devvm code, and connect to the VNC desktop relay.
- [Isolate work with repository clones](https://grok-wiki.com/public/docs/devvmhq-devvm-4242986d2853/pages/14-isolate-work-with-repository-clones.md): Create VMs with independent Git clones using devvm --clone, switch existing VMs between mounted folders and clones, and fetch VM branches to the host.
- [CLI reference: VM and workspace commands](https://grok-wiki.com/public/docs/devvmhq-devvm-4242986d2853/pages/15-cli-reference-vm-and-workspace-commands.md): Syntax, flags, exit codes, and examples for devvm (up), ls, restart, stop, update, rm, adopt, size, ports, host, code, desktop, and history.
- [CLI reference: network, security, and agent commands](https://grok-wiki.com/public/docs/devvmhq-devvm-4242986d2853/pages/16-cli-reference-network-security-and-agent-commands.md): Syntax, subcommands, and flags for devvm network, secret, agent, git-protect, clone, ssh-agent, link, and group.
- [CLI reference: images, storage, and host commands](https://grok-wiki.com/public/docs/devvmhq-devvm-4242986d2853/pages/17-cli-reference-images-storage-and-host-commands.md): Syntax, subcommands, and flags for devvm build, rebuild, images, layer, tools, space, gc, retention, setup, doctor, upgrade, completion, and limactl.
- [Configuration (config.toml) and --json schema reference](https://grok-wiki.com/public/docs/devvmhq-devvm-4242986d2853/pages/18-configuration-config.toml-and---json-schema-reference.md): Complete reference for ~/.config/devvm/config.toml keys, settings.json precedence, environment variables, state directory layout, and version 1 --json payloads.
- [Diagnose host, boot, and SSH failures](https://grok-wiki.com/public/docs/devvmhq-devvm-4242986d2853/pages/19-diagnose-host-boot-and-ssh-failures.md): Resolve devvm doctor host problems, Ubuntu cloud image boot fallbacks, SSH host-key verification errors, run logs, and moved project directories with devvm adopt.
- [Troubleshoot network policies, CAs, and disk space](https://grok-wiki.com/public/docs/devvmhq-devvm-4242986d2853/pages/20-troubleshoot-network-policies-cas-and-disk-space.md): Inspect blocked requests with devvm network log, configure corporate HTTP/HTTPS proxies and custom CAs in ~/.config/devvm/ca, and recover disk space.
- [Manage disk retention, garbage collection, and upgrades](https://grok-wiki.com/public/docs/devvmhq-devvm-4242986d2853/pages/21-manage-disk-retention-garbage-collection-and-upgrades.md): Configure automatic retention policies for run logs, agent history exports, unused tools, orphaned state, and Nix caches, and upgrade devvm installations.
- [Codebase invariants, testscript stubs, and E2E suite](https://grok-wiki.com/public/docs/devvmhq-devvm-4242986d2853/pages/22-codebase-invariants-testscript-stubs-and-e2e-suite.md): Enforce single-owner and layer rules in internal/structure, write deterministic CLI testscript tests with internal/stubtest, and run real-VM E2E suites.
- [Pinning, release signing, and supply-chain verification](https://grok-wiki.com/public/docs/devvmhq-devvm-4242986d2853/pages/23-pinning-release-signing-and-supply-chain-verification.md): Maintain SHA-256 download pins and Ubuntu PGP archive checks with scripts/bump.sh, build and sign releases with Minisign, and publish artifacts.

## Source Files

- `.goreleaser.yaml`
- `assets/base.yaml`
- `assets/oci/build.sh`
- `assets/prelude.sh`
- `assets/shared-tools/build.sh`
- `assets/shared-tools/mise.toml`
- `cmd/devvm/main.go`
- `install.sh`
- `internal/agentlogin/restore.go`
- `internal/backend/backend.go`
- `internal/backend/caps.go`
- `internal/backend/guard.go`
- `internal/backend/lima/check.go`
- `internal/backend/lima/lima.go`
- `internal/backend/lima/oci.go`
- `internal/backend/lima/seatbelt.go`
- `internal/backend/lima/start.go`
- `internal/build/build.go`
- `internal/build/layer.go`
- `internal/cli/agent.go`
- `internal/cli/agentlogin.go`
- `internal/cli/app.go`
- `internal/cli/args.go`
- `internal/cli/build.go`
- `internal/cli/clone.go`
- `internal/cli/code.go`
- `internal/cli/desktop.go`
- `internal/cli/doctor.go`
- `internal/cli/flags.go`
- `internal/cli/gc.go`
- `internal/cli/gitprotect.go`
- `internal/cli/group.go`
- `internal/cli/images.go`
- `internal/cli/json.go`
- `internal/cli/layer.go`
- `internal/cli/link.go`
- `internal/cli/ls.go`
- `internal/cli/network.go`
- `internal/cli/ports.go`
- `internal/cli/restart.go`
- `internal/cli/retention.go`
- `internal/cli/rm.go`
- `internal/cli/root.go`
- `internal/cli/script_test.go`
- `internal/cli/secret.go`
- `internal/cli/setup.go`
- `internal/cli/size.go`
- `internal/cli/space.go`
- `internal/cli/sshagent.go`
- `internal/cli/tools.go`
- `internal/cli/up.go`
- `internal/cli/update.go`
- `internal/cli/upgrade.go`
- `internal/desktop/desktop.go`
- `internal/desktop/relay.go`
- `internal/devcontainer/devcontainer.go`
- `internal/devcontainer/reread.go`
- `internal/fetch/fetch.go`
- `internal/from/from.go`
- `internal/from/registry.go`
- `internal/gitprotect/gitprotect.go`
- `internal/gitprotect/own.go`
- `internal/hostgit/hostgit.go`
- `internal/hostsafety/hostsafety.go`
- `internal/image/key.go`
- `internal/image/recipe.go`
- `internal/image/tool.go`
- `internal/netpolicy/log.go`
- `internal/netpolicy/netpolicy.go`
- `internal/netpolicy/rules.go`
- `internal/netpolicy/tier.go`
- `internal/paths/dirs.go`
- `internal/paths/vm.go`
- `internal/ports/ports.go`
- `internal/project/project.go`
- `internal/proxy/links.go`
- `internal/proxy/policy.go`
- `internal/proxy/proxy.go`
- `internal/proxy/secrets.go`
- `internal/proxy/sni.go`
- `internal/secrets/secrets.go`
- `internal/settings/companyproxy.go`
- `internal/settings/config.go`
- `internal/settings/retention.go`
- `internal/settings/settings.go`
- `internal/settings/values.go`
- `internal/sshagent/sshagent.go`
- `internal/sshconfig/sshconfig.go`
- `internal/state/layout.go`
- `internal/state/vm.go`
- `internal/structure/owners_test.go`
- `internal/structure/rules_test.go`
- `internal/structure/structure_test.go`
- `internal/stubtest/stubtest.go`
- `internal/tools/share.go`
- `internal/tools/tools.go`
- `internal/trust/ca.go`
- `internal/trust/trust.go`
- `internal/ubuntu/archive.go`
- `internal/ubuntu/pgp.go`
- `internal/ui/runlog.go`
- `internal/upgrade/install.go`
- `internal/upgrade/minisign.go`
- `internal/upgrade/source.go`
- `internal/upgrade/upgrade.go`
- `internal/vm/agentimport.go`
- `internal/vm/agentlogin.go`
- `internal/vm/agents.go`
- `internal/vm/agentsave.go`
- `internal/vm/clone.go`
- `internal/vm/detect.go`
- `internal/vm/devcontainer.go`
- `internal/vm/env.go`
- `internal/vm/exports.go`
- `internal/vm/finder.go`
- `internal/vm/groups.go`
- `internal/vm/housekeep.go`
- `internal/vm/lifecycle.go`
- `internal/vm/links.go`
- `internal/vm/move.go`
- `internal/vm/parts.go`
- `internal/vm/remake.go`
- `internal/vm/start.go`
- `internal/vm/tools.go`
- `internal/vm/up.go`
- `internal/vmname/vmname.go`
- `internal/vmssh/checked.go`
- `internal/vmssh/forwards.go`
- `internal/vmssh/hostkeys.go`
- `mise.toml`
- `packaging/homebrew/devvm.rb`
- `packaging/key.go`
- `README.md`
- `scripts/bump.sh`
- `scripts/publish.sh`
- `scripts/release.sh`
- `tests/e2e/sandbox_test.go`