Hetzner Cloud: Creating and Configuring Servers via API

Hetzner Cloud: the Best European Cloud

Hetzner Cloud is a German cloud provider with servers in Germany, Finland, and the US. Its price/performance ratio is one of the best on the market: a CX22 (2 vCPU / 4 GB) costs €4.35/month.

Installing the hcloud CLI

# Linux
wget https://github.com/hetznercloud/cli/releases/latest/download/hcloud-linux-amd64.tar.gz
tar -xzf hcloud-linux-amd64.tar.gz
mv hcloud /usr/local/bin/

# Authentication (token from Cloud Console)
hcloud context create my-project
# Enter your API token

Creating a Server

# View available server types
hcloud server-type list

# View images
hcloud image list --type system

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

# List servers
hcloud server list

Firewall via CLI

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

hcloud firewall add-rule web-firewall \
  --direction in --protocol tcp --port 22 \
  --source-ips 0.0.0.0/0,::0/0

hcloud firewall add-rule web-firewall \
  --direction in --protocol tcp --port 80 \
  --source-ips 0.0.0.0/0,::0/0

hcloud firewall add-rule web-firewall \
  --direction in --protocol tcp --port 443 \
  --source-ips 0.0.0.0/0,::0/0

# Apply to the server
hcloud firewall apply-to-server web-firewall --server web-01

Managing via API (cURL)

TOKEN="your_api_token"

# List servers
curl -H "Authorization: Bearer $TOKEN" \
  https://api.hetzner.cloud/v1/servers

# Create a server via API
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "api-server",
    "server_type": "cx22",
    "image": "ubuntu-24.04",
    "location": "nbg1"
  }' \
  https://api.hetzner.cloud/v1/servers

Floating IP and Load Balancer

# Create a Floating IP
hcloud floating-ip create --type ipv4 --home-location nbg1

# Assign it to the server
hcloud floating-ip assign 12345678 --server web-01

# Create a Load Balancer
hcloud load-balancer create \
  --name lb-01 \
  --type lb11 \
  --location nbg1

hcloud load-balancer add-target lb-01 \
  --type server --server web-01

Snapshots and Backups

# Create a snapshot
hcloud server create-image web-01 \
  --type snapshot \
  --description "Before update $(date +%Y-%m-%d)"

# Enable auto-backup
hcloud server enable-backup web-01

Real API Errors Explained

The Hetzner Cloud API returns structured JSON errors with a code field — that makes it easy to understand the cause without guessing from the HTTP status alone.

resource_unavailable

{"error":{"code":"resource_unavailable","message":"Server type cx22 not available in location nbg1"}}

Not every server type is available in every data center — for example, some CCX or CPX lines may be unavailable in a specific location due to capacity load. Check availability for a specific combination with hcloud server-type list and try a neighboring region (fsn1, hel1).

uniqueness_error

{"error":{"code":"uniqueness_error","message":"resource already exists"}}

The server, SSH key, or firewall name is already taken in your project — Hetzner requires unique names for resources of the same type within a project. Add a suffix with the date or environment: web-01-prod instead of just web-01.

Comparing Hetzner Server Lines

When Hetzner Cloud Is Not a Good Fit

• You need a physical dedicated server with full control over the hardware — that is the Hetzner Dedicated/Robot line, a separate product with a different API, not hcloud.
• You need a data center outside Europe or the US East region — Hetzner Cloud has no regions in Asia, South America, or Africa.
• You need an official Windows Server image from the catalog — hcloud's image list is oriented primarily toward Linux distributions.
• You need a wide selection of GPU instances for ML inference — Hetzner Cloud's GPU lineup is noticeably narrower than AWS's or GCP's.
• You need managed Kubernetes with a control plane run by the provider itself — Hetzner Cloud only gives you raw VPS instances; you have to deploy k3s or a full cluster yourself.

Verifying the Result

# The server was created and is in the running state
hcloud server describe web-01 -o json | grep status

# The firewall is actually applied to the server
hcloud firewall describe web-firewall

# SSH works via key, not password
ssh -o PasswordAuthentication=no -o PreferredAuthentications=publickey root@SERVER_IP echo ok

# The API token works and can see the project
curl -s -o /dev/null -w "%{http_code}\n" -H "Authorization: Bearer $TOKEN" https://api.hetzner.cloud/v1/servers

A 401 response code from the API means an invalid or revoked token — reissue it in Cloud Console (Security → API Tokens). If the server is created as part of a recurring process, move the steps into a Terraform configuration instead of manual hcloud calls, and deploy the application onto the finished server through CI/CD with GitHub Actions.