Deploy to Hetzner Cloud

Run nebula deploy to deploy Nebula to Hetzner Cloud. The command creates one virtual machine (VM) for the orchestrator and gateway and lets the orchestrator create one VM per worker. The orchestrator hosts the control plane and keeps it, with every saved entity, in a SQLite file on its VM or in a PostgreSQL database you point it at.

The deployment uses the same game build as a local mesh. It starts the orchestrator with -nebula-host hetzner instead of -nebula-host process. To run the mesh on the hosted service instead, see Deploy to Nebula Cloud.

Prerequisites

• A Hetzner Cloud project and a Read & Write API token for it (console.hetzner.cloud, project, Security, API tokens). The token is checked against the API when you configure it.
• Optionally, a PostgreSQL server the orchestrator VM can reach, for a world that must outlive the VM. Without one the orchestrator uses SQLite on its own disk.
• Unity with Linux Dedicated Server support installed for the project's Unity version. nebula deploy builds Builds/Linux64/Nebula.x86_64 with the Server subtarget; without the module the build fails.
• ssh and scp on your PATH. The CLI creates and uses ~/.ssh/nebula_hetzner.
• The nebula CLI installed and a project with nebula.json (see Install).

Configure the deployment

Two one-time steps. Both write to ~/.nebula-cli/config.json (0600 on Unix) and to the project's nebula.json.

nebula config hetzner
nebula config database

nebula config hetzner asks for the token, project label, region, worker VM type, and orchestrator VM type. Pass --token to supply the token as an option. The command verifies the token and sets deploy.target to hetzner in nebula.json.

Set HCLOUD_TOKEN to override the saved token, such as in continuous integration (CI).

nebula config database is optional. It stores a database URL (--url) for deployed meshes in the CLI config: postgres://user:password@host:5432/nebula for PostgreSQL, or default for SQLite on the orchestrator VM. deploy.database in nebula.json and NEBULA_DATABASE_URL in the environment take precedence over it.

The deploy section of nebula.json

{
  "deploy": {
    "target": "hetzner",
    "meshName": "nebula",
    "database": "postgres://nebula:secret@db.example.com:5432/my-game",
    "workers": 4,
    "workerType": "ccx13",
    "orchestratorType": "cpx21",
    "location": "ash"
  }
}

The mesh section (dashboardPort 7080, gatewayPort 7000) is shared with the local mesh and also sets the ports the firewall opens.

Deploy

nebula deploy --workers 4 --open-ui

nebula status --cloud
nebula logs --cloud orchestrator
nebula logs --cloud w1

Builds\Win64\Nebula.exe -nebula-role client -nebula-gateway <orchestrator public ip>:7000 -nebula-name Player

Topology

            you (client / bot)                     Hetzner project my-game, location ash
                    │ udp/7000                     ┌─────────────────────────────────────────────────────┐
                    ▼                              │  nebula-orchestrator VM (public IP)                  │
  ┌───────────────────────────────┐   HCLOUD API   │   Nebula.x86_64 -nebula-role orchestrator            │
  │ api.hetzner.cloud             │◄───────────────│     -nebula-host hetzner  (creates/deletes worker VMs)│
  └───────────────────────────────┘                │     dashboard :7080, serves /build/nebula-linux.tar.gz│
                                                   │   gateway process  udp/7000                          │
  ┌───────────────────────────────┐                │   control plane + saved entities at :7080/api/    │
  │ PostgreSQL (optional)         │◄───────────────│     in /opt/nebula/data/nebula.db, or PostgreSQL     │
  │ my-game                       │  NEBULA_DATABASE_URL           │ private net   │ 10.0.1.0/24
  └───────────────────────────────┘                └───────────────▲───────────────▲─────────────────────┘
                                                          ┌────────┴───────┬───────┴─────────┐
                                                          │ orch1-w1-1 VM  │ orch1-w2-2 VM   │ ...
                                                          │ worker udp/7101│ worker udp/7102 │
                                                          └────────────────┴─────────────────┘

The orchestrator VM runs two processes: the orchestrator (dashboard, worker host) and the gateway it launches through the process host. The systemd unit's command line is:

Nebula.x86_64 -batchmode -nographics -nebula-role orchestrator -nebula-host hetzner
  -nebula-workers 4 -nebula-min-workers 4 -nebula-max-workers 4 -nebula-idle-pool 0
  -nebula-dashboard-port 7080 -nebula-dashboard-bind + -nebula-build-dir /opt/nebula/artifacts
  -nebula-advertise <private ip> -nebula-gateway <public ip>:7000
  -nebula-cloud-mesh nebula -nebula-cloud-location ash -nebula-cloud-type cpx21 -nebula-cloud-image ubuntu-24.04
  -nebula-cloud-network nebula -nebula-cloud-sshkey nebula -nebula-cloud-firewall nebula-worker
  -logFile /var/log/nebula/orchestrator.log

