Skip to content
BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

62 Commits
ansible
ansible
 
 
config
config
 
 
docs
docs
 
 
.gitignore
.gitignore
 
 
CLAUDE.md
CLAUDE.md
 
 
LICENSE
LICENSE
 
 
Makefile
Makefile
 
 
README.md
README.md
 
 
ansible.cfg
ansible.cfg
 
 

Repository files navigation

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

🔧 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.

About

Deploy Claude Code and additional tools to a VM for remote development

vanillacore.net

Topics

claudeclaude-aiclaude-codemcpmcp-servermcp-servers

Resources

Readme
MIT license
Activity
Custom properties

Stars

33 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases

Packages

Contributors

Languages