.TH CLAUDE-VM 1 "January 2026" "claude-vm" "User Commands"
.SH NAME
claude-vm \- run Claude Code in isolated Incus containers
.SH SYNOPSIS
.B claude-vm
[\fIINSTANCE_NAME\fR]
[\fB\-i\fR \fIIMAGE\fR]
[\fB\-u\fR \fIUSER\fR]
[\fB\-c\fR \fICOMMAND\fR]
[\fB\-\-network\fR \fIMODE\fR]
[\fB\-\-rw\fR \fIPATH\fR]
[\fB\-\-ro\fR \fIPATH\fR]
[\fB\-\-recreate\fR]
[\fB\-\-\fR | \fB\-+\fR]
[\fIARGS\fR...]
.SH DESCRIPTION
.B claude-vm
creates and manages Incus containers for running Claude Code with automatic
directory mounting and UID/GID mapping. It handles container lifecycle,
networking configuration, and passes through environment variables.
.PP
By default, it runs the
.B claude
command inside the container with a system prompt and dangerous permissions
skipped for automated operation.
.SH OPTIONS
.TP
.I INSTANCE_NAME
Name of the Incus container instance. Default: \fBclaude-vm\fR.
Can also be set via \fBCLAUDE_VM_INSTANCE\fR environment variable.
.TP
.BR \-i ", " \-\-image " " \fIIMAGE\fR
Incus image to use for creating the container.
Default: \fBimages:ubuntu/24.04\fR.
Custom images like \fBclaude-vm-ubuntu-full\fR can be used.
.TP
.BR \-u ", " \-\-user " " \fIUSER\fR
User to run commands as inside the container. Default: \fBclaude\fR.
.TP
.BR \-c ", " \-\-command " " \fICMD\fR
Command to execute inside the container. Default: \fBclaude\fR.
.TP
.BR \-e ", " \-\-env " " \fIVAR=VALUE\fR
Set environment variable for the command. Can be specified multiple times.
.TP
.BR \-p ", " \-\-prompt " " \fIPATH\fR
Path to file containing system prompt for Claude.
Default: \fB~/.claude/CLAUDE-VM.md\fR.
.TP
.BR \-\-add\-path " " \fIPATH\fR
Add directory to guest PATH environment variable. Can be specified multiple times.
.TP
.BR \-\-rw " " \fIPATH\fR
Mount a host path read-write into the container.
Format: \fIHOST_PATH\fR or \fIHOST_PATH\fR:\fIGUEST_PATH\fR.
If GUEST_PATH is relative, it's relative to \fB/home/claude/host/\fR.
.TP
.BR \-\-ro " " \fIPATH\fR
Mount a host path read-only into the container. Same format as \fB\-\-rw\fR.
.TP
.BR \-\-network " " \fIMODE\fR
Network mode: \fBnat\fR (default) or \fBmacvlan\fR for direct L2 network access.
.TP
.BR \-\-parent " " \fIIFACE\fR
Parent interface for macvlan mode. Auto-detected from default route if not specified.
.TP
.B \-\-x11
Enable X11 forwarding. Mounts the host's XAUTHORITY file to \fB~/.host/Xauthority\fR
and \fB/tmp/.X11-unix\fR to \fB~/.host/X11-unix\fR, setting the appropriate
environment variables (DISPLAY and XAUTHORITY) for GUI applications.
.TP
.B \-\-tmux
Create and attach to a tmux session named after the instance.
If the session already exists, attach to it; otherwise create a new session.
This allows for persistent sessions and easy reconnection.
.TP
.B \-\-fresh
Remove all existing mount devices before applying new mounts.
.TP
.B \-\-bootstrap
Create claude user and install claude-code on first boot.
Useful when using base images without pre-installed tools.
.TP
.B \-\-init
Initialize guest claude configuration by copying template files from
\fB~/.config/claude-vm/\fR on the host to \fB~/.claude/\fR in the guest.
Copies \fBclaude/AGENTS.md\fR to \fB~/.claude/CLAUDE.vm\fR,
\fBclaude/settings.json\fR to \fB~/.claude/settings.json\fR,
and \fBclaude.json\fR to \fB~/.claude.json\fR.
.TP
.B \-\-recreate
Delete and recreate the container if it already exists.
.TP
.B \-\-restart
Restart the container if it already exists.
.TP
.B \-\-
Stop option parsing and pass remaining arguments directly to the command,
replacing default arguments.
.TP
.B \-+
Stop option parsing and append remaining arguments to the default arguments.
.SH ENVIRONMENT
.TP
.B ANTHROPIC_API_KEY
API key passed through to Claude inside the container.
.TP
.B CLAUDE_VM_INSTANCE
Default instance name if not specified on command line.
.SH FILES
.TP
.I ~/.claude/CLAUDE-VM.md
Default system prompt file for Claude.
.TP
.I /etc/subuid
.TQ
.I /etc/subgid
Must contain entries allowing root to map host user's UID/GID for mounts to work correctly.
.SH EXAMPLES
Run Claude with current directory mounted read-write:
.PP
.RS
.nf
claude-vm --rw .
.fi
.RE
.PP
Use a pre-built full image:
.PP
.RS
.nf
claude-vm --image claude-vm-ubuntu-full --rw /path/to/project
.fi
.RE
.PP
Run with macvlan networking:
.PP
.RS
.nf
claude-vm --network macvlan --parent eth0 --rw .
.fi
.RE
.PP
Ask Claude a question directly:
.PP
.RS
.nf
claude-vm -+ "How do I reverse a list in Python?"
.fi
.RE
.PP
Run a different command:
.PP
.RS
.nf
claude-vm -c bash -- -c "echo hello"
.fi
.RE
.PP
Run with X11 forwarding for GUI apps:
.PP
.RS
.nf
claude-vm --x11 --rw . -c google-chrome
.fi
.RE
.PP
Bootstrap a fresh image:
.PP
.RS
.nf
claude-vm --image images:archlinux --bootstrap --rw .
.fi
.RE
.PP
Run in a persistent tmux session:
.PP
.RS
.nf
claude-vm --tmux --rw .
.fi
.RE
.SH SEE ALSO
.BR incus (1),
.BR claude (1)
.SH AUTHORS
sinitax