Daemon Setup

The TurboPanel daemon (turbopaneld) runs on managed servers. It connects to the instance over HTTPS/WSS, runs Ansible to install runtimes and services, and manages Docker, tunnels, and orchestration locally.

Overview

Purpose

• Connect to the instance control plane as a remote daemon
• Run Ansible playbooks (installs, upgrades, Postgres, Caddy, instance, UI)
• Apply dev-sync pushes and Cloudflare tunnel tokens from the instance
• Report server identity (serverId, hostname, machineId) on WebSocket hello

Relationship to control plane

The daemon is not a slim Docker-only executor in the new architecture — it is the constant on every TurboPanel-managed host and the only party that runs Ansible. On the control plane host it runs co-located (Unix socket or Caddy URL). On additional servers it dials the instance URL you provide at install time.

Architecture

Deployment models

Installation

Supported platforms

Not supported: 32-bit ARM (armv7l, armhf), 32-bit Raspberry Pi OS, or any CPU architecture other than aarch64 and x86_64. Unsupported hosts fail during Ansible provisioning with an explicit architecture error.

Remote managed server (official installer)

Obtain a license from your TurboPanel organization, then run the channel installer. Set TURBOPANEL_LICENSE to the base64url-encoded licenseId:licenseToken (the UI copy-paste command includes this).

TurboPanel High Availability (Cloudflare Workers — default host from the channel manifest):

curl -fsSL turbopanel.sh | TURBOPANEL_LICENSE=<base64url-encoded-license> sh

Self-hosted instance (pass TURBOPANEL_HOST with the full instance URL):

curl -fsSL turbopanel.sh | \
  TURBOPANEL_LICENSE=<base64url-encoded-license> \
  TURBOPANEL_HOST=https://<instance-host>:8443 \
  sh

Production and self-hosted instances always fetch the installer from turbopanel.sh. The instance host /run.sh path is development-only — it is served by the dev overlay Caddyfile (plaintext :8880), not by the production instance Caddyfile.

# Dev overlay only (plaintext HTTP control plane)
curl -fsSL http://<dev-host>:8880/run.sh | \
  TURBOPANEL_LICENSE=<base64url-encoded-license> \
  TURBOPANEL_HOST=http://<dev-host>:8880 \
  sh

The installer self-escalates with sudo and prompts for your password when needed — do not prefix the pipeline with sudo.

While provisioning runs, the terminal shows a rolling status view (spinner on TTY hosts) with neutral labels — orchestration instead of Ansible tool names, cache instead of Redis, queue instead of RabbitMQ. Vendor paths, role names, and env vars on disk are unchanged; full detail remains in /var/log/turbopanel/daemon.log after install. See the daemon repo AGENTS.md — Installer presentation layer.

For self-hosted HTTPS, the installer fetches the platform CA from GET /api/daemon/v1/instance/ca and configures TURBOPANEL_INSTANCE_CA. Re-run the same command any time to upgrade or reconcile a node.

Refresh an existing node

If the server is already installed, re-run the same run.sh installer. Build the license argument from state on disk (or copy a fresh install command from the UI):

LICENSE_B64=$(python3 -c "
import base64
id = open('/var/lib/turbopanel/license.id').read().strip()
tok = open('/var/lib/turbopanel/license.token').read().strip()
print(base64.urlsafe_b64encode(f'{id}:{tok}'.encode()).decode().rstrip('='))
")

curl -fsSL turbopanel.sh | \
  TURBOPANEL_LICENSE="$LICENSE_B64" \
  TURBOPANEL_UPDATE_CHANNEL=trunk \
  sh

See Refresh a stuck daemon for offline UI mismatches, missing license files, and self-hosted hosts.

Install options

What gets installed (FHS layout)

The installer bootstraps uv/Python/Ansible and runs daemon-install.yml, which lays out a clean Filesystem Hierarchy Standard tree — there is no source checkout on a managed server:

• User tp:tp (UID/GID 9999) with passwordless sudo
• turbopaneld.service (systemd, single process via flock). The unit runs the native binary when turbopaneld --version succeeds. On hosts where that probe fails — notably some Raspberry Pi arm64 kernels with a 16 KiB page size, which cannot load the usual 4 KiB-page deno compile binary — install downloads turbopaneld.js, installs vendored Deno, and uses deno run …/bin/turbopaneld.js as the supported ExecStart for that hardware. Deno is installed only on that path; native hosts skip it.

Configuration

Runtime config: /etc/turbopanel/daemon.env (EnvironmentFile= on turbopaneld.service).

Co-located socket mode omits TURBOPANEL_INSTANCE_URL and dials unix:///run/turbopanel/instance.sock.

Communication

• WebSocket: wss://<instance>/ws/daemon/v1
• Hello: daemon sends hostname, optional serverId, machineId; instance returns canonical serverId
• Commands: instance routes over daemon-hub; dev-sync and tunnel-token messages for operator pushes

Common issues

See Deployment troubleshooting for more.

Related documentation

• Control plane — Instance and Caddy layout
• Security — TLS and socket hardening
• Daemon README — Maintainer reference