nixos-vm-template on blog.rymcg.tech

NixOS VMs part 4: Managing VMs with home-manager and sway-home

Thu, 29 Jan 2026 00:00:01 -0600

This is part 4 of a series on nixos-vm-template:

Running code agents in an immutable NixOS VM
Bootstrapping a Docker server with immutable NixOS on Proxmox
Mutable VMs are cool too
Managing VMs with home-manager and sway-home (this post)

The previous posts covered creating and managing VMs with nixos-vm-template. But how do you actually integrate it into your daily workflow on your workstation? This post covers using home-manager to set up the VM tooling, create shell aliases with tab completion, and manage updates through the Nix ecosystem.

What is home-manager?

Home Manager is a tool for managing user environments using the Nix package manager. Instead of manually installing programs and editing dotfiles, you declare what you want in a Nix configuration file, and home-manager builds and activates that environment.

The key benefits:

Declarative: Your entire user environment is defined in code
Reproducible: The same configuration produces the same result on any machine
Rollback: Every configuration change creates a new “generation” you can switch back to
Isolated: Packages are installed in the Nix store, not globally

Home-manager works on any Linux distribution - you don’t need NixOS. You just need the Nix package manager installed.

What is sway-home?

sway-home is a home-manager configuration that sets up a complete development environment. It includes:

Shell configuration (bash, with aliases and completions)
Editor setup (Emacs)
Development tools (git, ripgrep, just, etc.)
Window manager config (Sway, if you’re on Wayland)
And relevantly: nixos-vm-template integration

When you activate sway-home with home-manager, you get all of this configured and ready to use. The configuration is modular - you can enable or disable components as needed.

The hm-* commands

Sway-home provides shell aliases for common home-manager operations. These are the commands you’ll use to manage your environment:

Command	What it does
`hm-switch`	Rebuild and activate your home-manager configuration
`hm-update`	Update flake.lock to fetch latest versions of all inputs
`hm-upgrade`	Update + switch in one step
`hm-generations`	List your configuration history (each activation is a “generation”)
`hm-rollback`	Revert to the previous generation if something breaks
`hm-metadata`	Show the git revisions of all flake inputs
`hm-pull`	Git pull the sway-home repository

The typical workflow: edit your configuration, run hm-switch to apply it. If you want the latest upstream changes from sway-home and its dependencies (including nixos-vm-template), run hm-upgrade.

The nixos-vm-template module

One of sway-home’s modules, nixos-vm-template.nix, integrates the VM tooling directly into your shell. It does three things:

Symlinks the nixos-vm-template repository into ~/nixos-vm-template (bound to the nix store, so it’s read-only but versioned)
Creates a default environment file at ~/.config/nixos-vm-template/env with XDG-compliant paths
Sets up the vm shell alias with tab completion

After activating home-manager, you get a vm command that works like this:

vm list                    # List all VMs
vm create                  # Create a VM (interactive wizard)
vm ssh myvm                # SSH in
vm upgrade myvm            # Upgrade to new image

The vm create command runs an interactive configuration wizard that prompts for the VM name, profiles, memory, CPUs, disk size, and network mode. After configuration, it builds the image, creates the VM, and starts it automatically.

The vm command operates on the local machine’s libvirt backend.

The alias is defined using the _justfile_alias function, which wraps just with a specific Justfile and environment file:

_justfile_alias vm \
  "$HOME/nixos-vm-template/Justfile" \
  "$HOME/.config/nixos-vm-template/env"

This gives you full tab completion for recipes and machine names. Tab completion works for commands like vm ssh, vm status, and vm upgrade that take a VM name as an argument.

The nix store binding

Here’s an important detail: ~/nixos-vm-template is a symlink into the nix store, not a regular git clone. The module declares:

home.file."nixos-vm-template".source = inputs.nixos-vm-template;

This means the repository is read-only. You can’t edit files there directly. The benefit is reproducibility - your VM tooling version is pinned to a specific commit in the sway-home flake.lock.

The downside is that changes to nixos-vm-template upstream won’t appear until you update and rebuild. More on that below.

Where things live

The environment file sets up XDG-compliant paths:

Path	Purpose
`~/.config/nixos-vm-template/machines/`	Machine configs (identity files, profiles)
`~/.config/nixos-vm-template/libvirt/`	Libvirt XML templates
`~/.config/nixos-vm-template/env`	Backend configuration
`~/.local/share/nixos-vm-template/`	Built images and VM disks

