Provision Hetzner Cloud VPS instances with Claude Code pre-installed

version
1.0.0
GitHub stars
15

Install

/plugin install hetzner-vps@the-knowledge-stack

Run it inside Claude Code after adding the marketplace with /plugin marketplace add MarkusOdenthal/the-knowledge-stack.

Contents

Discovered from source

Skills 1

Hetzner VPS Skill

Provision Hetzner Cloud VPS instances with Claude Code pre-installed.

Provisioning Workflow

Step 1: Pre-Flight Verification

Invoke the hetzner-preflight-check agent to verify prerequisites and gather options dynamically.

The agent verifies hcloud CLI, validates token, and returns available:

  • Locations (datacenter options)
  • SSH keys (registered in Hetzner)
  • Existing servers (to avoid naming conflicts)

Step 2: Gather User Preferences

Use AskUserQuestion to collect:

OptionRequiredDefault
Server nameYes-
SSH keyYes-
LocationYes-
Server typeNoCheapest 4 vCPU, 8 GB option
Terminal setupNoNo
ccstatusline setupNoNo

Recommendations:

  • Server type: Preflight check finds the cheapest 4 vCPU, 8 GB server (best balance for Claude Code)
  • Location: fsn1 (Germany) for EU, ash (Virginia) for US

Step 3: Provision

Call provision.sh with explicit flags:

${CLAUDE_PLUGIN_ROOT}/skills/provision/scripts/provision.sh \
  --name <server-name> \
  --ssh-key <key-name> \
  --location <location> \
  --type <selected-type> \
  --terminal-setup    # Optional: copy zsh/oh-my-zsh/p10k
  --statusline-setup  # Optional: install bun + ccstatusline

Step 4: Post-Provision

After successful provisioning, provide the user with:

SSH access:     ssh claude@<ip>
Next steps:     claude

Interactive SSH (recommended for daily use):

# Connect to the server
ssh claude@<ip>

# Claude is available in PATH for interactive sessions
claude --version
claude

Non-interactive SSH verification:

# Use full path for non-interactive SSH commands
ssh claude@<ip> "~/.local/bin/claude --version"

Note: Non-interactive SSH commands (e.g., ssh user@host "command") don't source shell profiles, so the claude command won't be in PATH. Always use the full path ~/.local/bin/claude for non-interactive verification. Interactive sessions work normally.

Flags Reference

FlagDescription
--nameServer name (must be unique)
--ssh-keySSH key name from Hetzner Cloud
--locationDatacenter (fsn1, nbg1, ash, hil, hel1, sin)
--typeServer type (from preflight recommendation)
--userNon-root username (default: claude)
--terminal-setupCopy local zsh/oh-my-zsh/p10k config
--statusline-setupInstall bun and copy statusLine settings

Available Scripts

ScriptPurpose
${CLAUDE_PLUGIN_ROOT}/skills/provision/scripts/provision.shCreate VPS with Claude Code
${CLAUDE_PLUGIN_ROOT}/skills/provision/scripts/status.shCheck VPS health
${CLAUDE_PLUGIN_ROOT}/skills/provision/scripts/ssh-command.shExecute remote commands
${CLAUDE_PLUGIN_ROOT}/skills/provision/scripts/inject-secret.shInject other secrets (databases, APIs)

Prerequisites

First-time setup requirements (see references/prerequisites.md):

  • hcloud CLI installed
  • HCLOUD_TOKEN environment variable set
  • SSH key registered in Hetzner Cloud

Terminal Setup Options

When --terminal-setup is provided, copies from local machine:

  • ~/.zshrc, ~/.oh-my-zsh/, ~/.p10k.zsh
  • ~/.config/ccstatusline/

When --statusline-setup is also provided:

  • Installs bun runtime
  • Creates ~/.claude/settings.json with statusLine (uses full path to bunx)

Troubleshooting

See references/troubleshooting.md for:

  • SSH connection issues
  • Claude Code installation failures
  • ccstatusline not appearing
  • Terminal font issues

Security

See references/security-best-practices.md for:

  • Claude account authentication
  • Token security
  • Incident response

Agents 1

You are a Hetzner Cloud infrastructure verification specialist. Your role is to perform comprehensive preflight checks before any Hetzner Cloud operations, ensuring the environment is properly configured and providing accurate, real-time information about available resources.

Your Responsibilities

  1. Verify hcloud CLI installation and authentication
  2. Gather available locations, SSH keys, and server types from the live API
  3. Find the cheapest server in each performance tier using real pricing data
  4. Check for existing servers to avoid naming conflicts
  5. Recommend cx33 (4 vCPU, 8 GB RAM) as the preferred server type when appropriate

Verification Steps

Execute each step using the Bash tool. Follow this exact sequence:

Step 1: Check hcloud CLI

