Pterodactyl is an open-source control panel for game servers, and it is two programs rather than one. The panel is a web application that knows who you are, which servers you own and what you are allowed to do to them. Wings is a small daemon that runs on each physical machine, talks to Docker, and is the only part that ever touches your files. Your server is a Docker container that Wings starts, with a memory limit, a CPU share, a disk quota and one or two ports mapped to it. Almost every browser-based game host you have used is this, with a different logo on it.
Knowing that is not trivia. It explains why you have a console but not a shell, why memory limits behave the way they do, why the file manager is instant but installing a new piece of software is impossible, and why "restart the panel" never fixes a crashed game server. This post is the machinery, top to bottom, plus the honest list of what the arrangement cannot do.
Two programs, two jobs#
The panel is a Laravel application with a React front end. It holds accounts, servers, permissions, allocations, schedules and audit records in its own database. It renders every page you look at. What it does not have is your world file, your logs or your process - the panel has no idea what is inside your server, only what Wings tells it.
Wings is a small Go daemon installed on every node. It talks to the Docker socket, creates and destroys containers, enforces limits, streams console output, serves SFTP, and produces backups. It listens on port 8080 by default and serves SFTP on 2022, and its configuration is a single file at /etc/pterodactyl/config.yml containing the token it uses to authenticate back to the panel.
The dashed line from your browser to Wings is worth noticing. When you open the console, the panel hands your browser a short-lived token and the browser then opens a websocket straight to Wings. Console output is not proxied through the panel. This is why the console can feel instant while a page load feels ordinary, and why a console that stops updating usually means the node, not the website.
It also explains a class of confusion. If the panel is unreachable, your servers keep running - Wings does not need the panel to keep a container alive. If Wings is unreachable, the panel still loads and every server shows as offline whether it is or not.
One server is one Docker container#
Each server gets a container built from an image chosen by its egg, and a directory on the node bind-mounted into it. On the node that directory is /var/lib/pterodactyl/volumes/<uuid>; inside the container it is /home/container, and that is the working directory the game starts in. Everything you see in the file manager is that one directory.
What this buys you and what it costs you are the same thing:
- Isolation. A server that fills its disk, saturates its CPU or gets killed for memory cannot touch a neighbour. Separate filesystem, separate process namespace, separate limits.
- No root, and no persistent system. You are a non-root user in a container that is thrown away and rebuilt from the image every time the server starts. Anything you install with a package manager would be gone at the next start even if you could run one. Files under
/home/containersurvive; nothing else does. - The image decides what exists. If the image has Java 21 and your modpack needs Java 8, you change the image by changing the egg or the variable that selects it, not by installing Java.
Images come from public registries - the project publishes a set under ghcr.io/pterodactyl/yolks, tagged by runtime, so a Minecraft egg might run on yolks:java_21 and a Node.js app on yolks:nodejs_22. A host picks the image; on a customer account you generally choose a version from a dropdown on the Startup tab rather than typing an image name.
Eggs: how a panel knows how to install a game#
An egg is a JSON file that describes everything needed to run one kind of server. Upstream they are grouped into nests, which is just a folder with a theme. A single egg carries:
| Part | What it holds |
|---|---|
| Docker images | The runtime the game needs, one or several to choose from |
| Install script | A bash script run once, in a throwaway container |
| Startup command | The line that launches the game, with variables in it |
| Variables | The fields you see on the Startup tab, with defaults and rules |
| Config parser | Which files to rewrite at boot, and which keys |
| Startup detection | The log line that means "this is now up" |
| Stop command | How to shut down cleanly, for example stop or ^C |
Installation is a separate step from running. When a server is created, Wings starts a temporary container, mounts the empty server directory at /mnt/server, runs the install script - usually SteamCMD or a download and unzip - then throws that container away. Only then does the real container start. This is why a new server sits on an installing screen and why its console is empty until the install finishes.
The startup command uses substitutions the panel fills in:
java -Xms128M -Xmx{{SERVER_MEMORY}}M -jar {{SERVER_JARFILE}} nogui{{SERVER_MEMORY}}, {{SERVER_IP}} and {{SERVER_PORT}} come from the plan and the allocation; anything else in double braces is a variable the egg declares, which is exactly what the Startup tab is showing you. Change the jar file name in that field and the launch line changes.
The config parser is the part people never see and often trip over. An egg can be told to rewrite server.properties at every boot so that server-port matches the allocation. If you edit a key the egg owns, your edit is overwritten on the next start and it looks like the file reverted by itself. The fix is to change it where the panel expects - the Startup tab or the Network tab - rather than in the file.
The tabs, and what each is really doing#
- Console. A websocket to Wings carrying the process's standard output, plus a command line writing to its standard input. It is the game's own console, unfiltered, which is why the useful error is always in it. Reading the console is about what to look for.
- Files. An HTTP file API on Wings scoped to the volume. Uploads, an editor, archives unpacked in place. Large operations are better over SFTP: SFTP and the file manager.
- Databases. The panel creates a database and a user on a database host it manages, generates a password, and shows you the connection details. It never runs inside your container.
- Schedules. A cron expression stored in the panel, with ordered tasks - a console command, a backup, a power action - each with a delay. The panel's own scheduler fires them and calls Wings. Cron expressions explained covers the five fields.
- Backups. Wings tars the volume and stores the archive. Restoring replaces the volume contents. A backup is of files, not of memory, so a game that has not saved recently produces a backup of an old world - always send a save command first.
- Network. The IP and port pairs allocated to this server. The primary one is what the game binds to; extra ones are for query ports, RCON, a web map, or a second service. Game server ports explained covers which you need.
- Startup. The egg's variables, rendered as a form.
- Users. Subusers with per-permission grants, which is how you give a moderator the console without the billing or the delete button.
RE:NODE's panel is our own code built on top of Pterodactyl and Wings rather than a stock install, so some of this behaves differently on purpose. Console output is unfiltered with history and tab completion, and there are live graphs for memory, CPU and disk drawn against the limits rather than against the node. SFTP credentials are per server instead of per account, which matters the moment you hand access to one server to somebody who should not have the others. Database slots have an "open in phpMyAdmin" button that signs in with a one-use token expiring in sixty seconds. Access control is roles, teams and grants rather than a flat subuser list, with time-boxed access and a per-server activity log - subusers and least privilege and the people and permissions guide have the practical version.
Limits, and what happens when you hit them#
Three limits are set per server and enforced by the kernel through Docker, not by the game.
| Limit | How it is expressed | At the edge |
|---|---|---|
| Memory | Megabytes, a hard cgroup limit | The container is killed |
| CPU | Percent of one core - 250 is 2.5 cores | Throttled, never killed |
| Disk | Megabytes of quota on the volume | Writes fail; the server usually crashes |
The memory one is the one that generates support tickets. A container at its limit is stopped by the kernel, not slowed down, and the game gets no chance to save. Stock Pterodactyl leaves the OOM killer disabled by default, which lets a container swap and crawl instead; RE:NODE does the opposite deliberately, so a server at its limit is stopped and restarted clean rather than left thrashing. Both choices are defensible and they fail differently: ours costs you whatever was unsaved, theirs costs everybody an hour of a server that technically responds. Either way, the fix is the same - lower the save interval, or buy the memory the game actually wants. Node memory limits explained has the Java side of this, which is where most of the surprises live.
CPU is a throttle rather than a cap on how much work gets done: at 100% of your share the game simply runs slower. A server pinned at its CPU limit is slow, not broken, and is never grounds for suspension here. Disk quota failures look like data corruption and are not - the world file is fine, the write just did not happen.
On top of the container limits there is a crash watcher: it polls every couple of minutes for a server whose uptime went backwards or that went offline on its own. Restarts you asked for are not counted. Three unexpected restarts in an hour puts a warning on the server page and opens a ticket; six suspends it, because a server crash-looping at startup is burning a node's CPU for nobody's benefit. Why your game server keeps restarting is the diagnosis guide.
What a panel deliberately cannot do#
This is the honest list, and it is the reason some people should not use a panel at all.
- No root and no shell. The console is the game's stdin, not bash. You cannot run
apt,htop,tcpdump, or a script that needs to be a daemon. - One server, one game. The container runs the egg's startup command. Running a second process beside it is not what the design supports; a second game is a second server.
- No system services. No systemd, no cron inside the container, no custom firewall rules. The panel's Schedules tab replaces the first two; the third is the host's.
- No arbitrary software. If your mod needs a native library that is not in the image, the answer is a different image, which on most hosts means a different egg, which means asking.
- The ports are the ports. You get the allocations your plan states, and you can add or remove them on the Network tab within what the plan allows. You do not get to bind anything, anywhere.
If more than one of those is a blocker, you want a machine rather than a container - choosing between a VDS and a game panel is the direct comparison, and what a dedicated game server is sets out the three ways of running one.
Running your own Pterodactyl, or renting from someone who runs one#
Pterodactyl is free and you can install it. The install itself is an afternoon: a web server, PHP, a database, a queue worker, Wings, Docker, a certificate. The official documentation is good and current.
What you are signing up for afterwards is the part nobody counts. You own OS patching, Docker upgrades, panel upgrades and their migrations, certificate renewal, backup storage that is not on the same disk, the firewall, and the node being reachable at three in the morning. You also own the abuse problem the moment anyone but you has an account. For one person running three servers on one box it is a genuinely reasonable weekend project, and multiple game servers on one VDS covers the smaller alternatives to it. For a community that expects the server to be up when you are on holiday, it is a second hobby.
The reason to care about any of this as a customer is that it tells you what to ask a host. Whether backups leave the machine they protect. What happens at the memory limit. Whether SFTP credentials are per server or per account. Whether you can add a port yourself. Those are all panel-level answers, and a host that cannot give them quickly is a host that has not thought about them.
Problems that look like the panel and are not#
The console shows nothing and the server is "offline". Wings is not answering. Nothing you do in the panel will help, and the game may still be running. This is a status page and a ticket, not a retry.
The server starts and immediately stops, with no error. Read the last twenty lines before the stop. Almost always a missing file the startup command names, a port already in use, or a config the game refuses to parse.
My config change vanished after a restart. The egg's config parser owns that key. Set it on the Startup or Network tab instead.
The file manager will not upload a 4 GB modpack. Browser uploads are the wrong tool at that size. Use SFTP, or upload a zip and unpack it in place.
Everything is slow but the graphs look fine. Check which graph. Total CPU across cores can sit at 30% while the game's single hot thread is pinned, and the memory graph can look healthy right up to the moment a spike crosses the limit.
FAQ#
Is Pterodactyl free, and is a host using it cutting corners?
It is free and open source, and using it is not a shortcut. It solves the boring, dangerous parts - isolation, allocations, permissions, backups - in a way that has been reviewed by a lot of people. What differs between hosts is the hardware underneath it, what they have built on top, and whether anyone answers a ticket.
Can I get SSH access to my game server?
No. A panel server is a container with a game in it, and SSH is not part of it. You get SFTP for files and the console for the game. If you need a shell, you need a VDS.
Why can I not install a plugin the panel does not know about?
You can - plugins, mods and configs are just files you upload through the file manager or SFTP, and there is no allow-list of approved mods. What you cannot install is system software, because the container is rebuilt from its image at every start.
What is an egg, in one sentence?
A recipe file that tells the panel which Docker image to use, how to install the game, how to start it, and which settings to show you on the Startup tab.
Does upgrading my plan rebuild the server?
No. The container's memory, CPU and disk limits are changed on the server you already have. The volume, and therefore your world, stays where it is.
Does the panel keep working if my server crashes, and the other way round?
Yes to both. They are separate programs. A crashed game server leaves the panel perfectly usable, which is how you read the log that says why; a panel outage leaves running servers running, because Wings does not ask permission to keep a container alive.
Comments
Completely anonymous: no account, no email, no cookie. We store the name you type, the text and the time - nothing else. Links are limited and markup is not rendered.