Add a GPU host

Each GPU host runs one node agent. Adding a host connects another computer with a GPU to the same instance.

1. Prepare the host

• Linux with a working GPU driver (ls /dev/dri shows a renderD* node).
• Docker or Podman, in a supported engine mode. The command detects which.
• The host steps for its engine: Docker, Podman, or rootless. For NVIDIA, complete NVIDIA setup.
• A shell as the account that runs the engine: root for rootful Podman, root (or passwordless sudo) for rootful Docker, the quasar account for a rootless engine.
• Network access to the control plane’s https:// address, plus a direct LAN or VPN route from each player’s browser to this computer.

2. Generate the command

In the admin console, go to Fleet ▸ Hosts and press Add host. Optionally name the host (reusing an existing name re-enrolls it), pick how long the command stays valid, and press Create command. You get:

curl -fsSL -k --pinnedpubkey 'sha256//<key hash>' https://<control-plane>/enroll-host.sh \
  | QUASAR_ENROLLMENT='qenr1.…' sh

The enrollment string contains the instance address, certificate pin and single-use token. It is private; the token is not embedded in the URL. The address in it is always wss://. A host set up over ws:// instead needs QUASAR_ALLOW_PLAINTEXT_AGENT=1 and sends the token and node secret in cleartext.

3. Inspect the script

Read the enrollment script before running it: run the same curl with -o enroll-host.sh instead of the pipe. Keep the generated command unchanged and the single-use token private. If the dialog shows a certificate fingerprint, check it matches the fingerprint= the control plane printed at startup.

4. Run it

Paste the command on the new machine.

• Rootful Podman: run it as root (sudo -i, then paste). Its socket is visible to root only; from any other account the command reports no container engine found.
• Rootless: open a session as the quasar account first (sudo machinectl shell quasar@, see Install with Podman).

The script checks the host, offers to fix anything missing, then pulls the images and starts Quasar. It’s safe to run again.

5. Confirm it worked

The script ends with:

enrolled: this host is now '<name>' in Admin → Fleet.

The host appears online in Fleet ▸ Hosts within seconds.

When it says no

The last line names the reason. A failed install removes itself: fix the cause and run a fresh command.

Message	Fix
auth_failed	The token expired, was used, or is for another name. Create a new command.
Name already registered	That host’s agent is still connected. Stop it, or pick another name. If the machine is gone, forget the host first with the admin API (DELETE /v1/hosts/{id}); that deletes its history and tombstones its homes.
cp-tls-pin-mismatch	The certificate doesn’t match. Create the command from the control plane’s own page.
A host check failed	Apply the printed fix and rerun the same command.
Old Compose agent found	Run docker compose --project-directory /opt/quasar-agent down (homes are kept), then rerun.
A seed already exists	Quasar is already installed here. Keep it, or remove it first.
Still connecting	Check docker logs -f quasar-node-agent. Usually the control plane’s address isn’t reachable from this machine.

To re-enroll a machine that was installed before, put QUASAR_RESET_IDENTITY=1 in front of sh. It removes that machine’s Quasar containers and volumes (never the homes) and starts over. It refuses on a machine that runs the control plane.

More: Install and startup problems.

Options

Set in front of sh, like the token. sh enroll-host.sh --help lists them all.

Variable	Default	Purpose
QUASAR_HOME_ROOT	/var/lib/quasar/homes	Where user homes live on this machine.
QUASAR_NODE_NAME	the machine’s host name	The host’s name, if the command didn’t set one.
QUASAR_ENROLL_FIX	off	1 fixes failed checks without asking.
QUASAR_ENROLL_DRY_RUN	off	1 checks the host and starts nothing.

Using Dockge or Arcane

The dialog’s Dockge or Arcane tab gives you a stack to paste instead. You then prepare the host yourself (render node, /dev/uinput, user namespaces, AppArmor); the host’s readiness card lists anything missing.

Storage across hosts

To have saves follow a user between hosts, put the home roots on shared storage. Otherwise, set the locality placement policy so Quasar prefers the host that already has the user’s home.