Daemon Setup

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

Overview

Purpose

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

Relationship to control plane

The daemon 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 control plane URL you provide at install time.

Architecture

Deployment models

Both control-plane models are in private alpha and not yet publicly available. The installer and daemon behavior below apply when you have access.

Every self-hosted hostname is https://<host>:8443. The certificate follows the name. Port 80 accepts HTTP-01 only while a Let's Encrypt certificate is being issued or renewed. Port 443 is hosting.

Full table: Control plane. The issuance window, including port 80 is held by <process>, is in Hostnames and TLS.

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 (production installer)

Self-hosted examples below use https://<host>:8443. A Let's Encrypt hostname, and an uploaded certificate that chains to a public root, omit --insecure-tls.

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

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

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

turbopanel.sh is a redirect to scripts/run.sh on the live branch of the daemon repository. Keep the L in curl -fsSL: without it curl prints the redirect page and sh runs that instead of the installer.

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.

Contributor dev overlay only

The control plane host /run.sh path is development-only — served by the dev overlay Caddyfile at https://<dev-host>:8443/run.sh. LAN names use curl -k and TURBOPANEL_INSECURE_TLS=1 because the leaf is the Platform CA:

curl -fsSLk https://<dev-host>:8443/run.sh | \
  TURBOPANEL_LICENSE=<base64url-encoded-license> \
  TURBOPANEL_HOST=https://<dev-host>:8443 \
  TURBOPANEL_INSECURE_TLS=1 \
  sh

Refresh an existing server

If the server is already installed, re-run the same turbopanel.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('='))
")

HOST=$(sed -n 's/^TURBOPANEL_INSTANCE_URL=//p' /etc/turbopanel/daemon.env)
CHANNEL=$(sed -n 's/^TURBOPANEL_UPDATE_CHANNEL=//p' /etc/turbopanel/daemon.env)

curl -fsSL turbopanel.sh | \
  TURBOPANEL_LICENSE="$LICENSE_B64" \
  TURBOPANEL_HOST="$HOST" \
  TURBOPANEL_UPDATE_CHANNEL="$CHANNEL" \
  sh

Pass the server's own control plane and channel back, as above. The installer does not read them from daemon.env on a remote server: without TURBOPANEL_HOST it uses the TurboPanel High Availability control plane named in the release manifest, and without TURBOPANEL_UPDATE_CHANNEL it uses release.

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). Its sudo rule is limited to three root commands, without a password: the host helper (/opt/turbopanel/lib/tp-host), the orchestration runner, and the web-engine config checks. tp is also in the docker group, and Docker access is root-equivalent, so treat the tp account as equivalent to root on that host.
• 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 — install downloads turbopaneld.js, installs vendored Deno, and uses deno run …/bin/turbopaneld.js as the supported ExecStart for that hardware.

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. On a self-hosted control plane that is the daemon the control plane installer provisions: it starts before the wizard has issued a license, re-checks the daemon state directory every few seconds, and enrols as soon as the wizard writes the first organization's license there. Contributor dev keeps the console opt-in (TURBOPANEL_DEV_INSTANCE); a managed install connects without it.

Communication

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

Common issues

See Deployment troubleshooting for more.

Purging this host

Purge TurboPanel from this host with the purge script. It removes everything TurboPanel put on the host; there is no remove-TurboPanel-only option.

curl -fsSL https://raw.githubusercontent.com/TurboPanel/turbopaneld/trunk/scripts/purge.sh | sudo sh

Unlike the installer, this script must be run with sudo (or from a root shell) and needs a terminal. Over SSH, use ssh -t.

Related documentation

• Deployment hub — Operator overview
• Control plane — Control plane and Caddy layout
• Security — TLS and socket hardening
• Purge — Purge TurboPanel from a host
• Daemon README — Maintainer reference