portal-relay-hetzner
Create a Hetzner Cloud server for a Portal relay with the hcloud CLI, attach a Hetzner Cloud Firewall that opens only the relay ports, keep a stable primary IPv4, and hand the host to portal-relay for
SKILL.mdplugins/portal-relay/skills/portal-relay-hetzner/SKILL.md
GitHubPortal relay on Hetzner Cloud
This skill creates and opens the host. portal-relay deploys the relay on it. Follow ../portal-relay/references/provider-contract.md (the portal-relay skill's contract in this same plugin; the path is relative to this file, so it matches the installed version and needs no network) for the phase order, credential rules, and approval rules. This file adds only what is specific to Hetzner Cloud.
Preflight
hcloud version. If the CLI is missing, point to the official hcloud install instructions and stop.hcloud context activenames the active project context, and a read-only call such ashcloud server-type list -o noheaderproves the token works here. Do not open~/.config/hcloud/cli.toml; it stores the token.
Authenticate
When no context works, ask the user to create a project API token in the Hetzner Console and run hcloud context create <name> locally; the CLI prompts for the token, so it never appears in chat or in shell history. A project token can change every resource in that project, so suggest a dedicated project for the relay. In a CI or sandbox environment that the user controls, HCLOUD_TOKEN in its secret store also works; never set it in a command line.
Plan
Collect and show, then wait for approval:
- Location (
hcloud location list) and server type (hcloud server-type list; read current names and prices fromhcloud server-type describe <type>instead of assuming them). The smallest Arm or x86 type is enough; the relay image supportslinux/arm64andlinux/amd64. - Image: a current Ubuntu image from
hcloud image list --type system. - SSH key: an existing key from
hcloud ssh-key list, or the user's public key added withhcloud ssh-key create --public-key-from-file. Without one Hetzner emails a root password; avoid that. - Firewall rules from the contract. Hetzner Cloud Firewalls allow only what a rule lists, so every port the relay needs must be present.
- Primary IPv4: billed separately from the server. Create it on its own (
hcloud primary-ip create --type ipv4 --name <name> --location <location>, with auto-delete off) and pass it with--primary-ipv4, so the glue address survives server re-creation. - Optional
--enable-protection delete,rebuildagainst accidental deletion.
Apply
hcloud firewall create --name <name> --rules-file rules.json, where each rule is{"direction": "in", "protocol": "tcp" | "udp", "port": "443" | "40000-40009", "source_ips": ["0.0.0.0/0", "::/0"]}(restrict SSH to the operator's address when known).hcloud server create --name <name> --type <type> --image <image> --location <location> --ssh-key <key> --firewall <firewall> --primary-ipv4 <ip>.- Read the address with
hcloud server ip <name>.
Ubuntu images on Hetzner Cloud have no extra host firewall by default; if the user enabled ufw, open the same ports there.
Verify
ssh root@<ip>works, and after deploymentdig @<ip> <relay domain> NSandcurl -fsS https://<relay domain>/api/healthzsucceed. A port that times out is usually missing from the Cloud Firewall.
Hand off
Then continue with the portal-relay skill from Verify the host, not from Deploy: a fresh image may lack Docker and Compose v2, and that step checks and, with approval, installs them. Use this host's public address as the glue address. The NS and glue records come before Deploy, at the common skill's Delegate DNS step, because the relay's first start needs them to issue its certificate; the DS comes after Deploy, at Publish the DS. Report the server, firewall, and primary IP with their hourly or monthly price, and rollback: hcloud server delete <name>, hcloud firewall delete <name>, and hcloud primary-ip delete <name> (disable protection first if it was enabled).
Portal can also use Hetzner DNS as its ACME DNS provider (ACME_DNS_PROVIDER=hetzner); that is a relay setting covered by the configuration reference, not by this skill, and Hetzner DNS does not support ENS DNSSEC automation.