{"id":28918320,"url":"https://github.com/ksamaschke/claude-code-vm","last_synced_at":"2025-06-26T07:01:40.038Z","repository":{"id":300226540,"uuid":"1004819233","full_name":"ksamaschke/claude-code-vm","owner":"ksamaschke","description":"Deploy Claude Code and additional tools to a VM for remote development","archived":false,"fork":false,"pushed_at":"2025-06-20T14:36:50.000Z","size":124,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-06-20T14:36:52.586Z","etag":null,"topics":["claude","claude-ai","claude-code","mcp","mcp-server","mcp-servers"],"latest_commit_sha":null,"homepage":"https://vanillacore.net","language":"Makefile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ksamaschke.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-19T08:23:11.000Z","updated_at":"2025-06-20T14:34:16.000Z","dependencies_parsed_at":"2025-06-20T14:47:42.940Z","dependency_job_id":null,"html_url":"https://github.com/ksamaschke/claude-code-vm","commit_stats":null,"previous_names":["ksamaschke/claude-code-vm"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ksamaschke/claude-code-vm","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ksamaschke%2Fclaude-code-vm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ksamaschke%2Fclaude-code-vm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ksamaschke%2Fclaude-code-vm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ksamaschke%2Fclaude-code-vm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ksamaschke","download_url":"https://codeload.github.com/ksamaschke/claude-code-vm/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ksamaschke%2Fclaude-code-vm/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261224290,"owners_count":23126930,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude","claude-ai","claude-code","mcp","mcp-server","mcp-servers"],"created_at":"2025-06-22T02:02:39.234Z","updated_at":"2025-06-24T04:02:16.326Z","avatar_url":"https://github.com/ksamaschke.png","language":"Makefile","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Claude Code VM\n\n**Automated deployment system for Claude Code development environments on Debian VMs**\n\nDeploy a complete AI-enabled development environment with Claude Code CLI, Docker, Node.js, Git, and MCP servers in minutes.\n\n## 🚀 Quick Start\n\n```bash\n# Clone and setup\ngit clone https://github.com/ksamaschke/claude-code-vm.git\ncd claude-code-vm\nmake setup\n\n# OPTIONAL: Configure automated Git setup\nnano .env  # Add your Git credentials for automated setup\n\n# Deploy to your VM\nmake deploy VM_HOST=192.168.1.100 TARGET_USER=developer\n```\n\n## ✨ What You Get\n\n- **🤖 Claude Code CLI** - Ready to use with MCP server integration and subagent support\n- **📝 Automated CLAUDE.md Generation** - Environment-specific guidance with subagent documentation\n- **🐳 Docker \u0026 Docker Compose** - Complete container development environment\n- **📦 Node.js 22 LTS** - Latest LTS with global package support and PATH configuration\n- **🔐 Git Multi-Provider Support** - GitHub, GitLab, Azure DevOps, Bitbucket, custom Git servers\n- **☸️ Kubernetes Options** - k3s (default) or KIND (optional) with kubectl, kompose, and optional NGINX Ingress\n- **🧠 MCP Servers** - Optional AI extensions (search, memory, document processing) with API key setup\n- **📺 Persistent Sessions** - Screen-based terminal sessions that survive disconnects\n\n## 📋 Requirements\n\n- **Target VM**: Debian 12+ with SSH access and sudo privileges\n- **Local Machine**: Ansible installed\n- **Optional**: Git Personal Access Tokens for automated Git credential setup\n\n## 🛠️ Essential Commands\n\n```bash\nmake help              # Show comprehensive help and usage examples\nmake setup             # Initialize environment files (.env, mcp-servers.json)\nmake deploy            # Deploy complete development stack\nmake validate          # Verify all deployed components are working\nmake deploy-mcp        # Deploy MCP servers only (after initial deployment)\nmake clean             # Clean up temporary files\n```\n\n**Required for all deployments:**\n- `VM_HOST` - Target VM IP address \n- `TARGET_USER` - Username on the target VM\n\n## 🎯 Common Usage Patterns\n\n### Complete First-Time Setup\n```bash\nmake setup                                          # Initialize project\nnano .env                                          # Add Git credentials (optional)\nmake deploy VM_HOST=192.168.1.100 TARGET_USER=dev  # Deploy everything\nmake validate VM_HOST=192.168.1.100 TARGET_USER=dev # Verify deployment\n```\n\n### Deploy Individual Components\n```bash\n# Use Ansible directly with tags for component-specific deployment\nansible-playbook ansible/playbooks/site.yml --tags git\nansible-playbook ansible/playbooks/site.yml --tags docker,nodejs\nansible-playbook ansible/playbooks/site.yml --tags kubernetes,mcp\n\n# Available tags: common, git, docker, nodejs, claude-code, kubernetes, mcp\n```\n\n### MCP Server Management\n```bash\nmake setup-mcp-tool                                 # Setup local MCP management\nmake generate-mcp-config                           # Generate MCP configuration\nmake deploy-mcp VM_HOST=192.168.1.100 TARGET_USER=dev # Deploy MCP servers\n```\n\n## 🔧 Authentication Options\n\n```bash\n# Use specific SSH key\nmake deploy VM_HOST=192.168.1.100 TARGET_USER=dev TARGET_SSH_KEY=~/.ssh/custom_key\n\n# Use password authentication\nmake deploy VM_HOST=192.168.1.100 TARGET_USER=dev USE_SSH_PASSWORD=true SSH_PASSWORD=mypass\n\n# Custom environment files\nmake deploy VM_HOST=192.168.1.100 TARGET_USER=dev ENV_FILE=production.env\n```\n\n## 🌟 Key Features\n\n### AI-Enhanced Development\n- **Claude Code CLI** with MCP server integration\n- **CLAUDE.md generation** with environment-specific configuration and subagent documentation\n- **MCP servers** for search, memory, document processing (optional, requires API keys)\n\n### Container \u0026 Orchestration\n- **k3s**: Lightweight Kubernetes (default, optional)\n- **KIND**: Kubernetes in Docker (optional alternative)\n- **NGINX Ingress**: Optional ingress controller (preselected, disables Traefik)\n- **Docker**: Standard Docker and Docker Compose installation\n\n### Git Multi-Provider Support\n- **Multiple Git servers** with environment variable-based credential management\n- **Supports**: GitHub, GitLab, Azure DevOps, Bitbucket, custom Git servers\n- **SSH key generation** and global Git configuration\n\n### Deployment Features\n- **Package manager conflict detection** and graceful handling\n- **Deployment validation** with component status reporting\n- **Screen session management** for persistent terminal sessions\n- **Configurable authentication** (SSH keys, passwords)\n\n## 🔍 Quick Troubleshooting\n\n```bash\n# Test connectivity\nmake test-connection VM_HOST=192.168.1.100 TARGET_USER=dev\n\n# Check configuration\nmake check-config\n\n# Manual SSH test\nssh dev@192.168.1.100\n```\n\n## 📚 Documentation\n\nFor detailed configuration, troubleshooting, and advanced usage:\n\n- **[Ansible Configuration Reference](docs/ansible-configuration.md)** - Complete variable and role documentation\n- **[MCP Server Setup](docs/components-mcp.md)** - AI extensions and API key configuration\n- **[Troubleshooting Guide](docs/troubleshooting.md)** - Common issues and solutions\n- **[Authentication Guide](docs/authentication.md)** - SSH keys, passwords, security setup\n\n## 📄 License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n---\n\n**Need help?** Check the [documentation](docs/) or [open an issue](../../issues).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fksamaschke%2Fclaude-code-vm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fksamaschke%2Fclaude-code-vm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fksamaschke%2Fclaude-code-vm/lists"}