Claude VM

Run Claude in --dangerously-skip-permissions without worrying

Claude VM gives you safety through VM isolation, reproducibility through template VMs, and simplicity through one-command setup. Each Claude session runs in a fresh, sandboxed VM that's destroyed after use.

Quick Start

# One-time setup: create a template VM
claude-vm setup --git --node

# Run Claude in an isolated VM
claude-vm "help me code"

# Open a shell in the VM
claude-vm shell

Each run starts from the same clean template and automatically cleans up when done.

Command Structure

Claude VM supports two equivalent invocation patterns:

# Shorthand — automatically routes to agent
claude-vm "help me code"
claude-vm /clear
claude-vm --disk 50 /clear

# Explicit agent command
claude-vm agent "help me code"
claude-vm agent /clear
claude-vm agent --disk 50 /clear

Both forms work identically. The explicit agent command makes the default behavior discoverable — run claude-vm agent --help to see all agent-specific flags.

All existing usage continues to work without modification. No changes are needed to your workflows or scripts.

Available Commands

claude-vm agent [flags] [args]     # Run Claude (also the default)
claude-vm shell [flags] [args]     # Interactive shell or run commands (alias: sh)
claude-vm setup [flags] <name>     # Create a template VM
claude-vm worktree <subcommand>    # Worktree management (alias: w)
claude-vm info                     # Show project information (alias: i)
claude-vm config <subcommand>      # Configuration management (alias: cfg)
claude-vm list [flags]             # List templates (alias: ls)
claude-vm clean [flags]            # Remove current template
claude-vm clean-all [flags]        # Remove all templates
claude-vm update [flags]           # Update claude-vm (alias: up)
claude-vm network <subcommand>     # Network isolation management (alias: net)

Worktree subcommands:

• worktree create (alias: new) - Create a new worktree
• worktree list (alias: ls) - List all worktrees
• worktree remove (alias: rm) - Remove worktrees

Runtime flags like --disk, --memory, --mount, --env, and --worktree are available on agent, shell, and setup commands. Other commands show only their own flags.

See Usage Guide for complete command reference.

Why Claude VM?

VM isolation is the only safe way to run Claude with --dangerously-skip-permissions. Even if Claude executes unintended commands, the blast radius is limited to the disposable VM.

Claude VM runs each session in an isolated Linux VM that:

• Only mounts the current project directory
• Has its own filesystem, network stack, and process space
• Is automatically destroyed after each session
• Starts from a known-good template state every time

Think of it as Docker for AI coding assistants - isolated, reproducible, and safe.

Key Features

• Template VMs per Repository - Create once per project, clone for fast startup
• Git Worktree Management - Dedicated commands for creating, listing, deleting, and cleaning worktrees with seamless --worktree flag integration
• Runtime Scripts - Automatically run setup scripts before each session
• Configuration File Support - Define VM resources, tools, and settings in .claude-vm.toml
• Automatic Worktree Detection - Detects and mounts both worktree and main repository automatically
• Comprehensive Management - Commands for info, config validation, template cleanup, and more

Installation

Requirements

• Lima

Quick Install

Install to ~/.local/bin (no sudo required):

curl -fsSL https://raw.githubusercontent.com/themouette/claude-vm/main/install.sh | bash

Install system-wide to /usr/local/bin:

curl -fsSL https://raw.githubusercontent.com/themouette/claude-vm/main/install.sh | bash -s -- --global

Install specific version:

curl -fsSL https://raw.githubusercontent.com/themouette/claude-vm/main/install.sh | bash -s -- --version v0.3.0

Download from GitHub

Download the latest version for your platform from GitHub Releases and copy the executable to your ~/.local/bin directory.

From Source

See docs/development.md

Basic Usage

Setup a Template

# Create template with specific tools
claude-vm setup --docker --node

# Or install everything
claude-vm setup --all

Run Claude

# Run Claude in an ephemeral VM
claude-vm "help me code"

# Same thing, explicit agent command
claude-vm agent "help me code"

# With auto-setup if template doesn't exist
claude-vm --auto-setup "help me code"

Shell Access

# Interactive shell
claude-vm shell

# Execute a command
claude-vm shell npm test

Management Commands

# Show project info
claude-vm info

# Validate configuration
claude-vm config validate

# List all templates
claude-vm list

# Clean current project's template
claude-vm clean

Documentation

• Getting Started - Installation, requirements, and first setup
• Usage Guide - All commands with examples
• Configuration - TOML config, environment variables, precedence

Features

• Templates - How template VMs work
• Runtime Scripts - Runtime scripts and context contribution
• Custom Mounts - Mount additional directories
• Network Isolation - Prevent access to network
• Tools - Available tools (Docker, Node.js, Python, etc.)

Advanced Topics

• Agent Forwarding - GPG, SSH, and Git configuration
• Git Integration - Worktrees and conversation history
• Custom Packages - Install custom system packages
• Troubleshooting - Common issues and debugging

Contributing

• Development Guide - Architecture, building, and testing
• Contributing - How to contribute to the project

Quick Reference

Configuration File

Create .claude-vm.toml in your project root:

[vm]
disk = 20      # GB
memory = 8     # GB

[tools]
docker = true
node = true
rust = true
git = true

See docs/configuration.md for complete configuration reference.

Environment Variables

Pass environment variables to the VM:

# Individual variables
claude-vm --env API_KEY=secret shell

# From file
claude-vm --env-file .env shell

# Inherit from host
claude-vm --inherit-env PATH shell

License

MIT OR Apache-2.0

Inspiration

Based on an idea from @sylvinus

Thanks to @babbins for the catch-phrase