Concepts

Hetscale is a control plane, not a platform: it reads metrics and calls the Hetzner Cloud API in your project. Your traffic goes from your load balancer to your servers and never passes through Hetscale.

Node and node group

A node is one Hetzner Cloud server. A node group is a set of identical, stateless nodes behind one load balancer that scale together within a minimum and a maximum. Most setups have one group, for example “web”. Plans limit how many groups you can define, not how many nodes they hold.

Seed server

The existing server you point Hetscale at joins the group as an adopted, protected member. It counts toward capacity, but scale-in never selects it and healing never replaces it; if it becomes unhealthy, Hetscale alerts and starts a managed node beside it. The group’s template is taken from it. Promotion to a normal managed member is an explicit action with a confirmation: a server deleted by scale-in loses its legacy price.

Template and release

The template is what a new node is made of: server type, locations, network, firewall, SSH keys and labels. The release is what it runs: a snapshot id, an image digest or a Coolify deployment. Each group holds a current release pointer; every scale-out and every healing action boots from it, never from :latest. Your CI can move the pointer; for the snapshot adapter, a new snapshot of the seed is the next release. Nodes on an older release are stale and can be replaced surge-then-remove: create from current, wait for health, then drain one stale node.

Adapter

The adapter is the way a node gets your application: snapshot (clone of the seed), webhook (a signed node.created event your pipeline acts on) or Coolify (the node is registered in your Coolify instance and deployed). Adapters are distribution channels; the scaling engine does not depend on them.

Traffic provider and readiness

The traffic provider is the load balancer in front of the group: a Hetzner Cloud Load Balancer or Cloudflare Load Balancing. Its per-target health status is the readiness authority. A node becomes ACTIVE, counts toward capacity and receives traffic only when the provider reports it healthy. Adapter completion and ready callbacks are advisory. A node that never turns healthy before the deadline (default 15 minutes) is destroyed and reported with the load balancer’s reason.

Drain

Removing a node means: remove it from the load balancer, wait the group’s drain window (default 60 seconds, up to 300, which is the load balancer’s own limit), shut the server down so the application exits cleanly, then delete it. A node is never deleted while it is still a target.

Healing

A node is failed after 3 minutes of unhealthy status at the load balancer while Hetzner does not report it as rebooting. Hetscale creates a replacement beside it from the current release and routes to it once healthy. The failed node is not deleted by healing; it is kept out of traffic for diagnosis and cleaned up by you or by a normal scale-in. If the replacement fails too, healing stops after that one attempt and alerts: two failures in a row point at the release.

Ownership labels

Every server Hetscale creates carries the labels hetscale.dev/managed=true, hetscale.dev/group=<id> and hetscale.dev/node=<ulid> and the name hetscale-<group>-<ulid>. Before any destructive call, all three and the ledger must agree; anything else in the project is listed and never touched. During creation a fourth label, hetscale.dev/op, ties the server to the intent that requested it, so a retry adopts a half-created server instead of creating a second one.

Modes

Observe reads only and records what it would have done. Rehearsal is a supervised dry run of one node. Propose waits for your approval before each action. Live acts inside your range. The mode decides whether Hetscale may call the Hetzner API; it never changes how a decision is made or explained. See Modes.