Your machine configs are in ~/.config, so they’re easy to back up and track. The large image files go in ~/.local/share where they won’t clutter your config backups.

Updating nixos-vm-template

Since ~/nixos-vm-template is bound to the nix store, you need to update home-manager to get new versions:

hm-update    # Update flake.lock (fetches latest nixos-vm-template)
hm-switch    # Rebuild and activate

After this, ~/nixos-vm-template points to the new version and all vm commands use the updated code.

To see what version you’re running:

hm-metadata

This shows the git revisions of all flake inputs, including nixos-vm-template.

Home-manager inside the VM

So far we’ve talked about home-manager on your host workstation - managing your shell, your tools, and the nixos-vm-template integration. But you can also run home-manager inside the VM to manage the user environment there.

To get home-manager inside a VM, include the home-manager profile when creating it. Run vm create and select the home-manager profile along with your other desired profiles (e.g., dev, docker).

The home-manager profile installs sway-home’s configuration inside the VM, giving you the same shell setup, editor config, and tools. This is useful for development VMs where you want a consistent environment.

The profile works in both immutable and mutable VMs, but with slightly different behavior:

In immutable VMs, a custom activation service creates symlinks from /home/<user> to the nix store. This handles the complexity of the read-only root and bind-mounted home directories.
In mutable VMs, standard home-manager activation runs. The filesystem is writable, so home-manager just does its normal thing.

Note that the dev profile includes basic development tools (neovim, tmux, etc.) but does not include home-manager. If you want the full sway-home experience inside the VM, add the home-manager profile explicitly.

Creating a Proxmox alias

The vm alias points at libvirt by default. If you also have a Proxmox server, you can create a separate alias for it.

First, create an environment file for your Proxmox backend:

cat > ~/.config/nixos-vm-template/env-pve << 'EOF'
BACKEND=proxmox
PVE_HOST=pve
PVE_NODE=pve
PVE_STORAGE=local-zfs
PVE_DISK_FORMAT=raw
PVE_BRIDGE=vmbr0
OUTPUT_DIR=$HOME/.local/share/nixos-vm-template
MACHINES_DIR=$HOME/.config/nixos-vm-template/machines-pve
LIBVIRT_DIR=$HOME/.config/nixos-vm-template/libvirt
EOF

Note the separate MACHINES_DIR - this keeps Proxmox machine configs separate from libvirt ones, avoiding confusion.

Then add the alias to your shell config (e.g., ~/.bashrc or the sway-home config/bash/alias.sh):

_justfile_alias pve \
  "$HOME/nixos-vm-template/Justfile" \
  "$HOME/.config/nixos-vm-template/env-pve"

Now you have two aliases:

vm create       # Creates on local libvirt (interactive)
pve create      # Creates on Proxmox server (interactive)

Both use the same nixos-vm-template codebase and run the same interactive configuration wizard, but target different backends with different configurations.

Disk space and garbage collection

VM images accumulate in ~/.local/share/nixos-vm-template/. Each profile combination produces an image (typically 3-4 GB), and each VM has its own /var disk.

To see disk usage:

du -sh ~/.local/share/nixos-vm-template/

To clean up old images (keeping currently-used ones):

vm clean

For the nix store itself, home-manager profiles accumulate over time. To reclaim space:

nix-collect-garbage --delete-older-than 30d

This removes store paths that aren’t referenced by any generation newer than 30 days. Be careful - this includes home-manager generations, so you’ll lose the ability to roll back to older configs.

To see how much space you’d reclaim:

nix-store --gc --print-dead

The full workflow

Here’s what a typical session looks like:

# Update everything
hm-pull && hm-upgrade

# Check what version of nixos-vm-template you're running
hm-metadata | grep nixos-vm-template

# Create a VM for a new project (interactive wizard)
vm create
# Enter: project-foo, claude/dev/docker/home-manager, 8192, 4, etc.
# The VM starts automatically after creation

# Work on the project...
vm ssh user@project-foo
# ... do things ...

# Later, upgrade the VM to pick up profile changes
vm upgrade project-foo

# Deploy to production on Proxmox (interactive wizard)
pve create
# Enter: project-foo, docker, etc.
# The VM starts automatically

# Clean up old images
vm clean
nix-collect-garbage --delete-older-than 7d

Conclusion

The sway-home integration turns nixos-vm-template into a first-class shell tool. The vm alias gives you quick access to all VM operations with tab completion, and the home-manager binding ensures reproducible tooling versions across machines. Adding backend-specific aliases like pve lets you manage VMs across multiple hypervisors from a single workflow.