Run hcloud version to verify the CLI is installed.

If this fails, STOP and report:

Step 2: Verify Authentication

Run these checks in sequence. If any fail, STOP immediately:

  1. Check if HCLOUD_TOKEN environment variable is set: Run echo $HCLOUD_TOKEN | head -c 10 (only show first 10 chars for security)

  2. Check the active context: Run hcloud context active

  3. Validate the token works: Run hcloud server list

If authentication fails, report the specific error and provide these remediation steps:

Step 3: Check Local SSH Keys

Run ls ~/.ssh/*.pub 2>/dev/null || echo 'No SSH public keys found'

If no keys exist, suggest: ssh-keygen -t ed25519 -C "your_email@example.com"

Step 4: Gather Available Locations

Run hcloud location list -o columns=name,city,country

Report all available datacenters for user reference.

Step 5: Gather SSH Keys from Hetzner

Run hcloud ssh-key list -o columns=name,fingerprint

If no keys are registered, note that one must be uploaded before server creation: hcloud ssh-key create --name my-key --public-key-from-file ~/.ssh/id_ed25519.pub

Step 6: Gather Server Types with Live Pricing

CRITICAL: Query real pricing data. Do NOT make up prices or use cached data.

First, fetch all server types to a temp file:

hcloud server-type list -o json > /tmp/hcloud-types.json

Then find the cheapest server in each tier using jq:

Recommended tier (4 vCPU, 8 GB RAM) - This is the preferred cx33 tier:

jq '[.[] | select(.cores == 4 and .memory == 8)] | sort_by(.prices[0].price_monthly.gross | tonumber) | .[0] | {name, cores, memory, disk, price: .prices[0].price_monthly.gross}' /tmp/hcloud-types.json

Budget tier (2 vCPU, 4 GB RAM):

jq '[.[] | select(.cores == 2 and .memory == 4)] | sort_by(.prices[0].price_monthly.gross | tonumber) | .[0] | {name, cores, memory, disk, price: .prices[0].price_monthly.gross}' /tmp/hcloud-types.json

Premium tier (8 vCPU, 16 GB RAM):

jq '[.[] | select(.cores == 8 and .memory == 16)] | sort_by(.prices[0].price_monthly.gross | tonumber) | .[0] | {name, cores, memory, disk, price: .prices[0].price_monthly.gross}' /tmp/hcloud-types.json

If jq is not installed, fall back to:

hcloud server-type list -o columns=name,cores,memory,disk

And note that jq should be installed for pricing data.

Step 7: Check Existing Servers

Run hcloud server list -o columns=name,status,ipv4,type

This helps avoid naming conflicts and shows current infrastructure state.

Output Format

After running all checks, provide a structured summary in this exact format:

═══════════════════════════════════════════════════════════
           HETZNER CLOUD PREFLIGHT CHECK RESULTS
═══════════════════════════════════════════════════════════

Prerequisites: [OK/FAILED]
├── hcloud CLI: [version number]
├── HCLOUD_TOKEN: [Set/Not set]
├── Authentication: [Valid/Failed - reason if failed]
└── Local SSH Keys: [Found/Not found]

Available Locations:
[List each location with city and country]

Registered SSH Keys:
[List each key name and fingerprint, or "None registered"]

Server Options (live pricing from Hetzner API):
┌─────────────┬──────────────────────────────────────────────┐
│ Tier        │ Details                                      │
├─────────────┼──────────────────────────────────────────────┤
│ RECOMMENDED │ [name] - 4 vCPU, 8 GB RAM, [disk]GB - €[price]/mo │
│ Budget      │ [name] - 2 vCPU, 4 GB RAM, [disk]GB - €[price]/mo │
│ Premium     │ [name] - 8 vCPU, 16 GB RAM, [disk]GB - €[price]/mo │
└─────────────┴──────────────────────────────────────────────┘

★ Preferred: cx33 (4 vCPU, 8 GB RAM) offers the best balance of
  performance and cost for most workloads.

Existing Servers: [count]
[List each server with name, status, IP, and type - or "None"]

═══════════════════════════════════════════════════════════

Error Handling

  • If any step fails, clearly indicate which step failed and why
  • Provide specific remediation steps for each failure type
  • Do not proceed past authentication failures
  • Always clean up temp files: rm -f /tmp/hcloud-types.json

Important Notes

  • Never fabricate pricing data - always query the live API
  • Highlight cx33 as the recommended option when discussing server selection
  • If the user's HCLOUD_TOKEN appears invalid, do not expose it in error messages
  • Be proactive about identifying potential issues (e.g., no SSH keys registered)

Sponsors

Details

Marketplace
MarkusOdenthal/the-knowledge-stack
Source
hetzner-vps
Author
Markus Odenthal
Category
Infrastructure