Claude Code VM

Automated deployment system for Claude Code development environments on Debian VMs.

Features

Core Components:

• Claude Code CLI installation and configuration
• Node.js 22 LTS with npm global configuration
• Git with multi-provider credential management (GitHub, GitLab, Azure DevOps)
• Docker CE with user group integration (passwordless container access)
• Docker Compose with latest version auto-resolution
• Kubernetes tools (kubectl, k3s/KIND support)
• 7 MCP servers (4 require no API keys, 3 conditional on API keys)

Configuration Management:

• 4-tier progressive deployment architecture (baseline → enhanced → containerized → full Kubernetes)
• Intelligent CLAUDE.md deployment with automatic tier detection and modular template inheritance
• Comprehensive settings.json with 500+ curated allow/deny security rules for Claude Code
• External configuration support (keep config files outside project directory)
• Localhost deployment support (no SSH required)
• Dynamic inventory generation for single or multi-host deployments

Security & Safety:

• Curated security ruleset specifically designed for Claude Code VM operations
• SSH access restricted to private network ranges (10.0.0., 192.168.)
• Project-safe cleanup operations (rm -rf within current directory)
• Git safety controls (basic push excluded, force push to main/master denied)
• Credential management without committing sensitive data

Automation:

• Ansible-based deployment with Make interface
• Automatic component detection and configuration
• Git repository cloning and management
• External dependency resolution
• Comprehensive validation and testing

What Makes This Different

• Progressive complexity: Start with basic Git+Node.js, scale up to full Kubernetes clusters
• Context-aware Claude configuration: CLAUDE.md automatically adapts to your deployment tier
• Purpose-built security: 500+ rules specifically crafted for Claude Code VM operations
• External configuration support: Keep all config files outside the project directory
• Zero-SSH localhost support: Deploy and test configurations on your local machine
• Modular template system: CLAUDE.md uses inheritance for maintainable, customizable configurations

🚀 Quick Start

# Clone and setup
git clone https://github.com/ksamaschke/claude-code-vm.git
cd claude-code-vm
make setup

# Configure your environment (optional but recommended)
nano .env  # Add Git credentials and MCP API keys

# Choose your deployment tier
make deploy-baseline VM_HOST=192.168.1.100 TARGET_USER=developer         # Minimal
make deploy-enhanced VM_HOST=192.168.1.100 TARGET_USER=developer         # + MCPs + Docker
make deploy-containerized VM_HOST=192.168.1.100 TARGET_USER=developer    # + Docker Compose + shell
make deploy-full VM_HOST=192.168.1.100 TARGET_USER=developer             # + Kubernetes + everything

# Or deploy specific components
make deploy-claude-config VM_HOST=192.168.1.100 TARGET_USER=developer    # CLAUDE.md and settings.json

🏗️ 4-Tier Deployment Architecture

Tier 1: Baseline (deploy-baseline)

Minimal core development environment

• ✅ Git with multi-provider credential management (GitHub, GitLab, Azure DevOps, custom)
• ✅ Node.js 22 LTS with npm global configuration and PATH setup
• ✅ Claude Code CLI installed globally and ready to use
• ✅ uvx for isolated Python package execution
• ✅ Git repository management (optional) - automatic cloning with branch selection

Tier 2: Enhanced (deploy-enhanced)

Baseline + AI capabilities + containerization

• ✅ Everything from Tier 1
• ✅ MCP servers from template configuration:
  • 🧠 No API keys needed: memory, sequential-thinking, puppeteer, doc-forge (4 servers)
  • 🔍 Require API keys: brave-search, context7, omnisearch (3 additional servers)
• ✅ Docker with user group integration (passwordless container management)
• ✅ Docker group setup (needed for puppeteer-docker and other containerized MCPs)

Tier 3: Containerized (deploy-containerized)

Enhanced + orchestration + productivity

