{"id":35771472,"url":"https://github.com/the-resonance/claude-code-hetzner-vps","last_synced_at":"2026-01-07T04:19:13.450Z","repository":{"id":330988576,"uuid":"1124365019","full_name":"The-Resonance/claude-code-hetzner-vps","owner":"The-Resonance","description":"Provision secure, Claude Code-ready Hetzner VPS instances for ~$5/month. Free tool by Pete Sena.","archived":false,"fork":false,"pushed_at":"2025-12-29T15:36:27.000Z","size":36,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-01T18:26:05.427Z","etag":null,"topics":["automation","claude-code","cloud","devops","hetzner","infrastructure","plugin","security","vps"],"latest_commit_sha":null,"homepage":"https://claude-code-hetzner.vercel.app/","language":"Shell","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/The-Resonance.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-28T22:21:30.000Z","updated_at":"2025-12-31T17:49:02.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/The-Resonance/claude-code-hetzner-vps","commit_stats":null,"previous_names":["the-resonance/claude-code-hetzner-vps"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/The-Resonance/claude-code-hetzner-vps","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/The-Resonance%2Fclaude-code-hetzner-vps","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/The-Resonance%2Fclaude-code-hetzner-vps/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/The-Resonance%2Fclaude-code-hetzner-vps/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/The-Resonance%2Fclaude-code-hetzner-vps/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/The-Resonance","download_url":"https://codeload.github.com/The-Resonance/claude-code-hetzner-vps/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/The-Resonance%2Fclaude-code-hetzner-vps/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28232399,"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","status":"online","status_checked_at":"2026-01-07T02:00:05.975Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["automation","claude-code","cloud","devops","hetzner","infrastructure","plugin","security","vps"],"created_at":"2026-01-07T04:19:10.729Z","updated_at":"2026-01-07T04:19:13.444Z","avatar_url":"https://github.com/The-Resonance.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# claude-code-hetzner-vps\n\n\u003e Spin up a secure, Claude Code-ready VPS for ~$5/month in under 5 minutes.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Claude Code Plugin](https://img.shields.io/badge/Claude%20Code-Plugin-purple)](https://claude.ai/code)\n\n**A free tool by [Pete Sena](https://linkedin.com/in/petersena) | [The Resonance Labs](https://labs.theresonance.studio)**\n\n---\n\n## What is Claude Code?\n\n[Claude Code](https://claude.ai/code) is Anthropic's official CLI tool that lets you use Claude AI directly in your terminal. It can read files, write code, run commands, and help you build software faster. This plugin extends Claude Code with commands to provision secure cloud servers.\n\n---\n\n## Installation\n\n### Option 1: From Marketplace (Easiest)\n\n```bash\n# In Claude Code\n/plugin marketplace add The-Resonance/claude-code-hetzner-vps\n/plugin install claude-code-hetzner-vps\n```\n\n### Option 2: Clone and Use\n\n```bash\n# Clone the plugin\ngit clone https://github.com/The-Resonance/claude-code-hetzner-vps.git ~/.claude-plugins/hetzner-vps\n\n# Start Claude Code with the plugin\nclaude --plugin-dir ~/.claude-plugins/hetzner-vps\n```\n\n### Option 3: Test Locally\n\n```bash\ngit clone https://github.com/The-Resonance/claude-code-hetzner-vps.git\ncd claude-code-hetzner-vps\nclaude --plugin-dir .\n```\n\nOnce loaded, you'll have access to these commands:\n- `/provision` - Create a secure VPS\n- `/status` - Check server status\n- `/destroy` - Delete a server\n- `/cost-estimate` - See pricing before you spend\n\n---\n\n## The Problem\n\nYou want to run Claude Code on a remote server—maybe for longer tasks, CI/CD pipelines, or just to keep your laptop free. But setting up a secure cloud server means:\n\n- Configuring firewalls\n- Hardening SSH\n- Setting up fail2ban\n- Installing dependencies\n- ...and hoping you didn't miss a security step\n\n## The Solution\n\nOne command. Fully secured. Claude Code pre-installed.\n\n```bash\n/provision my-server\n```\n\nThat's it. You get:\n- **UFW firewall** blocking everything except SSH\n- **fail2ban** banning brute-force attackers\n- **SSH hardening** (key-only, no root, limited retries)\n- **Automatic security updates**\n- **Claude Code** ready to use\n\n---\n\n## 5-Minute Setup (Complete Walkthrough)\n\n### Step 1: Create a Hetzner Account\n\n1. Go to [console.hetzner.cloud](https://console.hetzner.cloud)\n2. Click **Register** and create an account\n3. Verify your email\n4. You may need to add payment info (no charge until you provision)\n\n### Step 2: Create a Project\n\n1. In the Hetzner Console, click **+ New Project**\n2. Name it something like `claude-servers`\n3. Click into your new project\n\n### Step 3: Generate an API Token\n\n1. Go to **Security** → **API Tokens**\n2. Click **Generate API Token**\n3. Name it `claude-code-cli`\n4. Select **Read \u0026 Write** permissions\n5. Click **Generate**\n6. **Copy the token immediately** (you won't see it again!)\n\n### Step 4: Install the hcloud CLI\n\n**macOS:**\n```bash\nbrew install hcloud\n```\n\n**Linux:**\n```bash\ncurl -fsSL https://github.com/hetznercloud/cli/releases/latest/download/hcloud-linux-amd64.tar.gz | tar xz\nsudo mv hcloud /usr/local/bin/\n```\n\n### Step 5: Configure hcloud Authentication\n\n```bash\nhcloud context create claude-servers\n```\n\nWhen prompted, paste your API token from Step 3.\n\n**Verify it works:**\n```bash\nhcloud server list\n```\n\nShould return an empty list (no errors).\n\n### Step 6: Ensure You Have an SSH Key\n\nCheck if you have one:\n```bash\nls ~/.ssh/id_ed25519.pub || ls ~/.ssh/id_rsa.pub\n```\n\nIf not, generate one:\n```bash\nssh-keygen -t ed25519 -C \"your@email.com\"\n```\n\nPress Enter to accept defaults.\n\n### Step 7: Provision Your Server\n\n```bash\n# Check cost first\n/cost-estimate cx22\n\n# Create the server\n/provision my-dev-server cx22 nbg1\n```\n\nThis takes about 60 seconds. You'll see the server IP when done.\n\n### Step 8: Connect via SSH\n\n**Wait ~2 minutes** for cloud-init to complete, then:\n\n```bash\nssh claude@\u003cyour-server-ip\u003e\n```\n\nYou'll see the branded welcome message confirming security features are active.\n\n### Step 9: Use Claude Code\n\n```bash\nclaude\n```\n\nDone! You're running Claude Code on your own secure VPS.\n\n---\n\n## GitHub + Vercel Workflow\n\nTo push code and work with Vercel, set up GitHub authentication on your server:\n\n### Install GitHub CLI\n\n```bash\nsudo apt install gh -y\n```\n\n### Authenticate with GitHub\n\n```bash\ngh auth login\n```\n\nSelect:\n- GitHub.com\n- HTTPS\n- Yes (authenticate with browser)\n- Login with a one-time code\n\n### Set Up SSH Key for Git\n\n```bash\n# Generate a key for this server\nssh-keygen -t ed25519 -C \"your-server-name\"\n\n# Add the required scope (important!)\ngh auth refresh -h github.com -s admin:public_key\n\n# Add the key to your GitHub account\ngh ssh-key add ~/.ssh/id_ed25519.pub --title \"my-hetzner-server\"\n\n# Test the connection\nssh -T git@github.com\n```\n\n### Clone and Work\n\n```bash\n# Clone your repo\ngit clone git@github.com:username/your-repo.git\ncd your-repo\n\n# Run Claude Code\nclaude\n```\n\nNow you can commit, push, and create PRs. Vercel will auto-deploy.\n\n---\n\n## Running Web Apps\n\nBy default, the firewall only allows SSH (port 22). To access web apps:\n\n### Quick Dev Access (port 3000)\n\n```bash\n# On your server\nsudo ufw allow 3000/tcp\n\n# Run Next.js bound to all interfaces\nnpm run dev -- -H 0.0.0.0\n```\n\nAccess at: `http://\u003cyour-server-ip\u003e:3000`\n\n### Production Setup (Domain + HTTPS)\n\n```bash\n# Open web ports\nsudo ufw allow 80/tcp\nsudo ufw allow 443/tcp\n\n# Install Caddy (auto-HTTPS)\nsudo apt install -y caddy\n```\n\nEdit `/etc/caddy/Caddyfile`:\n```\nyourdomain.com {\n    reverse_proxy localhost:3000\n}\n```\n\n```bash\nsudo systemctl restart caddy\n\n# Keep your app running with pm2\nnpm install -g pm2\npm2 start npm --name \"myapp\" -- start\n```\n\nPoint your domain's A record to your server IP. Caddy handles SSL automatically.\n\n---\n\n## Common Gotchas (\u0026 Fixes)\n\n| Problem | Cause | Solution |\n|---------|-------|----------|\n| `cx22` not available in US | Shared CPU types limited to EU | Use `nbg1`, `fsn1`, or `hel1` location |\n| SSH \"Permission denied\" | Running SSH from wrong machine | Run `ssh` from your **local** computer, not the server |\n| `gh ssh-key add` returns 404 | Missing API scope | Run `gh auth refresh -h github.com -s admin:public_key` first |\n| Can't access web app in browser | Firewall blocking port | `sudo ufw allow 3000/tcp` (or 80/443 for production) |\n| Next.js only accessible on localhost | Not bound to 0.0.0.0 | Run `npm run dev -- -H 0.0.0.0` |\n| Cloud-init not complete | Provisioning still running | Wait ~2 minutes after server creation |\n| `claude` command not found | Cloud-init still running | Check: `sudo cloud-init status` |\n\n---\n\n## Commands Reference\n\n| Command | Description |\n|---------|-------------|\n| `/provision \u003cname\u003e [type] [location]` | Create a secure VPS |\n| `/status [name]` | Check server status |\n| `/destroy \u003cname\u003e` | Permanently delete a server |\n| `/cost-estimate [type]` | Estimate monthly costs |\n| `/resonance-help` | Full documentation |\n\n---\n\n## Server Types \u0026 Pricing\n\n| Type | vCPU | RAM | Storage | EUR/month | USD/month* |\n|------|------|-----|---------|-----------|------------|\n| **cax11** | 2 (ARM64) | 4 GB | 40 GB | €3.79 | ~$4.10 |\n| **cx22** | 2 (shared) | 4 GB | 40 GB | €4.49 | ~$4.85 |\n| **cx32** | 4 (shared) | 8 GB | 80 GB | €8.98 | ~$9.70 |\n| **cpx21** | 3 (AMD) | 4 GB | 80 GB | €8.49 | ~$9.17 |\n\n*USD approximate at 1.08 exchange rate\n\n**Recommendation:** Start with `cx22` for development. It handles Claude Code perfectly.\n\n---\n\n## Locations\n\n| Code | City | Region |\n|------|------|--------|\n| `nbg1` | Nuremberg | Germany (default) |\n| `fsn1` | Falkenstein | Germany |\n| `hel1` | Helsinki | Finland |\n| `ash` | Ashburn | USA* |\n| `hil` | Hillsboro | USA* |\n\n*US locations have limited server types. Use EU for best availability.\n\n---\n\n## Security Details\n\n### What Gets Configured Automatically\n\n**UFW Firewall:**\n```bash\nufw default deny incoming\nufw default allow outgoing\nufw allow 22/tcp\n```\n\n**fail2ban (SSH jail):**\n- Max retries: 5\n- Ban time: 1 hour\n- Find time: 10 minutes\n\n**SSH Hardening:**\n```\nPermitRootLogin no\nPasswordAuthentication no\nPubkeyAuthentication yes\nMaxAuthTries 3\nX11Forwarding no\n```\n\n**Automatic Updates:**\n- `unattended-upgrades` enabled\n- Security patches applied automatically\n\n---\n\n## Multi-Project Workflow\n\nFor working on multiple projects:\n\n```bash\n# Create a projects directory\nmkdir ~/projects\ncd ~/projects\n\n# Clone your repos\ngit clone git@github.com:you/project-a.git\ngit clone git@github.com:you/project-b.git\n\n# Work on project A\ncd project-a\nclaude\n\n# Later, work on project B\ncd ../project-b\nclaude\n```\n\nEach project maintains its own git state. Claude Code inherits your shell's authentication.\n\n---\n\n## Troubleshooting\n\n### \"hcloud not found\"\n```bash\n# macOS\nbrew install hcloud\n\n# Linux\ncurl -fsSL https://github.com/hetznercloud/cli/releases/latest/download/hcloud-linux-amd64.tar.gz | tar xz\nsudo mv hcloud /usr/local/bin/\n```\n\n### \"unauthorized\" or \"forbidden\" error\nYour API token may be invalid or expired. Generate a new one:\n1. Hetzner Console → Security → API Tokens\n2. Generate new token with Read \u0026 Write\n3. Run `hcloud context create \u003cname\u003e` and paste new token\n\n### Server created but can't SSH\n1. Wait 2 minutes for cloud-init\n2. Ensure you're SSHing from your local machine (not from another server)\n3. Check your SSH key: `ssh -i ~/.ssh/id_ed25519 claude@\u003cip\u003e`\n\n### Claude Code not installed\nSSH in and check cloud-init:\n```bash\nsudo cloud-init status\nsudo cat /var/log/cloud-init-output.log | tail -50\n```\n\n---\n\n## Contributing\n\nContributions welcome! Please:\n\n1. Fork the repository\n2. Create a feature branch\n3. Submit a pull request\n\n---\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n## About\n\n**claude-code-hetzner-vps** is a free tool designed to make secure cloud provisioning accessible to everyone. No strings attached, no premium tier, just useful software.\n\nBuilt by [Pete Sena](https://linkedin.com/in/petersena) at [The Resonance Labs](https://labs.theresonance.studio).\n\n*Helping builders ship faster, securely.*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthe-resonance%2Fclaude-code-hetzner-vps","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthe-resonance%2Fclaude-code-hetzner-vps","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthe-resonance%2Fclaude-code-hetzner-vps/lists"}