-nebula-advertise is the orchestrator's private IP: workers reach the gateway, the control plane, and the build download over the private network. -nebula-gateway is the public address the gateway registers so clients can find it. The database URL, the mesh token, and the player signing key come from /etc/nebula/env, not the command line. --verbose on nebula deploy adds -nebula-verbose.

How worker VMs boot

HetznerWorkerHost creates each worker VM (<mesh>-<workerId>-<generation>, labels nebula-mesh, nebula-role=worker, nebula-worker=wN) with an Ubuntu 24.04 image, the ssh key, the private network, the worker firewall, a public IPv4 and a cloud-init script (HetznerWorkerHost.BuildCloudInit) that:

1. Logs to /var/log/nebula-bootstrap.log.
2. Reads its private IP from the Hetzner metadata service (169.254.169.254/hetzner/v1/metadata/private-networks), falling back to the first 10.* address, retrying for up to two minutes.
3. Downloads http://<orchestrator private ip>:7080/build/nebula-linux.tar.gz from the orchestrator's /build/ route, retrying up to 90 times.
4. Unpacks it into /opt/nebula, writes the deployment's environment variables (deploy.env) to /etc/nebula/worker.env, readable only by root, and writes nebula-worker.service, which loads that file and runs Nebula.x86_64 -batchmode -nographics -nebula-role worker -nebula-worker-id wN -nebula-worker-index N -nebula-port 710N -nebula-advertise <private ip> ... with -logFile /var/log/nebula-worker.log.
5. Starts the unit. Restart=no: if the worker dies, the orchestrator notices through heartbeats and replaces the VM.

From the create call to a registered, container-owning worker takes about 30 s. Killing a worker (dashboard Kill, POST /api/workers/kill) deletes its VM; removing one drains it first and then deletes it. When the orchestrator starts it deletes every VM labelled nebula-mesh=<mesh>,nebula-role=worker before launching fresh ones, so a crashed or redeployed orchestrator never leaves machines billing.

Ports

The firewalls are <meshName>-orchestrator (22, the dashboard port, the gateway port over UDP and TCP, the gateway port plus one over UDP, and TCP port 80, from anywhere) and <meshName>-worker (22 only). Each deployment adds missing required rules and keeps rules you added. Traffic on the private network is not filtered by Hetzner firewalls.

Choose VM types

Worker and orchestrator VMs default to cpx21. A four-worker mesh uses five VMs: four workers and one orchestrator.

Use a dedicated-vCPU VM type when you need stable performance measurements. Set deploy.workerType in nebula.json, then run nebula deploy again. Check Hetzner's current pricing before you deploy.

Operate the deployment

Open the Nebula Dashboard at http://<public-ip>:7080/. Copy the gateway address for your client, change the worker count, add or remove workers, stop a worker to test recovery, and edit your game's shared settings. Worker changes create or delete virtual machines. See Orchestrator, Nebula Dashboard and worker hosts.

Log file paths on the VMs, for when you ssh in yourself (ssh -i ~/.ssh/nebula_hetzner root@<ip>):

Remove the deployment

nebula destroy
nebula destroy --all

destroy lists the servers labelled with the mesh, asks for confirmation (--yes skips it) and deletes them all, workers and orchestrator. --all also deletes the firewalls, the private network and the ssh key after a short wait for the servers to detach. A SQLite database on the orchestrator VM goes with the VM, and with it every saved entity; a PostgreSQL database is left in place. The ssh key file in ~/.ssh is left alone.

Security and operations

• The control plane is protected by the mesh token only. Workers and the gateway present the token nebula deploy generated; without it the orchestrator answers 401, and the gateway and workers refuse a peer that cannot present a credential derived from it. The token lives in /etc/nebula/env on the orchestrator VM and on the worker VMs' command lines.
• The player signing key lives on the orchestrator VM. NEBULA_AUTH_KEY in /etc/nebula/env signs anonymous identities and session tokens. nebula deploy keeps it across deployments; nebula destroy deletes it with the VM, and every anonymous player then becomes a new player. Copy the value out of the file first if you rebuild the VM and want to keep them.
• The dashboard is unauthenticated. Anyone who can reach tcp/7080 can resize or kill the mesh. Restrict the orchestrator firewall's dashboard rule to your own IP (the firewall is created by nebula deploy; edit it in the Hetzner console).
• SQLite lives and dies with the VM. Point the mesh at PostgreSQL (nebula config database) when the saved world must survive nebula destroy or a lost VM.
• Replacing a worker takes about 30 s: a fresh VM boots, downloads the build and registers. Its transient entities are gone; players respawn through OnSpawnPlayer.
• nebula deploy restarts the mesh. Every deploy restarts the orchestrator and recreates every worker.
• One mesh per Hetzner project, labelled with meshName.