hetzner-cloud

---
name: hetzner-cloud
description: >-
  Manage Hetzner Cloud infrastructure from the terminal. Use when a user asks
  to create a Hetzner server, manage VPS instances, set up firewalls, configure
  networks, manage volumes, create snapshots, handle SSH keys, or provision
  infrastructure on Hetzner. Covers the hcloud CLI for all resource types.
  For deploying applications on top of Hetzner servers, see coolify.
license: Apache-2.0
compatibility: "Requires hcloud CLI installed. Install: brew install hcloud (macOS) or snap install hcloud (Linux) or download from https://github.com/hetznercloud/cli"
metadata:
  author: terminal-skills
  version: "1.0.0"
  category: devops
  tags: ["hetzner", "cloud", "vps", "infrastructure", "hosting"]
---

# Hetzner Cloud

## Overview

Provision and manage Hetzner Cloud infrastructure from the terminal using the `hcloud` CLI. Covers servers, networks, firewalls, volumes, snapshots, SSH keys, and load balancers. Hetzner offers high-performance VPS instances at competitive prices, commonly used to host self-managed platforms like Coolify.

## Instructions

When a user asks for help with Hetzner Cloud, determine which task they need:

### Task A: Initial setup

```bash
# Authenticate with an API token
hcloud context create my-project
# Paste your API token when prompted (from Hetzner Cloud Console > API Tokens)

# List configured contexts
hcloud context list

# Switch context
hcloud context use my-project
```

### Task B: Server management

```bash
# List available server types with pricing
hcloud server-type list

# List available images (OS options)
hcloud image list --type system

# Create a server
hcloud server create \
  --name my-server \
  --type cx22 \
  --image ubuntu-24.04 \
  --location fsn1 \
  --ssh-key my-key

# List servers
hcloud server list

# Get server details
hcloud server describe my-server

# SSH into a server
hcloud server ssh my-server

# Stop/start/reboot
hcloud server shutdown my-server
hcloud server poweron my-server
hcloud server reboot my-server

# Resize a server (requires poweroff first)
hcloud server shutdown my-server
hcloud server change-type my-server --server-type cx32

# Rebuild with a different OS
hcloud server rebuild my-server --image ubuntu-24.04

# Enable rescue mode (for recovery)
hcloud server enable-rescue my-server --type linux64 --ssh-key my-key

# Delete a server
hcloud server delete my-server
```

**Common server types:**

| Type | vCPU | RAM | Disk | Use case |
|------|------|-----|------|----------|
| cx22 | 2 | 4 GB | 40 GB | Small apps, staging |
| cx32 | 4 | 8 GB | 80 GB | Production apps |
| cx42 | 8 | 16 GB | 160 GB | Databases, heavy workloads |
| cx52 | 16 | 32 GB | 240 GB | High-traffic applications |
| ccx13 | 2 | 8 GB | 80 GB | Dedicated vCPU, consistent performance |

**Locations:** `fsn1` (Falkenstein), `nbg1` (Nuremberg), `hel1` (Helsinki), `ash` (Ashburn), `hil` (Hillsboro), `sin` (Singapore).

### Task C: Networking

```bash
# Create a private network
hcloud network create --name my-network --ip-range 10.0.0.0/16

# Add a subnet
hcloud network add-subnet my-network --type server --network-zone eu-central --ip-range 10.0.1.0/24

# Attach server to network
hcloud server attach-to-network my-server --network my-network --ip 10.0.1.2

# Create a firewall
hcloud firewall create --name web-firewall

# Add firewall rules
hcloud firewall add-rule web-firewall --direction in --protocol tcp --port 22 --source-ips 0.0.0.0/0 --description "SSH"
hcloud firewall add-rule web-firewall --direction in --protocol tcp --port 80 --source-ips 0.0.0.0/0 --description "HTTP"
hcloud firewall add-rule web-firewall --direction in --protocol tcp --port 443 --source-ips 0.0.0.0/0 --description "HTTPS"

# Apply firewall to server
hcloud firewall apply-to-resource web-firewall --type server --server my-server

# Allocate a floating IP
hcloud floating-ip create --type ipv4 --home-location fsn1 --description "Production IP"

# Assign floating IP to server
hcloud floating-ip assign <floating-ip-id> my-server
```

### Task D: Volumes and snapshots