The key things to remember:

~/nixos-vm-template is read-only; run hm-upgrade to get updates
Machine configs live in ~/.config/nixos-vm-template/machines/
Use nix-collect-garbage periodically to reclaim disk space
Create separate aliases and machine directories for each backend

NixOS VMs part 3: Mutable VMs are cool too

Thu, 29 Jan 2026 00:00:00 -0600

This is part 3 of a series on nixos-vm-template:

Running code agents in an immutable NixOS VM
Bootstrapping a Docker server with immutable NixOS on Proxmox
Mutable VMs are cool too (this post)
Managing VMs with home-manager and sway-home

The nixos-vm-template project has, so far, been only about immutable VMs: read-only root filesystem, separate /var disk for state, atomic upgrades from the host. It’s a nice model. But sometimes you just want a normal NixOS system that you can poke at from the inside.

This post introduces mutable VM support - a single read-write disk with the full nix toolchain available. Same profiles, same tooling, different architecture.

Why mutable?

Immutable VMs are great for production-like workloads. The OS is locked down, upgrades happen by replacing the boot image, and you can’t accidentally rm -rf / your way into trouble. But there are cases where that rigidity gets in the way:

NixOS experimentation: You want to run nixos-rebuild switch inside the VM to test configuration changes interactively.
Nix development: You’re working on Nix expressions and need nix build, nix develop, and friends to actually work.
Learning NixOS: You want a sandbox where you can break things and fix them without rebuilding images on the host.
Quick iterations: Sometimes you just want to nix profile install something and see if it works.

Immutable VMs don’t support any of this. The nix toolchain requires a writable /nix/store with a valid database, and that’s fundamentally incompatible with a read-only root. The old workaround was a nix profile that used overlayfs to make /nix writable, but it was fragile and didn’t survive reboots cleanly.

Mutable VMs solve this properly: one disk, fully writable, standard NixOS.

The tradeoffs

Nothing is free. Here’s what you give up:

Feature	Immutable	Mutable
Root filesystem	Read-only	Read-write
Disk layout	Boot + var (two disks)	Single disk
Thin provisioning	Yes (QCOW2 backing files)	No (full copy)
Host upgrades	`just upgrade`	Not supported
Corruption resistance	High (root can’t be modified)	Normal
Nix commands	Limited	Full toolchain

The big one is thin provisioning. With immutable VMs, multiple VMs sharing the same profile share a single base image - each VM’s boot disk is just a delta. With mutable VMs, each one gets a full copy of the image. If your base image is 4GB, every mutable VM is at least 4GB on disk.

The other big one is upgrades. You can’t run just upgrade on a mutable VM. The whole point is that the system is managed from inside, so you SSH in and run nixos-rebuild switch like you would on any NixOS machine.

Creating a mutable VM

Run the interactive create command:

just create

When prompted, enter the VM name and select your desired profiles (e.g., docker, dev). The wizard will also ask whether you want a mutable or immutable VM - select mutable mode when prompted.

Alternatively, you can enable mutable mode on an existing machine config:

just mutable myvm      # prompts to enable/disable
just recreate myvm     # applies the change

The just mutable command shows you the current status, explains what mutable mode does, and asks for confirmation. If you enable it, the next just create or just recreate will build a mutable image.

This works on both backends - just set BACKEND=proxmox in your .env file or environment before running just create.

What’s different inside

A mutable VM looks like a normal NixOS system. The root filesystem is ext4 on a single disk, /nix is writable, and you can run any nix command you want. But the VM still gets its identity from the machine config files - hostname, SSH keys, firewall ports - just stored in different locations.

File	Immutable location	Mutable location
Hostname	`/var/identity/hostname`	`/etc/hostname`
Machine ID	`/var/identity/machine-id`	`/etc/machine-id`
SSH authorized keys	`/var/identity/*_authorized_keys`	`/etc/ssh/authorized_keys.d/*`
Firewall ports	`/var/identity/tcp_ports`	`/etc/firewall-ports/tcp_ports`
Root password hash	`/var/identity/root_password_hash`	`/etc/root_password_hash`

On boot, systemd services read these files and apply them. The firewall-ports.service opens the configured ports; the root-password.service sets the root password from the hash file. Same end result, different plumbing.

Upgrading a mutable VM

Since the system is writable, you upgrade it the normal NixOS way:

just ssh admin@myvm

