Architecture

How FeatherPanel is built - FrankenPHP backend, Next.js frontend, Rust async runner, MCP server, MariaDB, Redis, FeatherWings and FeatherQuilld nodes.

FeatherPanel is split into a panel that you install once and daemons that you install on every machine that runs workloads. The panel never runs game servers or websites itself: it stores state, checks permissions and tells the daemons what to do.

The big picture

                      Browser / API client / MCP client
                                   │ HTTPS
                     your reverse proxy (nginx, Apache, Caddy, Cloudflare Tunnel)
                                   │ http://127.0.0.1:4831
┌──────────────────────────── panel host (Docker) ─────────────────────────────┐
│ frontendv2  (Caddy + Next.js)  ── /api, /pma, /webmail, /addons ──► backend   │
│        │   └─ /mcp, OAuth ──► mcp (Node.js)                         │         │
│        └─ /vnc-proxy ──► async-runner (Rust) ◄── Redis pub/sub ─────┤         │
│                                                    MariaDB ◄────────┤ Redis   │
└──────────────────────────────────────────────────────────────────────┼────────┘
           ┌───────────────────────────────┬─────────────────────────┘
           ▼ HTTPS + node token            ▼ HTTPS + node token          ▼ Proxmox API
   FeatherWings (game nodes)      FeatherQuilld (web nodes)       Proxmox VE (VDS nodes)
   Docker, SFTP :2022, API :8080  WebSpaces, proxy, DNS, mail,     VMs and LXC containers
                                  SFTP :2222, FTP :21, API :8989

Panel services

The Docker install (docker-compose.yml) runs these containers:

How requests are routed

The Caddy server inside frontendv2 decides where each request goes:

Requests may be up to 250 MB. Event streams (/api/mercure and the chatbot streams) are not compressed so they reach the browser immediately.

Inside the backend

The backend runs PHP on FrankenPHP. By default it uses worker mode: the app boots once and stays in memory, which removes the per-request bootstrap cost. There are two worker pools:

• featherpanel-api serves /api/*. It starts 2 x CPU threads and can grow to 3 x CPU (at most 32) under load.
• featherpanel-slow serves long responses (chatbot streams, file and backup downloads) so a few of them cannot block the rest of the API.

Set FRANKENPHP_WORKER=false to fall back to classic mode. See Cron, workers and runner for every knob.

The backend also hosts the Mercure hub that pushes live updates to the browser, and runs the cron jobs every minute.

The async runner

The runner listens on three Redis channels:

• featherpanel:mail:pending sends queued e-mail over SMTP, so a slow mail server never slows down a request.
• featherpanel:vm:pending creates VDS instances on Proxmox and reports progress.
• featherpanel:settings:reload reloads settings after an admin changes them.

It also serves the browser VNC console for VDS instances at /vnc-proxy.

Daemons

FeatherWings (game servers)

FeatherWings is a Go daemon, forked from Pterodactyl Wings. Each game node runs one. It creates a Docker container per server, streams the console over a websocket, serves SFTP on port 2022 and takes backups. The panel talks to it over HTTPS on port 8080 with the node token; Wings calls back to the panel with token_id.token.

A node’s daemon type can also be wings_rs (Calagopus Wings). Those nodes default to /etc/calagopus-wings/config.yml, /var/lib/calagopus-wings/volumes and the wings systemd unit. The panel keeps a feature matrix per daemon type (DaemonCapabilities) and hides what a node cannot do:

Both support the core server API, Docker, file search, archive browsing, deauthorize, self update, file history and file collaboration.

FeatherQuilld (web hosting)

FeatherQuilld is a .NET daemon for web nodes. It runs customer WebSpaces in Docker, manages a reverse proxy (Caddy, nginx or Traefik), DNS through PowerDNS, mail through docker-mailserver or mailcow, and SFTP/FTP. Its API listens on port 8989.

Proxmox VE (VDS)

VDS hosting needs no FeatherPanel daemon. The panel stores a Proxmox API token per VDS node and drives Proxmox directly; the async runner does the long-running VM creation. The installer has a Proxmox VNC Agent option that you run on the Proxmox node; it adds noVNC files for PVE token forwarding so the in-panel console works.

Data and state

Optional parts

• phpMyAdmin (/pma) and webmail (/webmail) are served by the backend. phpMyAdmin is installed with featherpanel module install pma.
• Telemetry: the UmamiTelemetryReporter cron job sends one event per day with aggregate counts (users, servers, backups, nodes, schedules, webspaces, VMs and similar). The hostname is sent as the fixed string featherpanel. Turn it off with the telemetry setting, or force it off for the whole install with UMAMI_ENABLED=false.
• Plugins add PHP routes, event listeners, cron jobs and frontend pages. See Plugins.