• ✅ Everything from Tier 2
• ✅ Docker Compose with latest version auto-resolution
• ✅ Enhanced bashrc with Docker aliases and shortcuts
• ✅ Shell integrations: dps, dcp, dcup, dcdown, dexec, dlogs aliases
• ✅ Productivity enhancements for container development

Tier 4: Full (deploy-full)

Everything + Kubernetes + comprehensive tooling

• ✅ Everything from Tier 3
• ✅ Kubernetes tools: kubectl, helm, kompose with bash completions
• ✅ k3s cluster (default) or KIND (alternative) - choose your Kubernetes backend
• ✅ NGINX Ingress Controller for production-ready ingress
• ✅ Comprehensive bashrc: Kubernetes aliases (k, kgp, kgs, kdesc, etc.)
• ✅ Advanced functions: kctx, kns, drun, cdls, ff
• ✅ User CLAUDE.md with environment-specific guidance

📋 Prerequisites

• Local machine: Ansible 2.9+ installed
• Target VM: Debian 12+ (Bookworm) with SSH access
• Network: SSH port 22 open between local and target
• Permissions: Target user with sudo access
• Optional: Git PATs for repository access, API keys for MCP servers

📁 Project Structure & Configuration

Default Configuration Directory: config/

The project uses the config/ directory for default configuration files:

config/
├── env.example                # Template for .env file with Git credentials and API keys
├── git-repos.env.example      # Template for Git repository configuration
├── mcp-servers.template.json  # Template for MCP server configuration
├── CLAUDE.common.md           # Common base configuration (shared by all)
├── CLAUDE.minimal.md          # Minimal deployment configuration
├── CLAUDE.enhanced.md         # Enhanced deployment with MCP/Docker
├── CLAUDE.containerized.md    # Containerized with Docker Compose
└── CLAUDE.full.md            # Full deployment with Kubernetes

Configuration Files

1. Environment File (.env)

   • Default location: config/.env (create from config/env.example)
   • Override with: ENV_FILE=/path/to/your/.env
   • Contains: Git credentials, API keys for MCP servers

2. MCP Configuration (mcp-servers.json)

   • Default location: config/mcp-servers.json
   • Override with: MCP_FILE=/path/to/your/mcp-servers.json
   • Contains: MCP server definitions and settings
   • Auto-generated: If no config exists, system copies config/mcp-servers.template.json as default

3. Git Repository Configuration

   • Default: Same as ENV_FILE
   • Override with: GIT_CONFIG_FILE=/path/to/your/git-repos.conf
   • Contains: Repository URLs, branches, and management settings

First-Time Setup

# 1. Clone the repository
git clone https://github.com/ksamaschke/claude-code-vm.git
cd claude-code-vm

# 2. Run setup to create default configuration
make setup  # Creates config/.env from template

# 3. Edit configuration files
nano config/.env  # Add your Git PATs and API keys

# 4. Deploy
make deploy-enhanced VM_HOST=192.168.1.100 TARGET_USER=developer

⚙️ Configuration Options

Kubernetes Backend Selection

# Use k3s (default - production-ready, lightweight)
make deploy-full VM_HOST=192.168.1.100 TARGET_USER=dev KUBERNETES_BACKEND=k3s

# Use KIND (development-focused, runs in Docker)
make deploy-full VM_HOST=192.168.1.100 TARGET_USER=dev KUBERNETES_BACKEND=kind

Git Repository Management

# Deploy only Git repositories (after initial deployment)
make deploy-git-repos VM_HOST=192.168.1.100 TARGET_USER=dev

# Enable automatic repository cloning during deployment
make deploy-enhanced VM_HOST=192.168.1.100 TARGET_USER=dev MANAGE_GIT_REPOSITORIES=true

# Use separate Git configuration file
make deploy-git-repos VM_HOST=192.168.1.100 TARGET_USER=dev GIT_CONFIG_FILE=.git-repos.env

# Supports multiple Git URL formats in config files:
# GITHUB_URL=https://github.com/user/repo.git  (simple format)
# GIT_REPO_URL=https://github.com/user/repo.git (single repo)
# GIT_REPO_1_URL=... (multiple repos)