# Inside the VM
sudo nixos-rebuild switch --upgrade

Or if you have a flake:

sudo nixos-rebuild switch --flake github:you/your-config#myvm

You can also use nix-env for user-level package management, though that’s generally not recommended on NixOS.

If you try just upgrade on a mutable VM, it will error out and tell you to upgrade from inside instead. This is intentional - the host doesn’t own the system configuration anymore, the VM does.

Firewall and passwords

The machine config files (machines/<name>/tcp_ports, udp_ports, root_password_hash) are copied into the image at creation time. If you want to change them:

Edit the files in machines/<name>/
Run just recreate <name>

Or just edit them directly inside the VM:

# Add a new allowed port in the running VM:
echo "8080" | sudo tee -a /etc/firewall-ports/tcp_ports
sudo systemctl restart firewall-ports

# Change root password
sudo passwd root

Changes made inside the VM persist across reboots but won’t be reflected in the machine config on the host. If you recreate the VM, you’ll get whatever’s in the host-side config.

When to use which

Use immutable VMs when:

Running services that don’t need system-level changes
You want atomic, host-driven upgrades
Multiple VMs share the same base image
You value the corruption resistance of a read-only root

Use mutable VMs when:

Experimenting with NixOS configuration
Developing Nix expressions
Learning NixOS interactively
You need nix build, nix develop, or nixos-rebuild

Both types use the same profiles, the same machine config structure, and the same just commands for everything except upgrades. You can have some VMs immutable and others mutable in the same setup.

Conclusion

Mutable VMs fill a gap that immutable VMs couldn’t: interactive NixOS development and experimentation. You lose thin provisioning and host-driven upgrades, but you gain a fully functional nix toolchain and the ability to iterate on system configuration without rebuilding images.

For production-like workloads, immutable is still the way to go. For learning, development, and experimentation, mutable VMs are cool too.

NixOS VMs part 2: Bootstrapping a Docker server with immutable NixOS on Proxmox

Fri, 23 Jan 2026 23:00:00 -0600

This is part 2 of a series on nixos-vm-template:

Running code agents in an immutable NixOS VM
Bootstrapping a Docker server with immutable NixOS on Proxmox (this post)
Mutable VMs are cool too
Managing VMs with home-manager and sway-home

In the last post I described running AI code agents inside immutable NixOS VMs using libvirt on a laptop. That setup works well for local development, but sometimes you want to deploy VMs on actual infrastructure - a Proxmox server sitting in a closet, a rack, or someone else’s datacenter.

The nixos-vm-template project now supports multiple backends. You build the same NixOS images locally on your workstation, you run the same commands as you would with libvirt, and you get the same immutable VMs - the only difference is where they land. This post walks through using the Proxmox backend to bootstrap a Docker server VM.

Why Proxmox?

Libvirt is fine for laptops and ‘sworkstations’. You run just create, the VM shows up locally, and you SSH into it. But if you want VMs running 24/7 on dedicated hardware, you probably have a hypervisor already, and in the homelab world that hypervisor is usually Proxmox.

The new Proxmox backend builds images locally with Nix, then ships them to your PVE node over SSH. No Proxmox API tokens, no web UI clicking, no cloud-init templates. Just NixOS config, SSH, and qm.

The backend abstraction

The tool now has a BACKEND variable. Set it to libvirt or proxmox and the same Justfile recipes work against either target:

# Local libvirt (the default)
just create

# Remote Proxmox
BACKEND=proxmox just create

The just create command runs an interactive configuration wizard that prompts for the VM name, profiles, memory, CPUs, disk size, and network mode. After configuration, it builds the image, creates the VM, and starts it automatically.

You can also put BACKEND=proxmox in a .env file and forget about it. The commands are identical - just stop, just upgrade, just ssh - they just talk to different backends.

Set up the Proxmox connection

All you need is SSH access to your PVE node. Create a .env file in the project root:

BACKEND=proxmox
PVE_HOST=pve
PVE_NODE=pve
PVE_STORAGE=local-zfs
PVE_BRIDGE=vmbr0
PVE_DISK_FORMAT=raw
PVE_BACKUP_STORAGE=pbs

A few notes on these:

