Create an Isolated Development VM for Every Project with devvm

What is devvm?

devvm creates an isolated virtual machine for each project folder. The VM contains the toolchains your project needs and provides a sandbox where you or a coding agent can work without installing the agent directly on your host machine.

Each VM runs through Lima. By default, devvm mounts only the selected project folder and exposes it inside the VM at the same path used on the host. Running devvm in that folder again reopens the same VM.

Key features

• One VM per project: Each project folder receives its own isolated environment.
• Automatic toolchain detection: devvm examines project files to determine required toolchains. For example, a project containing package.json receives Node.js tooling.
• Coding-agent support: Claude Code, Codex, opencode, and pi can run inside the VM with their settings, skills, and MCP servers.
• Controlled networking: New VMs use an allowlist network tier by default and can reach only approved hosts.
• Host-side secrets: Credentials such as GitHub and Claude Code tokens remain on the host across every network tier.
• Reusable images: VMs are copied from a base image, while toolchains are shared read-only between VMs. After the initial setup, new VMs can start in seconds.
• Optional layers: Built-in layers include docker, nix, and desktop. You can also create your own layer.
• Clone mode: A VM can work in its own Git clone instead of mounting your host working tree.

System requirements

devvm supports macOS 13 or newer and Linux on arm64 or x86_64. It requires Lima 2.2 or newer and the relevant Lima requirements. The project is tested on Apple silicon Macs and Linux systems using arm64 and x86_64, but it has not yet been tested on Intel Macs.

Install devvm

Install on macOS with Homebrew

The Homebrew formula installs devvm and Lima:

brew trust --formula devvmhq/tap/devvm
brew install devvmhq/tap/devvm

Install on Linux

Run the official installation script:

curl -fsSL https://github.com/devvmhq/devvm/releases/latest/download/install.sh | bash

The script also works on macOS. Before installing Lima, QEMU, or access to /dev/kvm, it asks for confirmation.

Each release is signed with the devvm minisign key RWSjzFsn7ETaijKJ2y7F4DtZobXmyv+LmdclJwZP/KmAkLUwOCzWF/2b. Follow the install-script verification guide if you want to verify the download before running it.

Check your installation

After installation, run the diagnostic command:

devvm doctor

This checks what devvm needs on your computer and explains how to obtain anything that is missing. See the complete installation guide for all requirements and installer options.

Create your first project VM

1. Open your project folder. In a terminal, change to the directory containing your project.
2. Run devvm. Review the proposed VM configuration and confirm it.
3. Work inside the VM. devvm opens a shell whose prompt begins with (devvm).

cd ~/some-project
devvm

devvm detects the toolchains requested by the project's files. Before creating the VM, you can also customize its toolchains, coding agents, layers, network tier, and size.

The first run asks a few questions that establish defaults for new VMs and the base image. These include the default VM size, coding agents, and optional base-image extras. Building the base image takes a few minutes once; later project VMs generally start in seconds.

Reopen the same VM

Return to the project folder and run the same command:

cd ~/some-project
devvm

Because a project folder keeps its own VM, devvm reopens the existing environment rather than creating an unrelated one.

Run a coding agent

Once the VM shell opens, start a supported agent from inside it. For example, run Claude Code with:

claude

This keeps the coding agent inside the sandbox instead of installing it on your host. devvm stores supported agents' settings and logins in its own store.

Log in to Claude Code

Before starting Claude Code for the first time, initiate its login from the VM:

devvm agent login claude

The login is retained on your machine. Consult the Claude Code login guide for details.

Import an existing agent configuration

If you already use a supported coding agent on the host, devvm can copy its existing configuration into its own store:

devvm agent import

This is intended for bringing across settings used by an existing local agent. The supported integrations include Claude Code, Codex, opencode, and pi.

Protect your working tree with clone mode

In the default mode, the host editor and VM share the mounted project files. Changes made inside the VM therefore appear in the same working tree.

For stronger separation, start devvm with --clone. The VM then receives its own repository clone, preventing processes inside it from touching the host working tree or its .git directory.

devvm --clone

After work is committed inside the VM, fetch it on the host through the devvm remote:

git fetch devvm

Fetched branches are available under names such as devvm/main. Review the difference before merging:

git log -p main..devvm/main

This workflow makes the VM's work reach your repository only when you explicitly fetch it. See Working on a clone for the complete workflow.

Advanced configuration tips

Choose toolchains deliberately

Automatic detection provides a useful starting point, but review the proposed setup before creating a VM. The creation flow lets you customize its toolchains when the detected selection does not match your intended environment. The toolchains documentation lists supported options.

Add environment layers

Use the built-in docker, nix, or desktop layers when a project requires those capabilities. To begin defining a custom layer, use:

devvm layer new

Review the layers documentation before customizing images.

Review network access

New VMs receive the allowlist network tier by default. Keep the list of accessible hosts as narrow as practical, especially when running an autonomous coding agent. Other network tiers are documented in the network safety guide.

Understand the sandbox boundary

A VM reduces risk, but it does not close every security gap. Understand what the VM can access, avoid exposing unnecessary resources, and review generated changes before accepting them. Read Staying safe before trusting a VM with an important project.

Consult the CLI reference

For commands, flags, and arguments beyond this tutorial, use the official CLI reference. The broader usage documentation also covers ports, VM sizing, links between VMs, SSH, editors, images, and troubleshooting.

Conclusion

devvm provides a practical way to give every project its own isolated development environment. Install it, validate the host with devvm doctor, run devvm from a project directory, and start your coding agent inside the resulting shell. For sensitive work, combine restricted networking with devvm --clone and review fetched changes before merging them.