Command line and Terraform

The HepCloud API follows the hcloud API standard. In practice that means you don't have to learn a new toolchain — you point the tools you already use at HepCloud.

Create an API token in the panel before you start: API tokens.

The hcloud command line tool

hcloud is a single-file command line tool; official builds for Windows, macOS and Linux are on the GitHub releases page.

Which API it talks to is set with the --endpoint option:

hcloud --endpoint https://api.hepcloud.net/v1 --token <token> server list

Set two environment variables so you don't have to repeat them.

Windows (PowerShell):

$env:HCLOUD_ENDPOINT = "https://api.hepcloud.net/v1"
$env:HCLOUD_TOKEN = "<token>"

macOS / Linux:

export HCLOUD_ENDPOINT=https://api.hepcloud.net/v1
export HCLOUD_TOKEN=<token>

An environment variable lives in that window

A value set with $env: in PowerShell only exists in the window you set it in; open a new window and you have to set it again. Use the Windows environment variable settings to make it permanent.

After that, commands are short:

hcloud server list
hcloud server describe web-01
hcloud ssh-key list
hcloud firewall list

Creating a server:

hcloud server create --name web-01 --type TRX-2G --image ubuntu-24.04 --ssh-key laptop

Keep the token out of your shell history

Typing the token into the command puts it in your shell history. Use the environment variable, and never commit a token to a repository, a script or a screenshot.

Terraform

The hcloud Terraform provider accepts an endpoint too:

terraform {
  required_providers {
    hcloud = {
      source = "hetznercloud/hcloud"
    }
  }
}

provider "hcloud" {
  token    = var.hepcloud_token
  endpoint = "https://api.hepcloud.net/v1"
}

variable "hepcloud_token" {
  type      = string
  sensitive = true
}

Don't put the token in a file; pass it with the TF_VAR_hepcloud_token environment variable.

A small stack — SSH key, firewall and server:

resource "hcloud_ssh_key" "laptop" {
  name       = "laptop"
  public_key = file("~/.ssh/id_ed25519.pub")
}

resource "hcloud_firewall" "web" {
  name = "web"

  rule {
    direction  = "in"
    protocol   = "tcp"
    port       = "22"
    source_ips = ["0.0.0.0/0"]
  }

  rule {
    direction  = "in"
    protocol   = "tcp"
    port       = "443"
    source_ips = ["0.0.0.0/0"]
  }
}

resource "hcloud_server" "web" {
  name         = "web-01"
  server_type  = "TRX-2G"
  image        = "ubuntu-24.04"
  ssh_keys     = [hcloud_ssh_key.laptop.id]
  firewall_ids = [hcloud_firewall.web.id]
}

output "ip" {
  value = hcloud_server.web.ipv4_address
}

terraform init followed by terraform apply builds it.

Server type and image names

Use the names you see in the panel for server_type and image (TRX-2G, ubuntu-24.04). You can also list them with hcloud server-type list and hcloud image list.

Supported resources

The resources these tools offer are limited to what HepCloud actually has:

Resource	Status
Servers	Create, power actions, resize, rebuild, delete
SSH keys	Full support
Firewalls	Edit rules, apply to and remove from servers
Primary IPs and rDNS	Full support
Server types, images, locations	Read only
Actions	Read only — the status of long-running work

A tool that calls a resource not on this list gets not_found.

Account operations are closed to the API

Balance, billing details, sessions, two-factor authentication and token management are panel-only. That is a deliberate boundary rather than a gap: it stops a leaked token from taking over your account, minting new tokens or turning off your 2FA.

Writing your own script

If you need something specific, call the API directly:

curl -H "Authorization: Bearer $HCLOUD_TOKEN" \
  https://api.hepcloud.net/v1/servers

Every endpoint with its request and response bodies: API reference.