BACKEND must be set to proxmox, otherwise libvirt is the default.
PVE_HOST must be the name of the SSH config entry in your ~/.ssh/config.
PVE_NODE must match your Proxmox node’s actual hostname. If your node is called pve in the web UI, put pve here.
PVE_STORAGE is which storage system the VM disks get stored on (i.e., local, local-zfs, my-nfs).
PVE_BRIDGE is the default network bridge. You can override this per-VM.
PVE_DISK_FORMAT use raw format for ZFS or LVM-thin, qcow2 for directory/NFS storage.
PVE_BACKUP_STORAGE is optional, for vzdump backups. Point it at a PBS instance if you have one.

Make sure you can SSH to the PVE node. Use a key without a password, or make sure that your SSH agent is loaded so you don’t need to type the password:

ssh -i ~/.ssh/id_ed25519 root@192.168.1.100

If that works, you’re good.

Build and create the Docker VM

The project ships with composable mixin profiles. The docker profile includes the Docker daemon and adds users to the docker group. For a dedicated Docker server, you don’t need the development tools or the AI agents that we used in the last post. The docker profile gives you a minimal system with SSH, Docker, and not much else (the core profile is always implicitly included).

Run the interactive create command:

just create

The wizard prompts you for:

VM name: e.g., apps01
Profiles: select docker
Memory: e.g., 4096 (4GB)
CPUs: e.g., 2
Var disk size: e.g., 50G
Network mode: select bridge and enter vmbr0

After configuration, just create builds the NixOS image with a read-only root filesystem and Docker enabled, transfers it to your PVE node via rsync, imports it as a Proxmox VM, and starts it automatically.

First boot

The VM starts automatically after just create completes. Check its status:

just status apps01

The status command queries the QEMU guest agent for the VM’s IP address. Once it’s up:

just ssh admin@apps01

You’re now SSH’d into a minimal NixOS system with Docker running. Verify it works:

docker run --rm hello-world

Docker data persistence

The immutable root design means Docker’s data directory (/var/lib/docker) lives on the read-write /var disk. This is where images, containers, volumes, and networks are stored. When you upgrade the base image, all of this survives.

If you want to run containers with persistent data, use standard Docker volumes, or you may use bind mounts from another directory under /var.

Firewall configuration

By default, ports 22, 80, and 443 are open. The firewall rules are stored per-VM in machines/<name>/tcp_ports (one port per line). To open additional ports:

echo "8080" >> machines/apps01/tcp_ports
just upgrade apps01

The upgrade syncs the new port list to the VM’s identity files and rebuilds the boot image, and automatically reboots.

Important note: The firewall rules are applied inside the VM and on the Proxmox host. This is a defense-in-depth approach. However, this also means that you should never manually touch the firewall config of the VM on the Proxmox console. All firewall changes must happen in the machines/<name>/tcp_ports and machines/<name>/udp_ports files, and subsequently run just upgrade.

Network options

Proxmox VMs can use any bridge configured on your PVE node. The network mode is stored per-VM and can be changed after creation:

# Move to a different bridge
just network-config apps01 bridge:vmbr1
just upgrade apps01

For NAT (if your PVE node has a NAT bridge configured):

just network-config apps01 nat
just upgrade apps01

Snapshots before risky changes

About to docker system prune -a and hoping you don’t regret it? Snapshot first:

just snapshot apps01 before-prune

If things go wrong:

just stop apps01
just restore-snapshot apps01 before-prune
just start apps01

Backups

For proper backups (not just snapshots), the tool wraps Proxmox’s vzdump:

just backup apps01

This creates a compressed backup on your PVE_BACKUP_STORAGE. To restore:

just restore-backup apps01

If you have a Proxmox Backup Server, point PVE_BACKUP_STORAGE at it and you get incremental, deduplicated backups for free.

Upgrades

The immutable design makes upgrades straightforward. Say you want to add lazydocker (A TUI manager for Docker). Edit the profile:

# profiles/docker.nix
{ config, pkgs, ... }:
{
  config = {
    virtualisation.docker.enable = true;
    users.users.${config.core.adminUser}.extraGroups = [ "docker" ];
    users.users.${config.core.regularUser}.extraGroups = [ "docker" ];

    environment.systemPackages = with pkgs; [
      lazydocker
    ];
  };
}

Then upgrade the VM:

just upgrade apps01

This rebuilds the image, syncs identity files, replaces the boot disk on Proxmox, and restarts the VM. Your /var disk - including all Docker data, volumes, and home directories - is untouched. The VM comes back up with the app lazydocker available and all your containers intact.

Cloning

Need another Docker server with the same setup? Clone it:

just clone apps01 apps02

