How FeatherPanel
is put together.
FeatherPanel is a control plane, not a single monolith that talks to Docker only. A PHP 8.5 API (largest share of the panel codebase) and aNext.js 16 UI keep state in MariaDB and Redis, then fan out: game power and files to FeatherWings, VDS work to a Rust async-runner over Proxmox, sites toFeatherQuilld, and operator migrations to FeatherCli.
Core terminology
Terms if you know Pterodactyl,
plus FeatherPanel names.
If you know Pterodactyl: Realms ≈ Nests, Spells ≈ Eggs, FeatherWings ≈ Wings. FeatherPanel also adds web and Proxmox planes that Wings never owned.
Core components
Panel
The control plane: a Next.js UI and a PHP API. Admins and clients manage users, game nodes, WebSpaces, and Proxmox VDS from here.
Node
A machine that runs FeatherWings (or Calagopus) for games, or FeatherQuilld for web hosting. The Panel talks to nodes over authenticated APIs.
FeatherWings
The recommended game-node daemon. It owns Docker lifecycle, SFTP, console, backups, and extras like firewall, FastDL, and self-update. Calagopus wings-rs is also supported.
Server
A game instance on a Node (Minecraft, Rust, CS2, and others) running in an isolated Docker container defined by a Spell.
Web hosting
FeatherQuilld
Web-node daemon (C# / .NET 10). Details and request flow are in the FeatherQuilld section below.
WebSpace
One tenant site on a Quill node: filesystem, domains, and runtime identity the Panel tracks by UUID.
Reverse proxy
Caddy, nginx, or Traefik. Quill writes the vhosts; the proxy terminates TLS for visitors.
Infrastructure
Docker
Runtime for container-based game hosting. Each server is a container with hard CPU, memory, disk, and port limits.
Proxmox VE
Hypervisor for VDS: full QEMU/KVM VMs or LXC. Managed through FeatherPanel VmNodes, separate from game Docker nodes.
Async runner
A Rust worker (Tokio) that drains Redis queues for mail and Proxmox tasks so long jobs do not block the PHP request path.
Spell system
Realm
FeatherPanel's Nest: a category that groups related Spells (for example all Minecraft server types).
Spell
FeatherPanel's Egg: install script, Docker images, startup command, config files, and variables. Pterodactyl eggs can be imported.
Yolks / images
Docker base images Spells run on (often community yolks). The Spell picks the image; Wings starts the container from it.
Visualizations
Hierarchy overview
One Panel manages many Nodes. Each Node hosts many Servers. That relationship is the base of container game hosting.
graph TD
Panel[Panel]:::panel
subgraph Nodes [Nodes and Servers]
direction TB
Node1[Node 1]:::node
Node2[Node 2]:::node
NodeN[Node n]:::node
Server1[Server 1]:::server
Server2[Server 2]:::server
Server3[Server 3]:::server
ServerN[Server n]:::server
end
Panel --> Node1
Panel --> Node2
Panel --> NodeN
Node1 --> Server1
Node1 --> Server2
Node2 --> Server3
NodeN --> ServerN
classDef panel fill:#3b82f6,stroke:#2563eb,color:#fff,stroke-width:2px;
classDef node fill:#10b981,stroke:#059669,color:#fff,stroke-width:2px;
classDef server fill:#f59e0b,stroke:#d97706,color:#fff,stroke-width:2px;
System architecture
Every product surface shares one login and one API. Side effects leave that request on purpose: Docker games hit Wings, VDS tasks enqueue on Redis for the Rust runner, and web sites talk to Quill on their own HTTP path. Mail shares the runner channel so PHP does not sit on SMTP.
flowchart TB
Client["Browser · API Client\nNext.js UI"]
Cli["FeatherCli\nC# · .NET 10"]
subgraph CONTROL["Control plane - FeatherPanel"]
direction LR
Web["Nginx / Apache\nTLS :443"]
API["PHP 8.5 API\nSymfony Routing\nXChaCha20 secrets"]
FE["Next.js 16 UI\nReact 19 · Tailwind"]
DB["MariaDB"]
Redis["Redis\nCache · Pub/Sub · Queues"]
Runner["Rust async-runner\nMail · Proxmox tasks"]
Web --> API
FE --> API
API --> DB
API <--> Redis
Runner <--> Redis
Runner --> DB
end
subgraph GAME["Data plane A - Containers"]
Wings["FeatherWings\nor Calagopus wings-rs"]
Docker["Docker"]
GameCtr["Game containers\nSpells · Limits · Allocations"]
Wings --> Docker --> GameCtr
end
subgraph VDS["Data plane B - Virtualization"]
PVE["Proxmox VE API"]
Qemu["QEMU / KVM VMs"]
Lxc["LXC containers"]
PVE --> Qemu
PVE --> Lxc
end
subgraph WEB["Data plane C - Web hosting"]
Quill["FeatherQuilld\nC# · .NET 10"]
Proxy["Reverse proxy\nCaddy / nginx / Traefik"]
Spaces["WebSpaces\nSites · SSL · SFTP/FTP"]
Quill --> Proxy --> Spaces
end
Client --> Web
Client --> FE
Cli -->|"migrate · server · account"| API
Cli -->|"SQL dump / APP_KEY"| DB
API <-->|"REST · WebSockets · mTLS"| Wings
API <-->|"REST · WebSockets"| Quill
Runner -->|"API token"| PVE
1. UI hits the API
Next.js calls /api/*. PHP middleware owns auth, admin, server, and remote daemon routes for each data plane.
2. State in MariaDB + Redis
Servers, spells, allocations, WebSpaces, and VmInstances live in MariaDB. Redis caches, rate-limits, and publishes job events.
3. Side effects leave the request
Games go to Wings. Sites go to Quill. Mail and Proxmox clone/power drain on async-runner so the API stays thin under load.
Note
Panel and Wings on the same machine
You can run FeatherWings on the Panel host. That machine is both control plane and a game node. This is common for demos, homelabs, and small fleets. Proxmox usually stays on dedicated hypervisor hardware.
Container-based hosting
Docker game servers
through FeatherWings.
The classic Wings model, reimplemented and extended: isolation, port allocations, and Spell blueprints.
Container hosting is for game processes that should be lightweight, dense, and disposable. FeatherPanel does not SSH into the box to start Minecraft. It asks FeatherWings, and Wings asks Docker.
Pick a Spell
A Spell (egg-compatible) defines the Docker image, install script, startup command, stop signal, and variables.
Claim resources
The Panel assigns a Node allocation (IP:port) and stores CPU, memory, disk, swap, IO weight, and thread limits on the server.
Wings builds the container
FeatherWings pulls the image, mounts the server filesystem, applies limits, and wires ports. Install scripts run once inside the container.
Operate live
Power, console (WebSocket), files, backups, schedules, and transfers go Panel to Wings to Docker. Proxmox is not involved on this path.
flowchart LR
Admin["Admin / User"]
Panel["FeatherPanel\nServer + Spell + Allocations"]
Wings["FeatherWings on Node"]
Spell["Spell blueprint\nimage · startup · install"]
Docker["Docker Engine"]
Ctr["Isolated container\nCPU · RAM · disk · ports"]
Admin --> Panel
Panel -->|"create / power / files"| Wings
Panel --> Spell
Spell --> Wings
Wings --> Docker
Docker --> Ctr
Hard limits
Memory, swap, CPU %, threads, disk, IO weight, and OOM policy are stored on the server and sent to Wings as the container build.
Allocations
IP:port mappings bind the container to the network. Default allocation plus extras for query ports, RCON, and similar services.
Egg compatible
Import Pterodactyl eggs into Spells. Realms group them. Images (yolks) stay Docker; Wings pulls what the Spell declares.
Virtual machine hosting
Proxmox VDS
QEMU and LXC.
Real hypervisor guests managed through queued API tasks, next to your game fleet.
flowchart LR
User["Admin / VDS user"]
Panel["FeatherPanel\nVmNode · VmInstance · VmTask"]
Redis["Redis\nfeatherpanel:vm:pending"]
Runner["Rust async-runner"]
PVE["Proxmox VE\n/api2/json"]
Guest["QEMU VM or LXC\nfrom template"]
User --> Panel
Panel -->|"enqueue task"| Redis
Redis --> Runner
Runner -->|"clone · resize · net · power"| PVE
PVE --> Guest
VDS lives on VmNodes, not Wings nodes. When you create an instance, PHP records the intent and enqueues aVmTask. The Rustasync-runner performs the Proxmox calls: clone template, resize disk, attach bridge/cloud-init, power on. Then the panel reflects status.
Register a VmNode
Connect Proxmox with an API token. FeatherPanel stores the node separately from game Wings nodes.
Enqueue a VmTask
Creating a VDS writes a VmInstance and a VmTask (create/reinstall/backup/...). Redis notifies featherpanel:vm:pending.
Rust runner calls Proxmox
async-runner clones a QEMU or LXC template, resizes disk, applies network/cloud-init, then powers the guest.
Day-2 ops
Start/stop/reboot, console users, backups, restore, and delete stay on the VDS path and stay independent of Docker game servers.
QEMU / KVM
Full virtual machines
Hardware-virtualized guests with their own kernel. Best when tenants need custom kernels, nested virt, or strong isolation for general-purpose VPS product lines.
LXC
System containers on Proxmox
Shared-kernel Linux containers managed by Proxmox. Denser than QEMU, still a VDS product, and a different path from FeatherWings game Docker containers.
Containers vs Proxmox vs web
Docker + Spells for game servers: egg ecosystem, hard limits, fast churn.Proxmox VDS when tenants need a full OS or classic VPS semantics.WebSpaces when the product is a site or app (proxy + TLS + files), not a game container. One UI; three data planes.
Web hosting daemon
FeatherQuilld
how the web plane works.
C# / .NET 10 on the node. Panel owns desired state; Quill owns filesystem, proxy, and tenant file access.
Game panels stop at Docker. FeatherPanel needed a second node daemon for sites that are not Minecraft containers: document roots, hostnames, certificates, and SFTP without giving every client a shell on the host.FeatherQuilld is that daemon. It sits beside Wings on the fleet map, not inside it.
The Panel stores WebSpace UUIDs and config in MariaDB the same way it stores game servers. Runtime work (create root, install, wire Caddy/nginx/Traefik, serve files over SFTP/FTP) happens on Quill over an authenticated HTTP API. Visitors never hit the Panel; they hit the reverse proxy Quill configured.
Request path
Admin traffic and visitor traffic stay split. The Panel only talks to Quill; browsers only talk to the proxy.
flowchart LR
Admin["Admin / client"]
Panel["FeatherPanel\nPHP API"]
Quill["FeatherQuilld\non web node"]
Proxy["Caddy / nginx / Traefik"]
Space["WebSpace\nfiles · process"]
Visitor["Site visitor"]
Admin -->|"create · files · status"| Panel
Panel -->|"HTTP API"| Quill
Quill --> Space
Quill -->|"vhost · TLS"| Proxy
Visitor -->|"HTTPS"| Proxy
Proxy --> Space
Provision lifecycle
Create, optional install, publish the hostname, then day-2 file ops, all reported back as status the UI can poll.
sequenceDiagram
participant P as FeatherPanel
participant Q as FeatherQuilld
participant FS as WebSpace FS
participant PX as Reverse proxy
P->>Q: PUT WebSpace uuid + config
Q->>FS: create root · permissions
alt install required
Q->>FS: run install job
Q-->>P: status installing
end
Q->>PX: route domain · ACME cert
Q-->>P: status running
P->>Q: SFTP/FTP or file API
Q->>FS: read / write tenant files
Operator steps
Link a Quill node
Install the daemon, point it at the Panel, and authenticate. That machine is only the web data plane. It does not run Wings or Proxmox.
Allocate a WebSpace
Panel issues a UUID and desired state. Quill creates the filesystem layout and runs install when the blueprint says so.
Publish the hostname
Quill updates the reverse proxy and completes ACME so the domain answers on HTTPS without a separate cert bot.
Day-2 from the UI
File manager, schedules, transfers, and status polls hit Quill. Minecraft containers and VMs never share this path.
Isolation per WebSpace
Each site gets its own root on disk, utilization counters, and status machine (installing, running, reinstalling) instead of sharing one document root.
Proxy control plane
Quill is the source of truth for vhosts. It pushes routes and certificates into Caddy, nginx, or Traefik so operators are not editing configs by hand.
Tenant file planes
SFTP and FTP land inside the WebSpace root. Clients never need SSH on the host; the Panel still drives uploads and edits over the same HTTP API.
Not Wings
Different job than game Docker
Wings manages containers, allocations, and game console WebSockets. Quill manages site roots, vhosts, and tenant file protocols. Mixing those into one daemon would couple unrelated failure domains.
Same Panel
One UI for hosts who sell both
Clients still open one FeatherPanel. Admins register Quill nodes next to Wings nodes. Permissions and billing plugins can treat WebSpaces like any other product object without a second control plane.
Built with
ASP.NET Core · Certes (ACME) · FxSsh · FubarDev.FtpServer · Caddy / nginx / Traefik drivers
The tradeoff
Why FeatherPanel
uses more memory.
Next.js, Redis queues, Rust workers, the IDE, and three data planes all use RAM. They run features Pterodactyl does not have, such as the Web IDE, VM hosting and web hosting. The same weekly benchmark measured higher throughput and lower latency than Pterodactyl.
Higher RAM usage
In our latest weekly run (23 Oct 2026, 01:10 UTC, 4 CPUs) FeatherPanel peaked at 193 MiB and Pterodactyl at 118 MiB. FeatherPanel keeps the Next.js UI, queues, mail, IDE, and Proxmox hooks loaded in memory.
Higher throughput and lower latency
Same run: 2,177 vs 187 peak req/s (higher) and 15 ms vs 166 ms average latency (lower) against Pterodactyl.
Queued mail
A DB-backed mail queue drained by the Rust runner over SMTP, instead of sending mail inside the PHP request.
Async jobs beyond Wings
Installs, schedules, transfers, mail, and Proxmox tasks run async so API requests stay responsive under load.
Container game fleets
Docker isolation with Spell blueprints, allocations, and hard limits. This is the usual path for game hosts.
Proxmox VDS in the same panel
Full VMs and LXC sit beside game nodes. One login for games and virtualization; separate data planes underneath.
Plugins without forking
Events and addons extend billing, branding, and workflows. You keep upstream FeatherPanel instead of maintaining a private fork.
Operator tooling
FeatherCli
C# · .NET 10
The official CLI for migrations and day-to-day panel tasks. It is a native .NET binary.
FeatherCli is a self-containedC# / .NET 10 binary. It owns Pterodactyl to FeatherPanel migrations (live panel dir or SQL dump + APP_KEY), decrypts Laravel secrets when needed, and drives the same client API the UI uses for servers, files, backups, schedules, and accounts.
Pterodactyl migrations
Import users, nodes, nests/eggs to realms/spells, servers, allocations, databases, schedules, backups, SSH keys, and settings from a live install or SQL dump + APP_KEY.
Staging-safe dumps
Load a mariadb-dump into a staging DB, decrypt Laravel secrets when needed, then push into FeatherPanel over the API.
Day-to-day ops
feathercli server list|start|stop|files|backups|databases|schedules and account tools, using the same client API as the panel UI.
# migrate from a live Pterodactyl install
feathercli config setup
feathercli migrate --pterodactyl-dir /var/www/pterodactyl
# or from a SQL dump + env
feathercli migrate \
--sql-dump ./panel.sql \
--env-file ./panel.env \
--staging-db-host 127.0.0.1 …
# day-to-day ops
feathercli server list
feathercli server start --uuid <id>
feathercli server backups create --uuid <id>
Packages
System.CommandLine · Microsoft.Extensions.* · Spectre.Console · Newtonsoft.Json · MySqlConnector
Languages & packages
Languages in the
main repos.
In the main FeatherPanel repo, PHP leads (~148k lines) because the API, plugins, and daemon clients live there. TypeScript/TSX (~140k) is the UI + FeatherIDE. Go, Rust, and C# show up in the daemons and CLI repos around it.
Panel API, auth, Wings and FeatherQuilld clients, Proxmox orchestration, plugins, cron
Next.js 16 UI, FeatherIDE, consoles, admin and client dashboards
Node agent: Docker lifecycle, SFTP, console, backups (separate repo)
FeatherCli migrations and ops; FeatherQuilld web hosting daemon (WebSpaces, proxy, SFTP/FTP)
async-runner: mail queue drain and Proxmox VmTask execution
Schema migrations, compose, spell/egg definitions, deploy config
Packages by area
Backend (PHP)
- symfony/routing · http-foundation · yaml · mime
- predis/predis · ext-redis
- guzzlehttp/guzzle
- firebase/php-jwt · web-auth/webauthn-lib · pragmarx/google2fa
- phpmailer/phpmailer
- cloudflare/sdk · softcreatr/gameq · zircote/swagger-php
- vlucas/phpdotenv · ext-sodium (XChaCha20)
Frontend
- next · react · react-dom
- tailwindcss · @radix-ui/* · @headlessui/react
- @monaco-editor/react · @uiw/react-codemirror · @xterm/xterm
- @simplewebauthn/browser · recharts · three / R3F
- pnpm workspaces
Async runner
- tokio · redis · sqlx (MySQL)
- lettre (SMTP) · reqwest
- chacha20poly1305 · serde · tracing
FeatherCli
- System.CommandLine
- Microsoft.Extensions.* (DI, Config, Http, Logging)
- Spectre.Console · Newtonsoft.Json · MySqlConnector
FeatherQuilld
- ASP.NET Core · OpenAPI
- Docker.DotNet · Certes (ACME)
- Caddy / nginx / Traefik reverse proxy
- SFTP / FTP (FxSsh · FubarDev.FtpServer)
Node daemon
- Docker Engine API
- SFTP / WebSocket console stack
- mTLS panel remote API
Data & edge
- MariaDB / MySQL
- Redis
- Nginx or Apache
- Docker · Proxmox VE API
What we build with
Stack by layer
across the repos.
Each layer is a real process you can deploy and reason about: PHP API, Next.js UI, MariaDB/Redis, then the daemons and runners that leave the request path.
We did not collapse everything into one language. The panel API stays PHP for plugins and speed of iteration. The UI is Next.js because consoles, FeatherIDE, and admin surfaces need a modern React tree. Game nodes stay Go (FeatherWings). Web nodes stay C# (Quill). Long Proxmox and mail jobs stay Rust. Operators get FeatherCli in C# for migrations without SSHing into the panel box for every dump.
PHP 8.5 · custom core
MythicalSystems PHP control plane with Symfony Routing and HttpFoundation, JWT, WebAuthn, Guzzle, and Predis. Secrets at rest use XChaCha20-Poly1305. The API is custom PHP, not Laravel or a Pterodactyl fork.
Next.js 16 · React 19
frontendv2: Tailwind, Radix/Headless UI, xterm consoles, Monaco and CodeMirror (FeatherIDE), charts, and WebAuthn passkeys.
MariaDB + Redis
MariaDB holds panel state (servers, spells, VMs, mail queue). Redis handles cache, rate limits, pub/sub, and async-runner job channels.
FeatherWings (+ Calagopus)
Game data plane. The Panel Wings client issues power, files, backups, and install jobs. FeatherWings is preferred; Calagopus wings-rs stays compatible.
FeatherQuilld · C# / .NET 10
Separate web data plane on the node. Full request path, lifecycle, and proxy wiring are covered in the FeatherQuilld section.
Rust async-runner
Tokio, sqlx, lettre, and reqwest. Listens on Redis for mail and VmTasks, then talks to SMTP or the Proxmox API so PHP stays lean under load.
FeatherCli · C# / .NET 10
Official operator CLI: Pterodactyl to FeatherPanel migrations (SQL dump or live dir), plus server power, files, backups, schedules, and account tools over the client API.
Docker + Spells
Realms and Spells define images and startup. Allocations map IP:ports. Limits (CPU, RAM, disk, IO, OOM) ship to Wings as the container build.
Proxmox QEMU / LXC
VmNodes, VmInstances, and VmTemplates. Create clones, resize disks, attach nets/cloud-init, power cycle, and backup through queued VmTasks.
Plugins & events
Addon system with events for billing, branding, and custom workflows, without forking the core.
Auth & edge
Passkeys, TOTP, OIDC/LDAP options, CSRF, rate limits, AbuseIPDB/Cloudflare hooks, Zero Trust paths, and mTLS to daemons.
Want the raw numbers?
Our weekly benchmark compares FeatherPanel to Pterodactyl, Pelican and Hydrodactyl on one shared machine. Last run: 23 Oct 2026, 01:10 UTC.