claude-vm

Run Claude Code in isolated Incus containers with automatic mounting and ID mapping.

Prerequisites

Incus installed and initialized (sudo incus admin init)
User added to incus-admin group

UID/GID Mapping

Edit /etc/subuid and /etc/subgid to allow root to map your user's UID/GID:

root:1000:1
root:100000:65536

Replace 1000 with your actual UID (id -u).

Installation

sudo ln -s $(pwd)/claude-vm /usr/local/bin/claude-vm
sudo cp claude-vm.1 /usr/local/share/man/man1/

Quick Start

# Run claude in a new container with current directory mounted
claude-vm --rw .

# Use a custom image
claude-vm --image claude-vm-ubuntu-full --rw .

# Run with macvlan networking for direct network access
claude-vm --network macvlan --rw .

Images

Pre-built images are available in images/. Build them with:

# Ubuntu (base and full)
./images/ubuntu/build.sh

# Arch Linux (base only)
./images/archlinux/build.sh

Images are exported to both Docker and Incus with names like claude-vm-ubuntu-base.

Configuration

Create ~/.claude/CLAUDE-VM.md to customize the system prompt passed to Claude.