The clone command prompts for the new VM name and optionally lets you adjust hardware settings (memory, CPUs, network) while keeping the same profile and disk contents.

This makes a full clone of the VM on Proxmox, generates fresh identity files (new hostname, machine-id, MAC address, SSH host keys), and syncs them onto the cloned /var disk. You get an independent VM that’s otherwise identical to the original.

Serial console

If networking is broken and SSH won’t connect, you can attach to the VM’s serial console directly:

First you’ll need to set the root password (root login is disabled otherwise):

just passwd apps01
just upgrade apps01

Reboot, and you’ll be able to login via the serial console:

just console apps01

This opens an SSH session to the Proxmox node and attaches to the VM’s serial port. You may need to press Enter to see the login prompt. Exit with Ctrl-O (that’s the letter O, not zero).

Proxmox uses full clones of the disk image

Unlike the libvirt backend, which has thin provisioning of the boot device, the Proxmox backend sends a full clone of the boot device for each VM you create on Proxmox. This increases the disk space required per VM by about 3 to 4 GB. You can run as many Docker servers as you want from a single just build docker, but, on Proxmox, each just create produces an independent VM with its own boot disk, its own identity, and its own /var disk.

If you really do want thin provisioning of Proxmox VMs, you could use nixos-vm-template to create the first VM, then turn that VM into a Proxmox template, and then use the Proxmox clone feature in the console, but then those clones would not be managed by nixos-vm-template.

Syncing identity files into /var

The Proxmox backend’s identity sync is worth noting: during upgrades, it mounts the /var disk on the PVE node using qemu-nbd and writes identity files directly. No need to download a multi-gigabyte disk just to update a hostname.

Putting it together

Here’s the full workflow for going from zero to a running Docker server on Proxmox:

# One-time setup on your workstation:
git clone https://github.com/EnigmaCurry/nixos-vm-template
cd nixos-vm-template

cat > .env << 'EOF'
BACKEND=proxmox
PVE_HOST=pve
PVE_NODE=pve
PVE_STORAGE=local-zfs
PVE_DISK_FORMAT=raw
PVE_BRIDGE=vmbr0
EOF

# Build and deploy (interactive wizard)
just create
# Enter: apps01, docker, 4096, 2, 50G, bridge, vmbr0

# The VM starts automatically, then SSH in:
just ssh admin@apps01

# On the VM
docker run -d --name nginx -p 80:80 nginx

Now you have an immutable NixOS machine for your Docker server, running on your own Proxmox infrastructure, built from a declarative Nix configuration, with snapshots and backups available, upgradeable without losing data, plus even if you don’t make backups, the whole machine is reproducible from the Nix config in your git repository (minus your data).

NixOS VMs part 1: Running code agents in an immutable NixOS VM

Thu, 22 Jan 2026 13:54:00 -0600

This is part 1 of a series on nixos-vm-template:

Running code agents in an immutable NixOS VM (this post)
Bootstrapping a Docker server with immutable NixOS on Proxmox
Mutable VMs are cool too
Managing VMs with home-manager and sway-home

AI coding agents like Claude Code and Open Code run in your terminal, read and write files, execute commands, and generally do whatever you tell them to. Claude Code is Anthropic’s official CLI agent; Open Code is an open-source alternative that supports multiple model providers (including Anthropic). Both are powerful, and both have full shell access to whatever machine they’re running on — which is a bit concerning if that machine is your daily driver laptop.

This post walks through setting up a code agent inside an immutable NixOS VM on a Fedora host, editing files remotely with Emacs TRAMP, and using git branches so that the agent’s work is immediately testable on other machines.

Why bother with a VM?

A code agent has shell access to whatever machine it’s running on. It can modify files and run any program. If you point it at your laptop’s home directory and say “refactor this project,” it will happily do so, and if something goes wrong, it went wrong on your machine.

A VM gives the agent its own filesystem to work with. The nixos-vm-template project builds immutable NixOS images with a read-only root filesystem and a separate data disk. If the environment gets weird, you can blow it away and recreate it in two commands. Your laptop stays clean.

The tradeoff is that you’re SSH’ing into a VM instead of running locally. With TRAMP this is basically invisible to Emacs, so it hasn’t bothered me.

Install the prerequisites

This example uses a Fedora laptop, but Debian, Arch, or pretty much any other Linux distro with KVM support will work. The only software dependencies you need are libvirt and the Nix package manager:

# Fedora
sudo dnf install nix just git libvirt qemu-kvm virt-manager guestfs-tools edk2-ovmf
sudo systemctl enable --now nix-daemon libvirtd

