Hetzner VPS Skill

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

Provisioning Workflow

Step 1: Pre-Flight Verification

Use the built-in Explore agent (Task tool with subagent_type: "Explore") to run preflight checks:

Verify Hetzner Cloud prerequisites:
1. Run `hcloud version` to check CLI installation
2. Run `hcloud server list` to verify authentication
3. Run `hcloud location list` to get available locations
4. Run `hcloud ssh-key list` to get registered SSH keys
5. Run `hcloud server-type list -o json > /tmp/hcloud-types.json` then use jq to find cheapest server in each tier:
   - Recommended (4 vCPU, 8 GB): jq '[.[] | select(.cores == 4 and .memory == 8)] | sort_by(.prices[0].price_monthly.gross | tonumber) | .[0]'
   - Budget (2 vCPU, 4 GB): jq '[.[] | select(.cores == 2 and .memory == 4)] | sort_by(.prices[0].price_monthly.gross | tonumber) | .[0]'
   - Premium (8 vCPU, 16 GB): jq '[.[] | select(.cores == 8 and .memory == 16)] | sort_by(.prices[0].price_monthly.gross | tonumber) | .[0]'
6. Run `hcloud server list` to check for existing servers

Report all findings with real data from the commands.

If authentication fails, direct user to references/prerequisites.md

Step 2: Gather User Preferences

Use AskUserQuestion to collect:

Option	Required	Default
Server name	Yes	-
SSH key	Yes	-
Location	Yes	-
Server type	No	Cheapest 4 vCPU, 8 GB option
Terminal setup	No	No
ccstatusline setup	No	No

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:

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

Flags Reference

Flag	Description
--name	Server name (must be unique)
--ssh-key	SSH key name from Hetzner Cloud
--location	Datacenter (fsn1, nbg1, ash, hil, hel1, sin)
--type	Server type (from preflight recommendation)
--user	Non-root username (default: claude)
--terminal-setup	Copy local zsh/oh-my-zsh/p10k config
--statusline-setup	Install bun and copy statusLine settings

Available Scripts

Script	Purpose
provision.sh	Create VPS with Claude Code
status.sh	Check VPS health
ssh-command.sh	Execute remote commands
inject-secret.sh	Inject 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