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 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

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

Self-hosted TLS modes (turbopanel_tls_mode) and the ports they bind:

lets_encrypt needs :80/:443 free on the control-plane host. Full table: Control plane.

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 :8443 by default. Omit the port (or use :443) when turbopanel_tls_mode=lets_encrypt. Public TLS omits --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.

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 instance host /run.sh path is development-only — served by the dev overlay Caddyfile (plaintext :8880), not the production instance Caddyfile:

curl -fsSL http://<dev-host>:8880/run.sh | \
  TURBOPANEL_LICENSE=<base64url-encoded-license> \
  TURBOPANEL_HOST=http://<dev-host>:8880 \
  sh

Refresh an existing node

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('='))
")

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 — 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.

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

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