Enable Nix flakes for this user:

mkdir -p ~/.config/nix
echo "experimental-features = nix-command flakes" >> ~/.config/nix/nix.conf

Clone and build

git clone https://github.com/EnigmaCurry/nixos-vm-template \
   ~/nixos-vm-template
cd ~/nixos-vm-template

The template ships with composable profiles that you combine as needed. For a full development environment with a code agent, combine the claude (or open-code) profile with dev, docker, and podman. The agent itself gets installed via npm on first login. Pick the one you want and create a VM:

# For Claude Code with full dev environment:
just create

# When prompted, enter the VM name (e.g., "claude-dev")
# Select profiles: claude, dev, docker, podman
# Configure memory (8192), CPUs (4), and other settings

The just create command runs an interactive configuration wizard that guides you through all the options, then builds the image, creates the VM, and starts it automatically. The root filesystem is read-only (immutable), and all mutable state lives on a separate /var disk. Home directories are bind-mounted from /var/home.

First boot

The VM starts automatically after just create completes. Check its status and connect:

just status claude-dev      # prints the IP address
just ssh claude-dev         # SSH into the VM with the 'user' account

On first login, the shell profile detects that the agent isn’t installed yet and runs the appropriate npm install automatically (@anthropic-ai/claude-code or opencode-ai). Both agents need an API key for your service of choice. Here’s an example for Anthropic:

echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.bashrc
source ~/.bashrc

The Open Code profile also creates a default config at ~/.config/opencode/config.json pointing at Claude Opus 4.5. You can edit that file to switch models or providers.

Set your git user profile and preferences:

git config --global user.email "you@example.com"
git config --global user.name "Your Name"
git config --global init.defaultBranch master

Create a project repository

Create a fresh repository on GitHub for the agent to work in. This will be the project it has full control over, committing and pushing on your behalf. Go to GitHub and create a new repository (public or private, your choice), then come back here.

Next, generate an SSH key on the VM so it can push to that repo:

ssh-keygen -t ed25519 -C "claude-dev-vm" -f ~/.ssh/id_ed25519 -N ""
cat ~/.ssh/id_ed25519.pub

Copy the public key and add it as a deploy key on the repository:

Go to your repository on GitHub.
Navigate to Settings > Deploy keys > Add deploy key.
Paste the public key, give it a name like “claude-dev VM”, and check Allow write access.
Click Add key.

Deploy keys are scoped to a single repository, which is a good fit here. The VM only needs push access to the project it’s working on, not your entire GitHub account. If the agent is working on multiple repos, generate a separate key per repo.

Verify the key works:

ssh -T git@github.com

You should see a message confirming authentication. Now clone the repo on the VM:

cd ~
git clone git@github.com:you/your-project.git project
cd project

Run claude or opencode in the project directory.

Editing files with TRAMP

TRAMP (Transparent Remote Access, Multiple Protocols) is Emacs’s built-in facility for editing remote files over SSH. You open a file with a special path syntax and Emacs handles the rest, no FUSE mounts or sync tools involved.

You can read more about how to configure emacs with my emacs config.

(If you don’t want to use Emacs, you can do something pretty similar in VS Code with the Remote Development Extension).

First, add an SSH config entry so you don’t have to remember the IP:

# ~/.ssh/config
Host claude-dev
    HostName <ip>
    User user
    ControlMaster auto
    ControlPersist yes
    ControlPath /tmp/ssh-%u-%r@%h:%p

(The ControlMaster settings are optional, they enable SSH connection sharing so you won’t have to authenticate as often.)

Now you can open files on the VM directly:

C-x C-f /ssh:claude-dev:/home/user/project/src/main.rs

To get a shell running inside the VM, open a remote shell buffer:

M-x shell RET

When prompted for a directory, enter /ssh:claude-dev:/home/user/. (Or use vterm if you prefer a proper terminal emulator in a buffer.) Run your agent in that shell. Now you have it running in the VM, and your Emacs buffers pointing at the same files it’s modifying. When the agent writes to a file you have open. In Emacs enable M-x auto-revert-mode and the fill will automatically detect changes and reload the file.

SSH remote forwarding

Sometimes the agent needs access to a service running on your laptop. For example, if you have a Traefik dashboard listening on 127.0.0.1:8080, you can expose it to the VM with SSH remote forwarding:

ssh -R 8080:127.0.0.1:8080 user@claude-dev