```bash
# Create a volume
hcloud volume create --name data-volume --size 50 --server my-server --format ext4

# List volumes
hcloud volume list

# Resize a volume (online, no downtime)
hcloud volume resize data-volume --size 100

# Detach/attach a volume
hcloud volume detach data-volume
hcloud volume attach data-volume --server other-server

# Create a server snapshot
hcloud server create-image my-server --type snapshot --description "Before upgrade"

# List snapshots
hcloud image list --type snapshot

# Create a server from a snapshot
hcloud server create --name restored-server --type cx22 --image <snapshot-id> --ssh-key my-key

# Delete a snapshot
hcloud image delete <snapshot-id>
```

### Task E: SSH keys and security

```bash
# Upload an SSH key
hcloud ssh-key create --name my-key --public-key-from-file ~/.ssh/id_ed25519.pub

# List SSH keys
hcloud ssh-key list

# Delete an SSH key
hcloud ssh-key delete my-key
```

### Task F: Set up a server for Coolify

A common workflow — provision a Hetzner server and install Coolify:

```bash
# 1. Create a server (cx32 recommended for Coolify)
hcloud server create \
  --name coolify-server \
  --type cx32 \
  --image ubuntu-24.04 \
  --location fsn1 \
  --ssh-key my-key

# 2. Create and apply a firewall
hcloud firewall create --name coolify-firewall
hcloud firewall add-rule coolify-firewall --direction in --protocol tcp --port 22 --source-ips 0.0.0.0/0 --description "SSH"
hcloud firewall add-rule coolify-firewall --direction in --protocol tcp --port 80 --source-ips 0.0.0.0/0 --description "HTTP"
hcloud firewall add-rule coolify-firewall --direction in --protocol tcp --port 443 --source-ips 0.0.0.0/0 --description "HTTPS"
hcloud firewall add-rule coolify-firewall --direction in --protocol tcp --port 8000 --source-ips 0.0.0.0/0 --description "Coolify UI"
hcloud firewall apply-to-resource coolify-firewall --type server --server coolify-server

# 3. Get the server IP
hcloud server ip coolify-server

# 4. SSH in and install Coolify
ssh root@<server-ip> "curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash"
```

After installation, access Coolify at `http://<server-ip>:8000` and complete the setup wizard.

## Examples

### Example 1: Provision a production server with firewall and volume

**User request:** "Create a Hetzner server for my production app with a firewall and a 100GB data volume"

**Steps taken:**
```bash
# Create the server
$ hcloud server create --name prod-api --type cx32 --image ubuntu-24.04 --location fsn1 --ssh-key deploy-key
Server 12345678 created

# Create and configure firewall
$ hcloud firewall create --name prod-firewall
$ hcloud firewall add-rule prod-firewall --direction in --protocol tcp --port 22 --source-ips 203.0.113.0/32 --description "SSH from office"
$ hcloud firewall add-rule prod-firewall --direction in --protocol tcp --port 443 --source-ips 0.0.0.0/0 --description "HTTPS"
$ hcloud firewall apply-to-resource prod-firewall --type server --server prod-api

# Attach a data volume
$ hcloud volume create --name prod-data --size 100 --server prod-api --format ext4
Volume 87654321 created and attached at /mnt/HC_Volume_87654321
```

### Example 2: Create a snapshot before a risky upgrade

**User request:** "Take a snapshot of my server before I upgrade the database"

**Steps taken:**
```bash
$ hcloud server create-image my-server --type snapshot --description "Pre-DB-upgrade 2024-01-15"
Image 11223344 created from server my-server (status: creating)

# Verify snapshot is ready
$ hcloud image describe 11223344
Status: available
Size: 18.40 GB
Created: 2024-01-15T10:30:00+00:00

# After upgrade, if something goes wrong:
# hcloud server rebuild my-server --image 11223344
```

## Guidelines

- Always create a firewall before exposing a server to the internet. At minimum, restrict SSH to known IPs.
- Use SSH keys instead of passwords. Hetzner disables password auth by default on new servers.
- Take snapshots before risky operations (OS upgrades, database migrations). Snapshots are billed by size.
- For Coolify servers, `cx32` (4 vCPU, 8 GB RAM) is the recommended minimum. `cx22` works for testing.
- Use private networks for server-to-server communication instead of public IPs.
- Volumes can be resized up (not down) without downtime. Plan initial sizes conservatively.
- Floating IPs let you swap servers behind a stable IP address — useful for zero-downtime migrations.
- Server types can be upgraded (not downgraded for shared types). The server must be powered off during resize.
- Use `hcloud server list -o columns=name,status,ipv4,server_type` for clean output in scripts.
- Hetzner locations in Europe (fsn1, nbg1, hel1) generally have the best pricing. US and Asia locations cost more.