How FeatherPanel
is put together.
A PHP 8.5 API (the most-used language in the panel) and a Next.js 16 UI orchestrate Docker games through FeatherWings, Proxmox VDS through a Rust async-runner, and migrations throughFeatherCli (C# / .NET 10).
Core terminology
Terms if you know Pterodactyl,
plus FeatherPanel names.
Realms and Spells map to Nests and Eggs. Wings becomes FeatherWings. Proxmox VDS is a second data plane.
Core components
Panel
The control plane: a Next.js UI and a PHP API. Admins and clients manage users, nodes, game servers, and Proxmox VDS from here.
Node
A machine that runs FeatherWings (or Calagopus). The Panel talks to Nodes over mTLS to create and control Docker game servers.
FeatherWings
The recommended 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.
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
Requests go from the Next.js UI into the PHP API, then out to FeatherWings for Docker games or through Redis to the Rust async-runner to Proxmox for VDS. Mail uses the same runner channel.
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
Client --> Web
Client --> FE
Cli -->|"migrate · server · account"| API
Cli -->|"SQL dump / APP_KEY"| DB
API <-->|"REST · WebSockets · mTLS"| Wings
Runner -->|"API token"| PVE
1. UI hits the API
Next.js calls /api/*. PHP middleware handles auth, admin, server, and Wings remote routes.
2. State in MariaDB + Redis
Servers, spells, allocations, and VmInstances live in MariaDB. Redis caches, rate-limits, and publishes job events.
3. Side effects leave the request
Game power and files go to Wings immediately. Mail and Proxmox clone/power run on async-runner.
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: when to use which
Use Docker + Spells for game servers: fast deploys, egg ecosystem, tight limits. Use Proxmox VDS when customers need a full OS, custom stacks, or classic VPS semantics. FeatherPanel exposes both under one UI. The runtimes stay separate so a Minecraft container does not share fate with a tenant VM.
The tradeoff
Why FeatherPanel
uses more memory.
Next.js, Redis queues, Rust workers, IDE, and dual data planes cost RAM. In return you get throughput and features Pterodactyl does not ship.
Higher RAM usage
Independent Calagopus 8c runs put FeatherPanel around 261 MiB peak vs ~148 MiB on Pterodactyl. That headroom keeps the Next.js UI, queues, mail, IDE, and Proxmox hooks warm.
Higher throughput and lower latency
Same suite: higher peak throughput (1,431 vs 1,170 req/s) and lower average latency (270 ms vs 333 ms) than Pterodactyl. The heavier stack is tuned for where operators feel load.
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; two separate data planes underneath.
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 is the most-used language (~148k lines). TypeScript/TSX is close behind (~140k).
Panel API, auth, Wings client, Proxmox orchestration, plugins, cron
Next.js 16 UI, FeatherIDE, consoles, admin and client dashboards
Node agent: Docker lifecycle, SFTP, console, backups (separate repo)
Migrations from Pterodactyl, operator CLI tasks, client API automation (separate repo)
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
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.
PHP 8.5, Next.js 16, FeatherCli (C#), FeatherWings (Go), Rust async-runner, MariaDB, Redis, Docker, Proxmox.
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.
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?
Independent Calagopus benchmarks compare FeatherPanel to Pterodactyl, Pelican, and Hydrodactyl on identical hardware.