External Configuration Files

# Use external environment file
make deploy-enhanced VM_HOST=192.168.1.100 TARGET_USER=dev ENV_FILE=/path/to/production.env

# Use external MCP configuration
make deploy-enhanced VM_HOST=192.168.1.100 TARGET_USER=dev MCP_FILE=/path/to/custom-mcp.json

# Use external Claude settings
make deploy-claude-config VM_HOST=192.168.1.100 TARGET_USER=dev CLAUDE_SETTINGS_FILE=/path/to/custom-settings.json

# Use all external configs
make deploy-enhanced VM_HOST=192.168.1.100 TARGET_USER=dev \
  ENV_FILE=/external/configs/production.env \
  MCP_FILE=/external/configs/my-mcp-servers.json \
  CLAUDE_SETTINGS_FILE=/external/configs/restrictive-settings.json

🛠️ Essential Commands

# Setup and validation
make help                    # Show comprehensive help with all deployment options
make setup                   # Initialize environment files (.env, mcp-servers.json)
make check-config            # Validate configuration before deployment
make test-connection         # Test SSH connectivity to target VM
make validate               # Verify all deployed components are working
make clean                  # Clean up temporary files and logs

# 4-tier deployments
make deploy-baseline        # Tier 1: Git + Node.js + Claude Code + uvx
make deploy-enhanced        # Tier 2: Baseline + MCPs + Docker
make deploy-containerized   # Tier 3: Enhanced + Docker Compose + bashrc
make deploy-full           # Tier 4: Everything + Kubernetes + comprehensive tooling

# Component-specific deployments
make deploy-claude-config   # Deploy CLAUDE.md and settings.json (supports localhost)
make deploy-mcp            # Deploy/update MCP servers on target VM
make deploy-git-repos      # Clone and manage Git repositories on target VM
make list-remote SSH_HOST=<ip> SSH_USER=<user>  # List MCP servers on remote VM

4. Claude Configuration (CLAUDE.md and settings.json)

The system automatically deploys both CLAUDE.md and settings.json files to ~/.claude/ on target VMs:

• CLAUDE.md: Provides Claude Code with context about the deployment environment
• settings.json: Defines allow/deny rules for safe operation within the VM

CLAUDE.md Features:

• Auto-detection: Automatically selects the right configuration based on deployment tier
• Modular templates: Uses inheritance (common → minimal → enhanced → containerized → full)
• Override support: Use custom templates with claude_config_template parameter
• Include processing: Templates can include other templates for modularity

settings.json Features:

• 500+ security rules: Comprehensive allow/deny rules for safe VM operations
• Development-focused: Docker, Kubernetes, Git (branch/merge), Make, npm, find, file operations
• Network access: SSH/SCP to private networks (10.0.0., 192.168.1., 192.168.0.*)
• Project-safe cleanup: rm -rf allowed within current directory (./* and .//)
• Security boundaries: Blocks destructive ops, privilege escalation, credential exposure
• Git safety: Basic push excluded (requires explicit permission), force push to main/master denied
• Configurable: Use templates (CLAUDE_SETTINGS_TEMPLATE) or external files (CLAUDE_SETTINGS_FILE)
• Inspired by: claude-settings project

Usage:

# Auto-detection (default) - deploys both CLAUDE.md and settings.json
make deploy-enhanced VM_HOST=192.168.1.100 TARGET_USER=dev

# Deploy CLAUDE.md and settings.json only
make deploy-claude-config VM_HOST=192.168.1.100 TARGET_USER=dev

# Use custom templates or external files
make deploy-claude-config VM_HOST=192.168.1.100 TARGET_USER=dev \
  CLAUDE_CONFIG_TEMPLATE=config/CLAUDE.custom.md \
  CLAUDE_SETTINGS_TEMPLATE=config/custom-settings.json

# Use external configuration files
make deploy-claude-config VM_HOST=192.168.1.100 TARGET_USER=dev \
  CLAUDE_SETTINGS_FILE=/path/to/external-settings.json

# Force override existing files
make deploy-claude-config VM_HOST=192.168.1.100 TARGET_USER=dev \
  CLAUDE_CONFIG_FORCE_OVERRIDE=true \
  CLAUDE_SETTINGS_FORCE_OVERRIDE=true

# Deploy to localhost (no SSH required)
make deploy-claude-config VM_HOST=localhost TARGET_USER=$USER

See docs/claude-config.md for detailed documentation.

💡 Smart Features

🤖 AI-Enhanced Development

• Claude Code CLI with configurable MCP servers for enhanced AI capabilities
• MCP servers from config/mcp-servers.template.json:
  • No API keys needed: memory, sequential-thinking, puppeteer, doc-forge (4 servers)
  • Require API keys: brave-search, context7, omnisearch (3 servers)
  • Fully customizable through template or custom configuration files
  • GitHub/GitLab repository integration with PAT support
  • Sequential thinking for complex problem solving
  • Browser automation with Puppeteer (both local and Docker)
• Environment-aware CLAUDE.md generation on target VM with deployment-specific guidance
• uvx integration for running AI tools and Python packages in isolation

🐳 Container & Orchestration Intelligence

• Dynamic Docker Compose version resolution - always gets the latest stable version
• Smart Kubernetes backend selection - k3s for production, KIND for development
• Automatic ingress configuration - NGINX Ingress with k3s, built-in with KIND
• User group management - passwordless Docker and proper permissions

📁 Git Multi-Provider Excellence

• Universal Git credential management - GitHub, GitLab, Azure DevOps, Bitbucket, custom servers
• Pattern-based configuration: GIT_{NAME}_{FIELD} for unlimited Git server support
• Automated repository management with branch selection and post-clone commands
• SSH key generation and global Git configuration

🚀 Shell Productivity Enhancements

• Docker aliases: dps, dpa, di, drm, dexec, dlogs, dcp, dcup, dcdown, dcps, dclogs
• Kubernetes aliases: k, kgp, kgs, kgd, kdesc, klogs, kexec, kapply, kdelete
• Custom functions:
  • drun <image> - Quick container execution
  • kctx [context] - Kubernetes context switching
  • kns [namespace] - Namespace switching
  • cdls <dir> - Change directory and list
  • ff <pattern> - Fast file find
• Auto-completions for kubectl, Docker, and all major tools

🎯 Use Cases & Examples

Development Team Setup

# Containerized development environment with Git automation
make deploy-containerized VM_HOST=192.168.1.100 TARGET_USER=developer \
  MANAGE_GIT_REPOSITORIES=true GIT_CONFIG_FILE=team-repos.env

AI/ML Development

# Full environment with uvx for Python tools and Kubernetes for ML workloads
make deploy-full VM_HOST=192.168.1.100 TARGET_USER=datascientist \
  KUBERNETES_BACKEND=k3s

Microservices Development

# KIND for local Kubernetes development with Docker Compose fallback
make deploy-full VM_HOST=192.168.1.100 TARGET_USER=developer \
  KUBERNETES_BACKEND=kind

Minimal CI/CD Agent

# Baseline environment for lightweight build agents
make deploy-baseline VM_HOST=192.168.1.100 TARGET_USER=ci-agent

🔧 Advanced Configuration

Using External Configuration Files

# Use configuration files from another location
make deploy-enhanced VM_HOST=192.168.1.100 TARGET_USER=dev \
  ENV_FILE=/path/to/external/.env \
  MCP_FILE=/path/to/external/mcp-servers.json \
  GIT_CONFIG_FILE=/path/to/external/git-repos.conf

# Example: Using configurations from another project
make deploy-full VM_HOST=192.168.1.100 TARGET_USER=dev \
  ENV_FILE=~/my-configs/.env \
  MCP_FILE=~/my-configs/mcp-servers.json

Authentication Options

# SSH key authentication
make deploy-enhanced VM_HOST=192.168.1.100 TARGET_USER=dev \
  TARGET_SSH_KEY=~/.ssh/custom_key

# Password authentication
make deploy-enhanced VM_HOST=192.168.1.100 TARGET_USER=dev \
  USE_SSH_PASSWORD=true SSH_PASSWORD=secure_password

# Sudo password required
make deploy-enhanced VM_HOST=192.168.1.100 TARGET_USER=dev \
  USE_BECOME_PASSWORD=true BECOME_PASSWORD=sudo_password

Component-Specific Deployment

# Deploy specific components using Ansible directly
ansible-playbook ansible/playbooks/site.yml --tags git,git-repos
ansible-playbook ansible/playbooks/site.yml --tags docker -e install_docker=true
ansible-playbook ansible/playbooks/site.yml --tags kubernetes -e install_kubectl=true
ansible-playbook ansible/playbooks/site.yml --tags bashrc -e enable_bashrc_integrations=true
ansible-playbook ansible/playbooks/site.yml --tags uvx

📋 Requirements

• Target VM: Debian 12+ (Bookworm) with SSH access and sudo privileges
• Local Machine: Ansible 2.9+ installed
• Network: SSH connectivity between local machine and target VM
• Optional: Git Personal Access Tokens for automated credential setup
• Optional: MCP API keys (Brave Search, GitHub, GitLab) for AI enhancements

🔍 Troubleshooting

Connection Issues

# Test basic connectivity
make test-connection VM_HOST=192.168.1.100 TARGET_USER=dev

# Check configuration
make check-config

# Manual verification
ssh dev@192.168.1.100 'docker --version && kubectl version --client && node --version'

Deployment Issues

# Verbose deployment for debugging
ansible-playbook ansible/playbooks/site.yml -vvv

# Check specific component
ansible-playbook ansible/playbooks/site.yml --tags docker --check --diff

# Validate after deployment
make validate VM_HOST=192.168.1.100 TARGET_USER=dev

Post-Deployment

# On target VM, update shell environment
source ~/.bashrc

# Verify installations
docker --version
kubectl version --client
claude --version
uvx --version

📚 Documentation

• CLAUDE.md - Complete deployment reference and architecture
• Claude Config Deployment - deploy-claude-config usage and localhost support
• Claude Configuration Guide - CLAUDE.md templates and customization
• Ansible Configuration - Variables and role documentation
• MCP Server Setup - AI extensions and API configuration
• Git Configuration - Multi-provider Git setup
• Authentication Guide - SSH keys, passwords, security

🔧 Component-Specific Deployments

CLAUDE Configuration Management

# Deploy CLAUDE.md with auto-detected template
make deploy-claude-config VM_HOST=192.168.1.100 TARGET_USER=dev

# Deploy specific CLAUDE template
make deploy-claude-config VM_HOST=192.168.1.100 TARGET_USER=dev \
  CLAUDE_CONFIG_TEMPLATE=config/CLAUDE.full.md

# Force override existing CLAUDE.md
make deploy-claude-config VM_HOST=192.168.1.100 TARGET_USER=dev \
  CLAUDE_CONFIG_FORCE_OVERRIDE=true

# Deploy to localhost (no SSH or Debian required)
make deploy-claude-config VM_HOST=localhost TARGET_USER=$USER

Localhost Deployment Support

The system automatically detects localhost deployments and adjusts accordingly:

• No SSH authentication required for VM_HOST=localhost or VM_HOST=127.0.0.1
• Uses Ansible local connection instead of SSH
• Skips sudo requirements for local deployments
• Ideal for testing configurations locally before remote deployment
• In case of Claude Config and MCP Servers: No Debian required, works with any Linux or MacOS

Note: Full stack deployments to localhost may have limitations on non-Debian systems.

📄 License

MIT License - see LICENSE file for details.

---

Ready to deploy? Start with make setup and choose your tier! 🚀

Need help? Check the documentation or open an issue for support.