This binds port 8080 on the VM to port 8080 on your laptop. Inside the VM, the agent can now reach the Traefik dashboard at 127.0.0.1:8080 as if it were local. You can add this to your SSH config to make it persistent:

# ~/.ssh/config
Host claude-dev
    ...
    RemoteForward 8080 127.0.0.1:8080

This is useful for giving the agent access to local dev servers, API endpoints, or dashboards without exposing them to your network. Furthermore, the claude and open-code profiles explicitly block access to RFC 1918 networks, so if you need the agent to access some service on your LAN, this is the only way.

The git workflow

The real utility of this setup is the git branching workflow. You work on a dev branch, the agent commits and pushes to it, and you can pull those changes on any other machine to test.

Setup

In the project you cloned earlier, check out a dev branch:

cd ~/project
git checkout -b dev/claude-work

Agent directives

Both Claude Code and Open Code support project-level instruction files. Claude Code reads CLAUDE.md; Open Code reads AGENTS.md. Add one (or both) to the project root:

- Always run `git pull` before making any changes.
- When working on a branch other than `master` or `main`, automatically commit
  and push changes when done with a task.

The agent reads this file and follows the directives. When you give it a task (“add input validation to the login handler”), it will pull, make the changes, commit with a message describing what it did, and push.

Testing on other machines

On your desktop, or wherever you want to test:

git fetch origin
git checkout dev/claude-work
git pull
# run tests, build, review the diff, whatever

If the tests fail, go back to the Emacs shell buffer and tell the agent what went wrong. It pulls, fixes, commits, pushes. You pull again. This loop works the same way it would with any remote collaborator, except the collaborator happens to be an AI running in a VM on your laptop.

When you’re happy with the branch, merge it however you normally merge branches.

Snapshots

One of the nice things about running in a VM is that you can snapshot the state disk before asking the agent to do anything particularly adventurous:

just snapshot claude-dev before-refactor

If things go sideways:

just restore-snapshot claude-dev before-refactor

This only snapshots the /var disk (which contains home directories, git repos, and all mutable state). The root filesystem is immutable so there’s nothing to snapshot there.

Upgrades and profiles

The template uses composable mixin profiles. Instead of a deep inheritance hierarchy, you combine profiles as needed:

core         → SSH daemon, user accounts, firewall (always included)
docker       → Docker daemon + user access
podman       → Podman + distrobox/buildah/skopeo
nvidia       → NVIDIA GPU support (requires docker)
python       → Python/uv development
rust         → Rust/rustup development
dev          → Development tools (neovim, tmux, etc.)
home-manager → Home-manager with sway-home modules (emacs, shell config, etc.)
claude       → Claude Code CLI
open-code    → OpenCode CLI

Profiles are specified as comma-separated lists. For example, claude,dev,docker,podman gives you Claude Code with the full development environment, Docker, and Podman. Each VM’s selected profiles are stored in machines/<name>/profile, which is set during just create and read by just upgrade to know which image to rebuild. To change a VM’s profiles, edit that file and put the comma-separated list you want, then run just upgrade <name>.

To add packages, edit the relevant profile file in profiles/, or create your own. For example, to add go to the dev profile:

# profiles/dev.nix
{ pkgs, ... }:
{
  environment.systemPackages = with pkgs; [
    neovim
    tmux
    go  # add new packages here
  ];
}

After editing, rebuild and upgrade:

just upgrade claude-dev    # build and install new image, preserving /var

Your home directory, git repos, npm globals (including the agent itself), and everything else on /var survives the upgrade. Only the read-only root filesystem gets replaced.

Multiple VMs

VMs created from the same base image are thin-provisioned (QCOW2 backing files), so they only store deltas from the shared image. You can spin up multiple VMs — one per project or task — each with their own repos and contexts, without duplicating the full OS image for each one.

Bridged networking

By default VMs use NAT, which means they’re accessible from the host but not from other machines on your LAN. If you want to pull the agent’s commits from a desktop on the same network without going through GitHub, you can use bridged networking. When running just create, select “bridge” for the network mode when prompted.

The VM will get an IP from your LAN’s DHCP server and be directly reachable from other machines.

See more information in the nixos-vm-template README.md

Conclusion

Putting a code agent in an immutable NixOS VM keeps your laptop safe: the OS is read-only, mutable state is isolated on /var, and snapshots make rollback trivial. With TRAMP and a branch-based git loop, it still feels local—and the agent’s work is easy to test anywhere.