The PlayPort manual

PlayPort is two things installed as one, and this manual covers both:

• The panel - a self-hosted control panel for game servers and website hosting, shipped as a single Windows executable (PlayPort.exe, .NET Framework that ships inside Windows - no runtime to install). It creates and runs Minecraft/Steam/manual game servers, hosts static/PHP/reverse-proxy websites with HTTPS, runs a MySQL/MariaDB server for them, takes backups, runs schedules, and exposes a REST API.
• The core plugin - PlayPortCore, one Paper/Spigot plugin jar the panel installs into the game servers it runs. It carries the in-game half of the product: economy, permissions, ranks, homes, claims, mines, shops, quests, dungeons, and about a hundred other modules (see Appendix D), each switchable, each configurable from config.yml and from the panel.

Both are documented here for the person who operates them: the owner of the machine, the admin who installs it, and the staff who use the panel day to day. This is not the developer or release document - those are README.md (README.md) (the product tour and the build), RELEASE.md (RELEASE.md) (how a release is cut and proved), and HARNESS.md (HARNESS.md) (the verification harness).

Where to start. If you have never run it, read the quick start and then chapter 01. If you already run a panel and want one feature explained, use the chapter index below - every chapter is self-contained.

The shape of the product

        your browser                                              the internet
             |                                                          |
             v                                                          v
   +--------------------+                                    +---------------------+
   |  the panel :8080   |  <-- login session, the whole UI    | sites on their own  |
   |  (one exe, the     |                                    | ports, HTTP + TLS   |
   |   control plane)   |                                    | (Let's Encrypt)     |
   +--------------------+                                    +---------------------+
      |      |      |                                              ^
      |      |      +--> game servers it created (Minecraft, Steam, manual) on their own ports
      |      |              |  console, files, backups, schedules, worlds
      |      |              +--> with the core plugin installed: the in-game product
      |      |
      |      +--> MySQL/MariaDB :3306 - a database per site or per server
      |
      +--> :8100 model and agent API, :8101 brain API  (loopback unless you say otherwise,
                                                        API key required whatever the bind)

Everything lives in one data folder next to the exe by default (playport-data/), so the whole installation is copyable, backupable and deletable - see Appendix C.

Quick start (in ten minutes)

1. Put PlayPort.exe in a folder you can write to. A folder inside your user profile or on a data drive is fine; Program Files without elevation is not (the panel falls back to %LOCALAPPDATA%\PlayPort there and says so).
2. Run it. Double-click, or PlayPort.exe --open to open the browser for you. The console window is the panel's own log and must stay open - closing it stops the panel and the servers it runs.
3. Open <http://127.0.0.1:8080/> and create the first account (that account is the admin). The first-run screen only exists until the account does.
4. Make a game server: Game Servers -> + New server -> Minecraft Vanilla/Paper (pick a version, accept the EULA) or SteamCMD (pick a game, or type an App ID). Press Start.
5. Install the core plugin into it if you want the in-game half: the server's Plugins tab has the embedded core plugin and can install it in one click - see chapter 07.
6. Host a website: Websites -> + Host a website -> static, PHP, or a reverse proxy to an app you already run. Then its Settings page has the TLS panel for a Let's Encrypt certificate.
7. Open the port you want reachable from the internet, on your router and in Windows Firewall (add-firewall.ps1 does the Windows half once, with admin rights). Reachability is checkable in the panel rather than guessed - see chapter 11.

Chapters

Each chapter is one self-contained document in manual/ (manual/). They are written to be read in any order; where a topic spans two of them, both say so and link across.

Conventions used throughout.

• Bold marks a label you click or a field you fill in, spelled the way the panel spells it.
• Monospace is text you type or a path on disk.
• A chapter ends with a Files behind this chapter table naming the source files each section describes, so a reader can go from a feature to the code that implements it.
• Nothing in this manual is invented: every route, flag, config key, port and command in it was read from this tree. Where the code is ambiguous, the manual says so instead of guessing, and where the panel draws a control the code behind it does not implement, the chapter says that too rather than documenting the intent.
• Who owns what. A chapter owns its area: when a feature changes, the chapter whose Files behind this chapter table names that code is the one that changes with it. The module registry in Appendix D is generated from pkg/src/ppcore/ModuleIndex.java, so it cannot drift from the plugin. Chapter 12's reference pages are prose, but their coverage is held to the same registry: harness/gates/manual-gate.js fails the build while a module the plugin reports has no entry, while an entry names a module the registry does not have, or while a heading labels a module differently from the plugin. Everything else in this manual is prose and has to be kept by hand.

Appendix A - the command line

One executable is the panel, the installer, the uninstaller and the updater. PlayPort.exe --help prints the same list.

Running the panel

Installing, updating and removing

Appendix B - ports, addresses and the network path

PlayPort listens in more than one place, and they are different doors on purpose: publishing one must not publish the others.

Both program ports bind loopback only unless Reachable from the network is on, and they demand an API key whatever the bind. The panel port deliberately does not answer /v1: a client pointed at it is told which port to use and which key to present, rather than getting a 404 that reads like the feature was removed. The panel has a Ports screen (and /api/ports) that names all of them with what each one is for - that screen is the authority; this table is the summary.

Appendix C - where everything lives on disk

By default the exe keeps everything in a folder beside itself, so the installation is one folder:

The exact set of files grows with the features you switch on; the panel's own Settings page names the data root it is using, and PlayPort.exe --help documents --data. Switching between the portable folder and %LOCALAPPDATA%\PlayPort is remembered next to the exe (playport-data-mode.txt), and --data DIR overrides both.

Appendix D - the core plugin's modules

The plugin is one jar made of modules, each with its own config section, its own commands and its own switch. This is the registry as the plugin itself reports it - /playport status in game, and the Plugins screen in the panel, print the same list in this order. Chapter 08 explains the model; chapter 07 explains how to install and configure them from the panel; chapter 12 documents every one of them in turn - what it does, how to turn it on, and what you can configure.

Appendix E - the other documentation in this repository

Chapter 01. Install and first run

This chapter takes you from a downloaded PlayPort.exe to a running panel with an admin account, a first game server and a data folder you chose on purpose. It is the only chapter you need before the rest of the manual makes sense. Everything an established panel owner needs later - servers, websites, the core plugin, the API - is in the chapters that follow.

Read ../MANUAL.md first if you have not: it has the quick start, the ports table (Appendix B), where everything lives on disk (Appendix C) and the command-line reference (Appendix A).

What PlayPort is, in two halves

The panel is one Windows executable. It is the control plane: it creates and supervises game servers, hosts websites, runs a bundled MySQL/MariaDB server, takes backups, runs schedules and serves the web interface you drive it from. It is not a service and it installs no runtime - it targets the .NET Framework that is already inside Windows 10 and 11.

The core plugin (PlayPortCore) is a Minecraft plugin jar the panel installs into the game servers it runs. It is the in-game half of the product - economy, permissions, ranks, homes, claims, shops, quests, dungeons and about a hundred more switchable modules. Chapter 07 installs it; chapter 08 explains it. You do not need it to run a panel, and nothing in this chapter depends on it.

There is nothing else to install. Websites, PHP, HTTPS certificates, the database server, Java and the Steam client are all fetched by the panel itself, at the moment you first use them - chapter 05, chapter 06 and chapter 03 cover each of those downloads and where they land.

What the machine needs

The panel samples CPU, RAM, disk and (where nvidia-smi exists) the GPU for its dashboard. Nothing it does requires a GPU; a machine with no NVIDIA card simply reports that it cannot see one rather than reporting an idle one.

Where data goes: the two folders

An installation is two folders, and separating them is the point of the installer.

The program folder holds PlayPort.exe and, if the panel was installed rather than unzipped, a record of the install: playport-install.json. That file is what makes an exe an install. Delete it and the same binary is portable again.

The data folder holds everything else: settings.json, auth.json, the server folders under instances/, the website folders under sites/, SteamCMD, MariaDB's data, backups, the log. It is the folder that grows to gigabytes, and it is the one you should put on a drive with room.

Which folder the panel uses is decided in this order (Store.cs's DefaultRoot):

1. --data DIR - always wins. Use it for a one-off, or to point a copy at data you moved by hand.
2. The data folder recorded in playport-install.json, for an installed copy. This is the folder you chose during install, and it deliberately outranks the folder rules below.
3. --portable or --appdata - typed by you, so they win over the remembered choice. --portable means playport-data/ next to the exe; --appdata means %LOCALAPPDATA%\PlayPort.
4. The remembered choice: playport-data-mode.txt next to the exe, written whenever you pass --portable or --appdata, so a mode switch survives restarts.
5. With none of the above: portable if the exe's folder is writable, otherwise %LOCALAPPDATA%\PlayPort. The test is a real write of a probe file (.pp-write-test) next to the exe, not a guess about paths the panel should not be writing to. A copy run from Program Files without elevation therefore falls back to %LOCALAPPDATA%.

On every start the panel prints which of these it chose, and why:

Data root: D:\PlayPortData  (installed - the folder you chose; install again to move it)
Data root: D:\playport\playport-data  (portable - next to the exe)
Data root: C:\Users\you\AppData\Local\PlayPort  (the old %LOCALAPPDATA% location - run "PlayPort.exe" --install to move it onto a drive with room)

That third line is worth acting on: %LOCALAPPDATA% lives on the system drive, and a panel there grows a C: drive while another drive sits idle. --install is the one command that moves it.

Installing

PlayPort.exe --install

Without arguments the installer prints what it is about to do and asks Install to <folder>? [Y/n]. --yes skips the prompt for scripted installs, --plan prints the same decision as JSON and changes nothing, and --no-launch installs without starting the panel afterwards.

There is no installer wizard window: the one exe is the installer, the panel, the uninstaller and the updater, and the command line above is the whole installer interface.

What it prints is the decision, not a promise:

Install PlayPort 0.3.1 (build 20260921-125250)
  program: C:\Users\you\AppData\Local\Programs\PlayPort
  data:    D:\PlayPortData
  on that drive: 412 GB free
  moving:  1.9 GB of existing data
             1.9 GB  C:\Users\you\AppData\Local\PlayPort  (appdata)

How the folders are chosen

The program folder defaults to %LOCALAPPDATA%\Programs\PlayPort - per-user, no elevation, no UAC, which is where a user-scope install belongs. The exception is a system drive that is short on room: under 25 GB free, or under 20% free, and the installer puts the program on whichever fixed drive has the most free space instead, naming the numbers in its reason. Override it with --dir DIR.

The data folder defaults to a data folder inside the program folder. Override it with --data DIR on the install command. Choose it deliberately: this is the folder holding every world, every website and every database.

The installer refuses two things outright, with the reason printed:

• An install folder inside the data folder. A copy of the panel dropped inside the folder the panel is reading is the kind of thing that looks finished and then reads its own logs as servers.
• Not enough room - the program's size plus 64 MB of headroom on the target drive.

What it writes

• The program (and a web/ folder, if the copy you are installing was an unpacked build rather than a lone download, so the installed panel serves the same interface).
• playport-install.json in the program folder: folder, data folder, version, build, when it was installed, and an optional update URL.
• Start Menu shortcuts in a PlayPort folder: PlayPort (which runs --open) and Uninstall PlayPort. A desktop shortcut is made too unless you passed --no-desktop.
• An entry in Apps & features under your user account. Its Uninstall button is the same --uninstall the shortcut runs, which is the point: the button in Windows cannot become a data-loss button and it needs no UAC prompt.

Moving existing data on install

If the machine already has a data root with something in it - the portable playport-data/ folder, %LOCALAPPDATA%\PlayPort, or whatever the current install record names - the installer offers to move it into the folder you chose. The move is verified: it copies, counts files and bytes on both sides, and only then deletes the source. If the counts disagree, nothing is deleted and it says where your old data still is:

  the move did not complete: the copy does not have everything: 41023/41024 files, 1.8 GB of 1.9 GB
  nothing was deleted - the data is still at C:\Users\you\AppData\Local\PlayPort
  point the panel at it with:  "C:\...\Programs\PlayPort\PlayPort.exe" --data "C:\Users\you\AppData\Local\PlayPort"

--no-move-data leaves existing data exactly where it is.

If a panel is running from the folder being moved, the move is queued instead. A running panel holds MariaDB's data directory, server jars and session files open, so moving them under it is the one thing that must not happen. The installer writes the job to playport-install-job.json, starts the installed copy with --finish-install --open, and that copy - at boot, before it reads any settings - waits for the old panel to stop and then does the move. If the move fails there, it says so and the panel starts against the new (empty) folder, with your old data named so you can point at it with --data.

Uninstalling

PlayPort.exe --uninstall                    # asks first: "Uninstall? [y/N] "
PlayPort.exe --uninstall --yes --keep-data   # what the quiet Apps & features entry runs
PlayPort.exe --uninstall --purge-data        # deletes the data folder too, because you said so

An uninstall is a statement about the program, so:

• Only panels running from that folder are asked to stop. A panel elsewhere on the machine is not this uninstall's business.
• Your data folder is kept by default, and the size and path are printed so it is obvious what was left and where. --purge-data deletes it, and says the size before doing it.
• Shortcuts, the Apps & features entry and the program files go; the install record (playport-install.json) is deleted first, so a folder left half-deleted by a locked file is not still an "install" the next launch reads a data folder out of.
• Only .exe, .dll, .pdb, .cer and playport-data-mode.txt are treated as the program's own files. Anything else you put in that folder - a world you started beside the exe, a notes file - is left alone.
• The folder itself is removed by a detached cmd after the window closes, because an exe cannot delete itself.

Running the panel

Double-click PlayPort.exe, or from a shell:

PlayPort.exe --open                 # start and open the browser
PlayPort.exe --port 8081            # a second panel beside the first
PlayPort.exe --bind-all --open      # reachable from the LAN (needs the URL ACL below)

The console window

The console window is the panel. It is not a launcher that hands off to a service: it prints the URLs, the data root, the model and brain ports, and then every log line. Closing it stops the panel and stops the servers it runs. A normal start looks like this:

PlayPort 0.3.1 - game server + web hosting panel (single executable)
Data root: D:\playport\playport-data  (portable - next to the exe)
Starting panel on port 8080 …
Panel URL:  http://127.0.0.1:8080/
Stop this panel: PlayPort.exe --stop  (no admin needed - the panel stops itself)
  (from Git Bash use: bash stop-panels.sh 8080)
Model API:  http://127.0.0.1:8100/v1  (API key)
Brain API:  http://127.0.0.1:8101/  (API key)

The boot lines are also written to playport.log in the data root, which is what to hand over when something goes wrong at startup.

Servers marked to start with the panel (autoStart) are started, websites that were enabled are rebound, and a playit.gg agent you left running is restarted - each of those in the background, so a single bad server cannot stop the panel from coming up.

First run: the admin account

Open <http://127.0.0.1:8080/>. Until an account exists, the panel shows the First-run setup card: Username, Password (min 6), Repeat password, and Create admin. That account is the admin, and the form only exists until it does - the first login is made for you, so you land inside the panel.

Two things worth knowing about this screen (Api.cs's Setup):

• The route refuses once any account exists ("already set up"), so the form cannot be replayed to create a second owner.
• A panel that cannot read its accounts file is not a new panel. Both states have zero accounts, and the panel is told which one this is; a damaged auth.json shows "PlayPort cannot read its accounts file" with the reason instead of a form, because creating a new owner over a file the panel refused to overwrite is the one outcome that would turn a readable file into a lost one. See chapter 11 for what to do about it.

Afterwards the card is the ordinary Sign in form. Accounts, roles and per-user permissions are chapter 02's subject.

Making it reachable (loopback, URL ACLs, firewall)

The panel listens on 127.0.0.1 only by default, and so do the model and brain ports. That is why a fresh install is safe to leave running: nothing on your network, let alone the internet, can reach it. When you do want it reachable:

1. Panel bind: Settings → Bind. Or start with --bind-all.
2. URL ACL, once, with admin rights. Windows reserves HTTP prefixes per user; without a reservation the panel can bind loopback and nothing else. add-urlacl.ps1 adds them for the ports it names, in every prefix form http.sys checks separately - http://+:PORT/, http://*:PORT/, http://127.0.0.1:PORT/, http://localhost:PORT/ and http://<LAN-IP>:PORT/. A + reservation alone does not cover the loopback and IP forms, and it uses the sddl= form of the command because user=Everyone fails on non-English Windows.
3. Firewall, once, with admin rights: add-firewall.ps1 adds inbound TCP rules for ports 80, 8080 and 8081. These are port rules rather than program rules on purpose - HTTP sites are served by http.sys in the kernel (PID 4), so a rule scoped to PlayPort.exe never matches their traffic. HTTPS on :443 is PlayPort's own socket, which is why that one works with a program rule.

Both scripts are samples, not settings: they hard-code the ports they touch and the URL-ACL script also names one LAN IP. Read them and edit the lists before running them. The panel prints the exact netsh http add urlacl line itself when it cannot bind all interfaces.

The panel also has a readiness screen that checks reachability from outside rather than assuming it - see chapter 11.

Stopping the panel without an admin prompt

The panel is its own kill switch, so none of these needs elevation:

PlayPort.exe --stop              # any running panel
PlayPort.exe --stop --port 8080  # specifically that one
bash stop-panels.sh 8080         # the same thing in plain curl, for Git Bash

A running panel advertises itself in a small control file (%LOCALAPPDATA%\PlayPort\panels\<port>.json) holding its port, pid, data root and a per-run secret, and it answers a shutdown request on loopback only with that secret. It then stops its servers and websites gracefully and exits - so --stop never cuts a save short.

One Git Bash trap. From Git Bash, running --stop on the very binary that is still running fails with Permission denied (MSYS will not start an image that is already loaded). cmd.exe, PowerShell and bash stop-panels.sh are unaffected; use the script.

Two panels, one machine

Starting the exe again on a port that is already panel-led is detected rather than ignored. With a console to answer on you are asked:

! A PlayPort panel is ALREADY RUNNING on port 8080 (pid 12345).
  Starting a second copy would only fail - your sites/servers are still being served
  by the existing window.
  [K] Stop the existing panel and take over, [Q] quit this copy? (K/Q) [K]:

K (the default) asks the running panel to stop, waits for the port and takes over. Q changes nothing and prints where the running panel is and how to start a second one alongside it (--port 8081). With no console to answer on - a double-click, a script - it takes over, because that is what launching the exe again means. The same handover is what makes updating work: drop in the new exe, run it, and it replaces the old panel.

If the port is held by something that is not a PlayPort panel, the bind fails and the panel says so and exits 1, naming the workaround:

! Could not listen on port 8080: ...
  Is another (non-PlayPort) program using that port? Try: PlayPort.exe --port 8081
  Binding all interfaces may need:  netsh http add urlacl url=http://+:8080/ user=Everyone

A fatal startup error pauses ("press any key") when the exe was double-clicked, so the window stays up with the reason in it instead of vanishing.

There is a third case, and the panel handles it without you: an HTTP reservation owned by something else can make a port answer 503 to everything. PlayPort notices, moves itself to the next free candidate port, saves that choice, and prints how to get the old port back:

  The panel moved to port 8081 instead:  http://127.0.0.1:8081/
  The choice is saved, so this stays your address until you change it.
  To claim 8080 back, remove the reservation once, as admin:
    netsh http delete urlacl url=http://+:8080/

Your first game server

Game Servers → + New server → pick Minecraft Vanilla, Minecraft Paper, SteamCMD or Manual process. For Minecraft, pick a version and accept the EULA; for SteamCMD, pick a game from the catalog or type an App ID; for manual, name an executable. Then press Start and watch the console.

That is the whole of the first-run experience. What each type downloads, how Java is chosen, how config and worlds are managed, and what the modpack and template catalogs offer are all chapter 03; the console, file manager, backups and schedules are chapter 04.

Updating PlayPort

There is no self-updater, on purpose: an update is a newer PlayPort.exe.

PlayPort.exe --update --from "D:\Downloads\PlayPort.exe"
PlayPort.exe --update --from-url https://example.com/PlayPort.exe

Both run inside the installed copy (so the record of the install and the data folder are the ones being updated). The sequence is deliberate:

1. The new file is asked --version before anything is replaced. A file that does not answer is refused and the installed copy is left untouched - "a truncated copy" and "a broken build" look identical until something asks.
2. Panels running from that install are asked to stop (no other panel on the machine is touched), because Windows will not let a running exe be replaced.
3. The old exe is moved aside, the new one copied in, and then the new one is run as the verification. If it does not run, the old one is put back.
4. Your data is not touched, and the panel says so: Updated. Your data (D:\PlayPortData) was not touched.
5. The Apps & features entry is updated so Windows' idea of the installed version matches the panel's.
6. If a panel was running (or you passed --relaunch) the updated panel is started again.

An --update-url recorded at install time is used when you pass no source, so a fleet of panels can be updated with the same URL. The panel's own Settings page also offers updating from a file; that path is chapter 02's.

PlayPort.exe --version is how you check what you are running, and it is the same question the updater asks:

PlayPort 0.3.1 (build 20260921-125250)
installed in C:\Users\you\AppData\Local\Programs\PlayPort, data in D:\PlayPortData

Line one is machine-readable and is the only line the updater reads; line two is for you. If the build was made without its checks passing, line two says so (· checks skipped: ...) instead of looking like every other build.

Moving an installation to another machine

Because the two folders are all there is:

1. Stop the panel (--stop), then copy the data folder to the new machine's drive.
2. Copy PlayPort.exe there and either run it with --data <that folder> or run --install --data <that folder> to record the location properly.
3. Nothing is keyed to the old machine's paths except what the applications inside the data folder wrote for themselves (a game server's own config, a website's absolute paths). Check a server's start command and a site's document root if they named absolute paths.

If you would rather not move by hand, copy the install folder with its playport-install.json too and the new machine reads the same install record - but fix the two paths inside it if the drives differ, or just install again.

What can go wrong at this stage

Files behind this chapter

Chapter 02. The panel

This chapter is the panel as an operator lives in it: signing in, who may do what, what every page in the sidebar is for, the dashboard and its health board, the settings page, and the small pieces that run underneath all of them (search, the activity list, the panel's own log). Each feature page is documented in its own chapter - this one tells you what exists, where it lives and what it is telling you, and points at the chapter that owns the detail.

The panel is one Windows executable serving a web interface on its own port (8080 unless you changed it) and talking to everything else on the machine: game servers, websites, the database, the model ports. It is a local product: by default it listens on 127.0.0.1 only, and the person using it is either at this machine or on the same network.

Signing in

Open the panel's address in a browser - http://127.0.0.1:8080/ on the machine itself, or http://<lan-ip>:8080/ from another device once the panel listens beyond loopback (see Binding, ports and reachability below).

First run. Until an account exists, the panel shows First-run setup: create the administrator account for this PlayPort. It asks for a Username, a Password (min 6) and Repeat password; the button is Create admin. That account is the owner of the machine's panel and the only one that can change panel-wide settings, so make its password a real one. The first-run form disappears for good once the account exists.

Every day after that the card says Sign in - username, password, Sign in - and the session it hands back lasts 30 days. The browser keeps the session token in its local storage, so closing the tab does not sign you out; Sign out at the bottom of the sidebar does, and it is the right thing to do on a shared machine.

When a session ends behind you. The panel answers a request with Not logged in once the token is no longer valid, and the interface reacts by throwing up the sign-in card with the message Session expired - log in again. Any form you had open is gone at that point, so save work before leaving a tab open for a month.

Wrong passwords are rate limited: eight failed attempts for the same username inside a minute and that name is refused for the rest of the minute. This is per username, and it is deliberately simple - it stops a script, and it does not lock a person out for a typo.

One failure mode worth knowing about. The panel will not replace an accounts file it could not read. If auth.json in the data root is damaged, sign-in switches off entirely and the card says PlayPort cannot read its accounts file, with the sentence from the panel itself: it names the file and says the panel kept a copy rather than overwriting your account hashes. There is no form to fill in, because zero accounts is also what a brand-new panel looks like, and letting the first-run form appear here would let anybody who can reach the panel create a new owner over the real one. The way out is stated on screen: stop PlayPort, delete or rename auth.json, start it again, and the first-run screen creates a new administrator.

Accounts, roles and what each account may touch

Users in the sidebar is the account list. Each row has the account name, its role (a dropdown you can change), how many resources are Shared with them, when it was created, and three buttons: Permissions, Reset password and Delete. + Add user opens a small form: Username, Password (min 6) and a Role with the three roles spelled out as the panel spells them:

Three rules the panel enforces rather than trusts:

• You cannot delete the account you are signed in as - the button says so instead of failing later.
• The last admin cannot be removed, so a panel can never be left with nobody who can administer it.
• A resource is only ever assigned to an account that exists, so a server or site can never end up owned by a user id that has gone (which would make it invisible to everyone but staff).

Sharing one server or site with somebody else is the Permissions button, and it is the capability model in one dialog. Each server and each website gets four checkboxes, in this order:

They imply each other downwards - Files implies Start/stop implies View, and Edit implies Start/stop - because a permission model nobody can explain is a permission model nobody checks. Nothing implies Files: file access is the one that can become code execution. Ownership and staff roles always win, so a grant only ever adds access and can never take it away. Ticking nothing for a resource stores nothing; ticking a capability for an account whose role is already admin or moderator is kept, but the dialog says plainly that the role already grants everything and the grants are only kept in case the role changes back.

Programs do not sign in; they present a key. Everything outside the browser - another PlayPort, an AI tool, a script - reaches the model and agent port with an API key rather than an account, and those keys are created on the Agents page. The three doors are listed in Appendix B; the agent side of it is chapter 10.

Where all of this is stored. Accounts, password hashes, roles, grants and sessions live in one file in the data root: auth.json. Passwords are stored as PBKDF2 hashes with a per-account salt, never in the clear. Panel-wide settings live beside it in settings.json (see Appendix C). Both are the panel's own files, and both are in a backup of the data root - the panel ships no separate account database.

The sidebar, and what every page is for

The sidebar is grouped into three labelled sections and always in this order. The icon rail collapses to icons on a narrow window; the search box stays at the top of it.

WORKSPACE

LOCAL AI

ADMINISTRATION

At the bottom of the sidebar: the colour theme picker (Colours), the Future effects toggle, and the account strip - your name, your role, and Sign out.

The dashboard (Overview)

The Overview page is deliberately two things: what the machine is doing right now, and what you run.

The stat cards, left to right:

Two charts under the cards - CPU and Memory - drawn from the machine samples the panel takes in the background. They are history, not a live gauge: the samples it has collected, scaled to the highest value in the recent stretch, with the scale marked top-left. A panel that was just restarted shows waiting for data… until it has a few.

Two tables, the same ones the feature pages use, so the dashboard is a way in rather than a second place to maintain: Game servers and Websites, each summarised by status. A fresh install says so in words - No game servers yet - create one - rather than showing an empty table.

The System health popover sits in the page's toolbar (staff only, and why is in the next section). Re-check re-runs it immediately.

The banners at the top of the dashboard

Some failures are not about a server or a site but about the panel's own memory of what you chose, and those get a banner at the top of the Overview page. There are four kinds, and they are worded differently on purpose, because each one sends you somewhere different:

• A change could not be saved. The change is on screen and not on disk, and it will be gone at the next start. The panel says which file and why, and names what to do. This is the shape that used to end with "I turned that off and it came back".
• A saved file could not be read. The panel started from defaults for that file. It kept what it could not read - named on the banner - rather than overwriting it, so the old values are still there if you can read them back.
• A file could not be read (a file the panel does not own, such as a game server's server.properties or its whitelist). The panel left it exactly where it is, and anything a page shows for it may be empty rather than true. Open that server's Files tab.
• Something the panel was doing could not be finished. An action was accepted and then failed on the worker that runs it. The banner says the panel and every other server are still up, because the alternative reading of a warning like this is that the whole machine is falling over.

System health: one screen of truth

The health board is the panel checking its own machine once and giving each part a verdict in words. It is staff only - it reports on the machine rather than on one tenant's corner of it, and /api/health refuses it to a plain user rather than drawing an empty screen. On the dashboard it is the System health popover; on Settings the same report is what fills the Components rows (MariaDB's state, for example, is a health row before it is a download button), so the two screens cannot disagree about whether a piece of this machine is working.

Four verdicts, and the last one matters as much as the first:

The board opens with one line of summary and a count, for example Everything is running, with 2 thing(s) worth watching with 14 ok · 2 watch · 0 down · 1 off beside it. Under that, one row per part: a state dot, the part's name, and its current state in a sentence. A row that is healthy says one line and stops; a row that is not gets the next step printed under it in words rather than a red dot, and a part the panel can fix on the spot carries a small button instead of a sentence telling you which page to visit. Some checks are worth knowing about by name:

• Panel - this build, its version and build id, where it is listening (loopback only, or reachable from the network) and how long it has been up. If the build was made without its checks having run, that row says so, in the same place as the version.
• Saved settings - the banner subjects above, collected in one row. It counts the unreadable files and the unsaved changes separately, because telling an owner one is the other sends them looking at the wrong half.
• The data volume - free space, against the warning line you set yourself (Settings -> Alerts).
• Database, Email, PHP, Java runtimes, SteamCMD, Tunnels, Certificates - the components this machine has been asked to run, each with its own state and its own next step.
• Websites, Servers, Backups - whether sites are serving, whether servers are crashed or looping, and whether every server has a recent backup.
• Work - background jobs that finished with an error.

Unrecognised crashes (the review queue)

The panel explains server failures from a library of known patterns, offline and instantly: it can say I do not recognise this but it never invents a cause. Anything it cannot name still gets filed, and that filing is the review queue - it appears on the Activity page, and only when there is something in it, so it stays out of the way until a crash needs a human.

The queue groups crashes by a signature of the "errorish" lines in the log, so a crash loop becomes one entry with a count instead of hundreds of entries. Each entry carries the failure's own most distinctive line, when it was first and last seen, which server (and its type and version) produced it, and the tail of that log. The actions on the panel are:

• Work them out now - the panel reads one entry itself and shows what it makes of it beside the entry. It is deliberately one entry per press: this machine also hosts game servers, and a button that fires six prompts at a GPU running one is how a feature becomes a stutter. Whether the panel's automatic pass is on is stated on the same line - the panel is not reading these itself when it is off - and its answer is labelled a hint, not a rule.
• Re-check all / Rescan on one entry - the current rules are run over the saved logs again. If a rule was added since an entry was captured, the entry flips to understood and can be cleared. Rules are re-run over the whole queue at every panel start, so this happens on its own too.
• Delete an entry, or Clear all. Clearing deletes every saved unrecognised log; a crash that happens again is filed again.

The queue is held in unknown-crashes.json in the data root, capped at 60 entries of up to 40 lines each, and nothing in it leaves the machine - it is a filing cabinet, not a service. Its normal life cycle is: a crash lands here, a person reads the log, a rule is added, and the entry is re-checked until it is understood.

Activity: everything the panel is doing

Activity is one list of every long-running thing: installs, updates, builds, starts, stops, Java runtime downloads, database work, site work, template downloads and network operations. Each row shows a kind, a title, a state pill, when it started (and how long it took if it has finished), any detail line the job carries, and a progress bar while it is live.

• A job that failed gets a Retry button that re-runs the exact operation. Retrying is offered only where it means something, and the button's own reason says why when it is not there.
• A job that produces something you can look at gets Open.
• Clear finished removes the finished rows, so the list stays a work list rather than a log.
• The sidebar entry carries a badge with the number of running plus failed jobs, and it turns red as soon as anything failed. Recent work at the bottom of the page is the history behind it.

The panel's own log

Everything the panel does that an operator might need later goes into one file in the data root: playport.log. Each line is stamped, and the API writes the whole stack there when a request fails, keeping the response itself to one sentence - so a 500 in the browser is not a dead end. The console window that opened with the panel prints the same stream, which is why closing that window stops the panel (see chapter 01). Per-server consoles and log files are a different thing entirely and are chapter 04.

Settings

Settings is one page of cards. Any signed-in account can open it, but the fields are disabled unless you are an admin, and the staff-only panels and their contents are only drawn for the roles that can use them: Server readiness, Databases, Backup destinations, Storage and Alerts are admin-and-moderator surfaces (the two database and backup panels are admin). In the order the page draws them:

Components - the pieces the panel downloads and runs on this machine: MariaDB (databases for sites and game servers, ~90 MB), cloudflared (public URL without opening a port, ~60 MB), and playit.gg (a public TCP/UDP address for a game port, ~5 MB). Each row has a state, what it is for, its size, and one small button that is the honest next action - Install, Start, Stop, or Enter secret key where the agent needs linking. Installing from here is admin-only, and a download that previously failed says so on the row instead of offering the button again blindly.

Panel & defaults - the settings that belong to the panel itself:

There is a Reaching this panel from the LAN explainer next to those fields, because the two binds are different questions: the panel's bind decides who can reach the control panel, and the website bind decides who can reach websites. A specific IP (for example 192.168.1.225) is what makes sites reachable on your network, and on Windows it needs admin rights or a URL ACL once. Only an admin gets a Save button; everyone else reads the note that says so.

Server readiness - the checks that answer is this machine actually reachable from the internet? Run checks measures it and the result is kept for the session so the page's own refresh does not re-probe the network. What each result means is the network path in chapter 11.

Tunnels - the Cloudflare side: quick tunnels and named tunnels for your sites (chapter 05).

Databases (admin) - the bundled MySQL/MariaDB server: install, start, stop, and the database list (chapter 06).

Backup destinations (admin) - the folders and shares that backups can also be copied to, for backups that leave the machine (chapter 04).

This installation - see below.

Storage and Alerts - the two panels handed to this page by its ops module. Storage totals the data root on disk (cached, with a Re-measure button): game servers, websites, backups, Java runtimes, the database and SteamCMD, the volume's free space, a per-server and per-site table, and the largest folders in the data root - which is the answer to what is filling my C: drive. Alerts is where you are told when something breaks: a Discord/Slack webhook URL, an email address, three events to subscribe to (A server crashed, Auto-restart gave up, An off-machine backup copy failed), a data volume this % full threshold with 0 = off, a de-duplication window (repeat the same alert after this many minutes, 0 = always), Save alerts and Send a test. Both panels are staff-only; alerts are chapter 10's subject.

This installation (a report, not a button)

The This installation card answers the questions a settings page should, and it does nothing. It shows where this copy is running, whether it is an installed copy or a portable one, where its data root is and how big it is, which other folders on this machine hold PlayPort data (and whether they are empty or abandoned), whether an install or move is still queued, and the port story - including, on a machine where the panel had to move off its configured port, the one admin command that gives it back.

Installing, updating and removing this program are done from a console, not from a web page:

PlayPort.exe --install   |   --update   |   --uninstall

That is deliberate, and it is the whole reason the card is a report: installing is a decision about a machine's folders, and the only front for it is a console somebody typed into. There is no in-panel Update button to look for - the flags, and what each one does, are in Appendix A and chapter 01.

Search (Ctrl+K)

The sidebar has a search box - Search everything, or press Ctrl+K anywhere in the panel. One query covers game servers, websites, databases, mail domains and mailboxes, users, backup archives and server console history, grouped by kind, one click from the destination page. Esc closes the overlay.

Two rules make it trustworthy rather than clever, and both are worth knowing when you rely on it:

• It never returns something you could not open anyway. Every hit goes through the same permission check the real page uses, so search cannot leak another tenant's server names.
• It never reads files from disk. Console hits come from lines already held in memory and archives are matched by name, which is why it answers instantly instead of walking every world folder.

A term shorter than two characters returns nothing but a hint to type more.

Appearance

Two controls sit at the bottom of the sidebar, and both are stored in your browser, not on the server, so they are per-browser rather than per-account:

• Colours - twelve palettes: Original, Ocean, Rose, Forest, Amber, Violet, Slate, Ember, Mint, Midnight, Sand and Neon.
• Future - the panel's optional futuristic effects on top of the palette.

The product's own name and mark (the controller whose middle is a server rack, green on one side and violet on the other) are fixed, drawn once and shared by the boot screen, the sign-in card and the sidebar, so the three can never drift apart.

The phone layout

The panel is usable from a phone or a small window on the same network. What changes at a narrow width: a single-column card layout, the sidebar reducing to an icon rail (and its labels, account strip and theme controls hidden), a horizontally scrolling nav, sub-menu tabs that stick under the top bar, form rows that stack, and modals that become full-width sheets. Wide tables scroll inside their own container rather than forcing the page sideways, so there is never a page-level horizontal scrollbar. Inside the server picker, the category rail becomes a horizontally scrolling chip row so the template tiles get the full width.

Reaching it from a phone needs the panel to listen beyond loopback and the machine's LAN address - http://<lan-ip>:<port>/ - which is the Bind setting above plus the network's own firewall.

Binding, ports and reachability

This is the short version; Appendix B is the table and chapter 11 is the network path in full.

• The panel listens on its own port (8080 by default) on 127.0.0.1 only until you change Bind. Changing the port or the bind needs a panel restart.
• Sites listen on their own ports and bind to the Website bind address - loopback by default, which needs no admin rights at all, and a specific LAN address or all interfaces when you want them reachable.
• Game servers each have their own port, and their own firewall question.
• The model and agent port (8100) and the brain port (8101) are separate doors with separate promises: loopback unless you turn on Reachable from the network, and an API key required whatever the bind. The panel's Ports screen names all of them with what each one is for, and it reports where the listeners actually are rather than where the settings say they should be - a bind that was refused by Windows is stated on that screen instead of being repeated as if it worked.

Files behind this chapter

Chapter 03. Game servers

This chapter is about the server side of the panel: creating a game server, choosing what it runs, giving it the right Java, starting and stopping it, and knowing what the panel does when it dies. It covers the four families of server (Minecraft, SteamCMD games, manual processes and modpacks), the template catalog, the Java runtime the panel fetches for you, and the restart policy. The console, the file manager, backups and schedules have their own chapter (04); installing the core plugin into a server is 07 and its in-game behaviour is 08; Minecraft networks (a proxy in front of several servers) are 09.

Everything here assumes you are signed in and can reach Game Servers. The panel port, the data root and the command-line flags are in chapter 01 and Appendix A.

What a game server is in PlayPort

One game server is one instance: its own folder under playport-data/instances/<id>/, its own port, its own console, its own install. Instances do not share a game directory, and nothing about one server can change another - which is what makes two servers on one machine behave like two servers on two machines.

The panel creates and runs four kinds of instance, and they differ in where the files come from rather than in how they are run:

Networks add two more types the picker shows under Networks - velocity (a proxy) and limbo (NanoLimbo, a tiny lobby/AFK server) - and those are chapter 09.

Creating a server

Game Servers -> + New server opens the picker. It is one catalog with a search box (Search games, modpacks…) and six categories:

• All - everything below, in one list.
• Minecraft - the server software this build can create. The list is not written into the page: it comes from the panel (/api/minecraft/software), so software added to the panel appears here without the page changing. Each tile carries the software's own one-line description, e.g. Paper is "Fast, modern and the one most plugins target.", Vanilla "Exactly what Mojang ships. No plugins and no mods of any kind.", Fabric "Lightweight mod loader…", Forge "The older mod loader, still what most 1.12 to 1.16 packs need."
• Networks - a whole Minecraft network in one click, a bare Velocity proxy, or a limbo server.
• Modpacks - server-compatible packs from Modrinth, searchable and paged.
• Templates - the game template catalog (below): every SteamCMD and manual game.
• Manual - a process you point at yourself.

Clicking a tile opens the second step: the settings that instance needs. Every create asks for the instance's own values (a name, memory, its port, its Java runtime) and, where they apply, the ones this chapter explains: the Minecraft EULA, the start executable and arguments, auto-restart and auto-start, a starter pack, a core-plugin profile, and the worlds the server should be made of. Creating an instance is not instant for the non-manual kinds: the panel starts an install job, the instance appears immediately in the installing state, and its console is where the install narrates itself.

The EULA is asked once and enforced twice. Minecraft servers refuse to start until eula.txt says eula=true, so the panel writes that file as part of the install and again at the last moment before every launch (in BOM-less UTF-8, because Java reads a byte-order mark as part of the line and refuses the file). The second write is the one that matters in practice: a server installed before you ticked the box - or installed by a template, a pack or a test - used to print Failed to load eula.txt on every start while the hint told you to tick a box that had no effect. Now "tick the box, then press Start again" actually works, which is what the panel's own diagnosis tells you to do.

Minecraft

Pick the software, then pick the Minecraft version. What happens on install depends on which one:

• Vanilla and Paper - the panel downloads the server jar for that version from Mojang or PaperMC. inst.Version is the version you chose.
• Purpur - the panel resolves the build from Purpur's own API for that Minecraft version, so "latest" is resolved to a real version rather than stored as the string latest.
• Fabric - Fabric publishes a ready server launcher per Minecraft version, so nothing has to be built and no Java needs to be present to create it: the panel downloads the launcher and records the newest Fabric loader build for that version.
• Forge and NeoForge - two steps, and Java is needed before either: the panel resolves a loader build for the chosen Minecraft version and then runs the loader's own installer. If no runtime is installed yet, the install stops with a sentence saying so rather than failing later with something cryptic.

On 1.17 and newer, Forge and NeoForge servers are not launched with -jar: they boot through the argument file their installer wrote. The panel detects that and uses it, so a pack that installs perfectly does not then refuse to start.

SteamCMD games

SteamCMD is Valve's own command-line client, and this is the same shape AMP's SteamCMD module has: the panel installs and updates files, and the way your game boots is yours to set.

• The catalog covers popular dedicated servers (Counter-Strike 2, Team Fortress 2, Garry's Mod, Valheim, Palworld, ARK, Project Zomboid, Rust, 7 Days to Die and more), and you can type any App ID. Entries marked needs login are games whose dedicated server is not downloadable anonymously.
• The first install downloads steamcmd.exe from Valve (~0.8 MB) into playport-data/steamcmd/, and every SteamCMD install then runs through it. Download progress is streamed into the instance's console in 5% steps rather than a wall of redraws.
• Anonymous install needs no account. For a game you own, the instance's Settings tab takes a Steam username (blank = anonymous) and password. Be aware of what that means: the password is stored in the instance's own instance.json in plain text, like the panel's own instance config - use a Steam account created for this server rather than your main one.
• Check for updates before starting runs app_update for the App ID first and only starts the server if the update succeeded. There is also an auto-update timer on the same tab: with it on, the panel re-checks the App ID on an interval (four hours by default) and reports what it did. A Validate flag passes SteamCMD's file verification.
• Start executable (relative to server folder) and Start arguments are what actually boots the game, e.g. steamapps/common/valheim/valheim_server.exe. A game template usually fills both in for you; a bare App ID does not.
• The panel deliberately does not guess: pressing Start on an instance with no App ID logs ! No Steam App ID configured. and stops, rather than launching something arbitrary.

The game template catalog (CubeCoders' AMP library)

The Templates category is the catalog AMP itself ships, read from CubeCoders' public AMPTemplates repository. The panel does not vendor or clone it: it downloads the repository index once, parses each template manifest, and keeps a normalised copy in playport-data/templates/catalog.json. After that first fetch the picker works offline, and the button under the list (Fetch templates, then Refresh) re-pulls from GitHub when you want something newer. The fetch runs as a job, so a slow first download shows its own progress.

A template is what makes this better than a bare App-ID list, because it carries everything needed to run a server: the display name and description, the dedicated-server Steam App ID, the Windows executable and command line, the working directory, the default port, whether an anonymous install is allowed, and the header image. Templates for services this panel already provides (MySQL, MariaDB, PostgreSQL, Redis and friends) or that are not games (language runtimes, code-server) are skipped on purpose, so the list stays a game list.

Two things to check before you trust one:

• A template's command line can contain {{Setting}} tokens that only the game knows. The panel resolves the ones it can (the port tokens) and leaves the rest visible in the start arguments and on the instance's Settings tab, rather than silently dropping arguments and producing a server that half-starts. Fill them in.
• A template whose OS is not Windows is marked as such, and one with no Steam stage is a manual install: the panel creates the folder and waits for you to upload the game files.

Modpacks (Modrinth)

The Modpacks category browses Modrinth's public API - free-text search and paging, not a fixed top list - and shows only packs that can run a dedicated server (Modrinth marks client-only packs as server-side unsupported, and those are filtered out). Each tile shows the pack's loader and the newest supported Minecraft version.

Installing a pack downloads the .mrpack, puts every mod where its loader expects it (mods/), applies the pack's overrides, and installs the loader the pack names (Fabric, Forge, or NeoForge) so that the panel's normal Minecraft launch path works. The exact loader build and Minecraft version are recorded on the instance, so a later update reinstalls the same build instead of silently moving your server onto a newer one. Java is required before the loader installer can run, and the install fails fast with "click Install Java in Settings -> Runtime, then re-run Install" rather than after downloading hundreds of mods.

Starter packs, the core plugin and the worlds a server owns

A fresh Minecraft server is not useful on its own, so the create form can apply a starter pack:

• A Paper or Purpur server is offered this product's own core plugin templates - one pack per profile the bundled plugin ships. Ranks, claims, an economy, homes and teleports, mines, shops and the panel's editors are all in that one jar, so the first-hour problem is answered by one plugin with a template rather than fifteen jars from nine authors. See chapter 07.
• A mod loader or Velocity server gets its own third-party packs, because the core plugin is a Bukkit plugin and cannot run on a modded server at all.
• Vanilla gets nothing, because it loads nothing.

The same form can ask for the worlds the server should be made of - a name, a preset and an optional seed per world, chosen from the presets the bundled plugin ships. A world is the one part of a Minecraft server that cannot be fixed afterwards: the plugin can adopt land that already exists, but adopting keeps whatever generated it, so a world the server made itself is ordinary vanilla terrain no matter which preset you name later. The list therefore travels with the create, the install writes it into the plugin's panel-worlds.yml, and the plugin makes those worlds on the first start. A row the validator refuses is refused by name in the new server's own console (! world request refused: <why>), so a typo arrives as a sentence rather than as a world that quietly is not there.

The Java runtime

Minecraft needs Java, and the panel answers "which Java" from Mojang's own published metadata rather than from a table somebody maintains: it reads the version manifest, asks for the version's own document, and records the majorVersion there. A Minecraft release published after this build therefore gets the right runtime, and a version whose requirement changes is picked up the next time it is resolved. Every answer is cached in playport-data/java-requirements.json, so the picker, the create flow and the start path all keep working with no internet at all; when a version has never been resolved and the metadata cannot be reached, a rule derived from the version number answers instead, and the panel says which of the two it used rather than pretending they are the same thing.

The panel installs Temurin JRE runtimes from Adoptium on demand - Java 8, 17, 21 and 25 - about 45 MB each, into four folders under the data root: playport-data/jre8, jre17, jre21, jre25. Finding a runtime works from the outside in: PLAYPORT_JRE if you set it, then a bundled runtime, then the usual vendors' install folders (Java, Eclipse Adoptium, Microsoft, Zulu, Amazon Corretto, BellSoft…), then JAVA_HOME, then whatever java is on PATH.

Pressing Start once is enough. If the runtime a server needs is missing, the panel downloads it there and then, the instance sits in Waiting for the Java runtime this server needs, and the start goes ahead by itself when the download finishes. A panel-wide sweep also re-resolves the requirement for every Minecraft instance and fetches a newer runtime when one is needed, so a server that moves to a newer Minecraft version does not start failing on a class-version error.

Running a server

The instance page has one tab per subject: Overview, Console, Game, Players, Plugins (or Mods, depending on what the server can load), Files, Backups, Schedules and Settings. Start, Stop and Restart live on the overview and in the list.

• Start resolves Java, writes the EULA if needed, then launches. Minecraft servers need either server.jar or the loader argument file; if neither is there you get ! No server.jar - run an install/update first. rather than a process that exits instantly.
• Stop is graceful: the panel asks the server to shut down and waits (the instance's own StopWaitMs, 40 seconds) so the world is saved.
• Kill exists for the case where the server will not answer, and the panel refuses it while the server says it is making a world. That refusal is not politeness: since Paper 26.x a world is written in stages on the first boot, and a process killed between them leaves a folder that looks real and can never be read again. If that has already happened, the panel recognises the state from the disk, sets the half-built world aside (renamed beside the server with a note saying what it is - never deleted, because the one thing a reinstall cannot bring back is somebody's land), and names it instead of calling it an unexplained crash.
• When the process exits on its own while the panel thought it was running, the instance goes to crashed with the exit code, the console gets ! Process exited unexpectedly (code N). and a plain-English explanation, and - if no rule could explain it - the evidence is filed in the unrecognised-crash queue for later (chapter 02). Three of the commonest instant exits are named directly in the console: a Java that is too old, an unaccepted EULA, and a port that cannot be bound.
• Live status comes from speaking the Minecraft server-list protocol (the same exchange your game client does), so the panel shows whether the server answers, its MOTD, its version and how many players are on - for Vanilla, Paper, Velocity and NanoLimbo alike, with no plugin involved. It is a status read, cached for a few seconds so a polling dashboard does not hammer a backend. The server's own server.properties can hide it from the server list, in which case the panel says so rather than claiming the server is down.
• Ports. Each instance has its own port, and the panel keeps instance ports and website ports from colliding when it suggests a free one. Opening a port to the internet is done on your router and in Windows Firewall - see chapter 11 - and reachability is checkable in the panel rather than guessed.
• Closing the PlayPort window stops the servers it runs. The panel stops them gracefully on exit; that is why the window is not a thing to close casually.

Restart policy

Three separate things, and it is worth knowing which one you are turning on:

• Auto-restart after a crash. With this on, an unexpected exit is retried automatically, backing off (about 8s, 16s, 32s) and saying so in the console: Auto-restart scheduled in ~16s (attempt 2 of 3). The loop is bounded on purpose: three starts that each died within a minute stop it with ! Auto-restart gave up: the last 3 starts each died within a minute (the last one lasted Ns). and an alert, because retrying forever fills the disk with crash reports and buries the cause. Pressing Start yourself resets that budget - a fix followed by a manual start is not still at the edge of giving up.
• Auto-start when the panel starts, for servers that should always be up.
• Scheduled restarts and the warning before them. A restart at 04:00 with no warning is the commonest complaint about a server, so a scheduled restart announces itself over the server's own console - Server restarting in 3 minutes., then one minute, then ten seconds - which is when players actually finish what they are doing. Schedules themselves (including a restart, a stop, a backup, an update check or a console command on a timer) are chapter 04.
• Steam auto-update is the fourth timer and lives on the Steam instance's Settings tab.

Editing the server's own config

The Game tab is an editor for server.properties, which is where every Minecraft owner ends up and is normally the worst interface in the stack: dozens of keys, no labels, no ranges, and a server that rewrites the whole file on boot (losing your comments and reordering your keys). The panel carries a schema - a label, a group, a sentence of help, a type, a range and a default for every key it knows - so the page draws real controls instead of a text box. The groups are Identity, Gameplay, World, Performance and safety, Remote access, Resource pack and Other keys in this file.

Two behaviours worth knowing:

• The panel writes back only the keys you changed. Comments, keys added by a newer version, and keys a plugin wrote are left byte for byte where they were found.
• Duplicate keys are collapsed, and the response says which lines were removed. Java's Properties reader keeps the last occurrence of a key, so a file with view-distance=10 near the top and view-distance=32 further down shows 32 in game while you edit the 10 and nothing happens. That confusion is common enough to fix on write.

The core plugin's own settings are a different surface and are documented in chapter 07 (the panel side) and chapter 08 (config.yml and the in-game editor). Anything Java-based whose file does not exist yet says so and points you at the Files tab.

Players: whitelist, operators and bans

The Players tab is the four JSON files nobody wants to hand-edit (whitelist.json, ops.json, banned-players.json, banned-ips.json) plus who is online right now, in one list. Every entry in those files is the player's Mojang id in dashed form; get it wrong and the entry silently does nothing, so the panel never guesses:

• While the server is running, every change is a normal console command (whitelist add, op, ban, kick), so the server resolves the name itself and writes its own file.
• While it is stopped, the files are edited directly, resolving the name against Mojang's public lookup and falling back to the deterministic offline-mode id (the md5 of OfflinePlayer:<name>, the same value every offline server computes). The answer says which of the two was used, because a guessed id on an online-mode server looks exactly like success.
• Actions that need a live server (a kick) say so instead of failing quietly, and a name that is not a valid Minecraft name is refused before anything is written.

What is on disk, and what is safe to move

playport-data/instances/<id>/
  instance.json    the instance's whole configuration (including a Steam password if you set one)
  console.log      the console history the panel shows
  server/          the game's own files - the server jar, worlds, plugins/mods, server.properties
  backups/         this server's archives

Copy the instance folder while the server is stopped and you have moved the server; that is also what the panel's own backup does. session.lock and playport.lock are deliberately not part of a copy.

Copying a server in one click

Copy on an instance makes a clone: the configuration, the mods, the plugins, the worlds, the starter pack and the core-plugin profile come across, and the clone is put on its own free port - a clone that immediately dies with "address already in use" would be worse than no clone at all - with the port rewritten in the copy's own server config. What is deliberately not copied: the backups (that would double your disk use for nothing), the logs (they describe a different server), the crash history, the schedules and saved commands, the panel's per-server link token and saved plugin settings (each server gets its own), and the database link - a copy that came up pointing at the original's database would write the original's player records from a second server, two servers and one set of balances with nothing on screen saying so.

Gotchas worth knowing up front

• A Steam or manual server that will not start is usually the start executable. It is relative to the server folder (steamapps/common/<game>/<game>_server.exe), and a template usually knows it; a bare App ID does not.
• A server that dies instantly on a port it cannot bind has a collision - another instance, a website, or an unrelated program. Read the console hint and change the port in Settings.
• A Minecraft version the machine cannot run shows up as a memory or CPU problem rather than a clean refusal: check the RAM you gave the instance against the machine's own headroom (the dashboard and the health screen are chapter 02).
• Disk fills from worlds and from SteamCMD installs; the panel tracks storage per server (chapter 04) and warns before it is a problem.
• The panel must be running for the servers to be watched - closing its window stops them (they save first). Past that, they are ordinary processes on your machine.

Files behind this chapter

Chapter 04. Files, console, backups and schedules

This chapter is the day-to-day of running a server: what the server is telling you, what is on its disk, what a backup actually contains, and what the panel does on a timer. It assumes the server already exists - creating one, its versions, its Java runtime and its start/stop policy are chapter 03. Site files (and the ZIP import that only a website takes) are chapter 05, database dumps are chapter 06, and the panel's own state - the thing you would restore the panel from - is chapter 11.

A server page has these tabs, and three of them are this chapter:

Overview · Console · Game · Players · Plugins/Mods · Files · Backups · Schedules · Settings

Which of them you can see depends on your account, and the gating is per tab: Files and Plugins/Mods need the files permission, while Backups, Schedules and Settings need edit. A staff member with only view rights cannot reach any of them, and the server refuses the request as well - hiding the tab is convenience, not the security boundary. See chapter 02.

The console

Console is the server's own output, streamed to the browser as it is printed, with a box at the bottom that sends a line straight into the server's stdin.

What it holds, and for how long. The panel keeps a rolling in-memory buffer of the last 3000 lines and appends every one of them to a real log file beside the server's configuration:

<data>/instances/<id>/console.log          the server's console, one line per entry
<data>/instances/<id>/console.log.old      the previous file, kept when the log passes 8 MB

Each line is stamped [HH:mm:ss] text. The file is capped by rotating it to console.log.old once it exceeds 8 MB, so there is always a bounded amount of history on disk and one generation behind it. The browser buffer is memory only: restarting the panel empties what you can scroll back through, not what is on disk - the file is where the words live.

Lines the panel writes itself are mixed into the same stream, and they are marked so a reader can tell them apart from the server's own output:

Those prefixes matter beyond readability: they are what the log reader uses to drop the panel's own earlier commentary before a reading is handed to a model, so a model cannot read its own previous guess as evidence (see the log feed).

Sending a command. Type into the box at the bottom of the console and press enter. Sending to a stopped server is refused - there is nothing to write to - rather than silently queued.

Saved commands. Below the box there is a save typed command button. Name a command once (save-all, whitelist add Steve, a maintenance broadcast) and it becomes a one-click chip on the console, stored with that server. The limits are enforced by name rather than by a silent truncation:

• one command per entry - a pasted multi-line blob is refused, not saved as a broken button;
• 300 characters maximum per command;
• 30 saved commands per server - the 31st is refused with "delete one first".

The log feed and crash explanations

When a server dies, the panel does not just say "it stopped".

The rules run first, offline. The moment a server enters an error or crashed state, the tail of its console is scanned by a rule-based analyzer - no AI, no API key, nothing leaves the machine - and the result is printed as a plain-language cause with a suggested fix. It knows the failures people actually hit: a missing or wrong Java version (with the exact java.exe to install), the port already being in use (it names the other server on it), the EULA not having been accepted, an out-of-memory limit, a world saved by a newer version, a config file that will not parse, and mod/plugin dependency clashes. The banner offers What happened? / Why did it crash?, and the console has Scan again and Look further back for a cause that scrolled past the window.

The one failure a console cannot explain is a half-made world folder, so the panel reads the folder too and puts the finding where the crash is: what shape it is in, how much land is in it, and - only when there is a level.dat, no world-gen settings and no chunk ever generated - one button that sets the folder aside as world.broken-<timestamp> so the server can generate it properly. A world with land in it is never moved by the panel; it says so instead of offering. Once the folder is fine the fatal finding is dropped rather than left accusing a repaired server.

The log feed, before any model sees anything. A Minecraft console is mostly not errors: a plugin list, a lag monitor, a spark banner, a warning about sun.misc.Unsafe and a wall of at java.base/... frames. The panel distils the window first - it keeps the exception, what the server said it could not do, the Caused by chain and a few frames per exception, and drops the banners, the repeated warnings, the JVM plumbing and the panel's own earlier lines. Two rules keep it honest:

• it never invents a line - everything kept is a line the server printed, in that order;
• it says what it dropped - the counts (kept, routine, known noise, frames folded) are shown next to the answer, so a reading made from four kept lines looks like one.

You can see exactly what a model would be handed, with no model and no panel:

PlayPort.exe --feed path\to\console.log

That prints the kept lines, the counts and the same summary sentence the page shows. Which model answers, and what the tiers and the free cloud do, is chapter 10.

When no rule matches, the evidence is not thrown away: a trimmed copy of that server's log is kept and listed under Activity -> Unrecognised crashes (admin/moderator only, since a log can belong to any client's server). That review queue, and what the panel does with it, is chapter 02.

The bot that reads a log for a person is the same machinery: Help answers questions about this machine (the assistant, its hands and what it may touch are chapter 10).

The file manager

Files on a server page browses the server folder; Files on a site page browses the site folder. It is the same manager, rooted at the thing you opened, and it needs the files permission.

What it will not do. Every path goes through one resolver that resolves it against the root and refuses anything that lands outside - ../ traversal, an absolute path, a name that escapes the folder. A refusal is answered as Invalid path, and the manager never touches a file outside the server or site folder it is rooted at. The same guard is what stops a crafted archive from writing outside the folder on restore (see below).

Failures are translated. The manager's own errors are the ones a buyer meets most - a folder the panel may not read, a file another program holds open. The raw Windows sentence goes to the panel log (where Diagnose reads it) and the browser is given the class of failure instead, so "Access to the path 'D:\...' is denied." never becomes the toast.

Two things to know before you rely on it.

• An upload's body is read into memory by the panel; this tree sets no size cap of its own, so a multi-gigabyte upload is a memory question as much as a disk one. For a large install, use the server's own installer (modpack, version change) rather than pushing the files through the browser.
• A running server can overwrite your edit. Minecraft and its plugins rewrite many of the files under their folder when they save - server.properties, a plugin's own YAML, level.dat blocks. Editing a config while the server runs is fine only for files the server re-reads on a reload; for anything else, stop the server, edit, start it. The panel does not lock files to protect you from this, and it does not pretend it does.

A site's Files page is the one with the ZIP import and the framework build - that is chapter 05; a game server's Files tab deliberately offers upload instead.

Backups

Backups is where you decide what an archive contains, where it goes, and what is kept. Its whole point is that "back up my server" should mean "the things I would be upset to lose" unless you say otherwise: a full zip of a modded server is routinely many gigabytes and most of it is regenerable.

The plan: what a backup contains

The tab opens with six categories, each showing what it would actually take - measured, not published as advice:

Three one-click starting points are offered next to the numbers - Smallest (player data and settings), Standard (player data, settings, world, plugins - the default for a new server) and Everything - each shown with what it would cost before you commit to it.

Extra paths can be added by hand, and they behave exactly like a built-in rule: myworld/ takes a folder, notes.txt takes one file, *.dat is a glob. A path that no longer exists is named in the plan and in the server log - an entry that has been renamed should be visible, not silently missing from every archive from then on.

How matching works (worth knowing, because it decides what a rule of yours really takes): paths are relative to the server folder, case-insensitive, with / separators. world/ is a prefix - the folder and everything under it. *.yml is a glob over one path segment, so it does not cross a / and a root-level config stays separate from a plugin's own config folder. * is the whole folder. A file matching no rule is simply not archived. Nothing outside the server folder is ever followed, and a symbolic link or junction is skipped rather than traversed - a link to C:\ is not part of a backup.

The selection is remembered on the server, so the button and a schedule agree by default; a schedule may override it (below). The measured sizes come from one metadata-only walk - nothing inside a file is read - and the archive is written by the same walk, so the number shown is the number of files it takes. The measured plan is held for twenty seconds while the tab polls (Instances.BackupInfo's cache) and re-measured as soon as you change the selection - note that README.md describes this as a thirty-second cache, which is not the value in the code.

Making one, and where it lands

Press the backup button (or let a schedule do it) and the panel writes:

<data>/instances/<id>/backups/<tag>-<stamp>.zip          the archive
<data>/instances/<id>/backups/<tag>-<stamp>.zip.meta.json  where copies of it went

The tag is manual for the button and scheduled for a schedule, and the list shows it back to you in plain words from the archive's own contents. A backup refuses to start while the server is running - the log says so in as many words ("would corrupt the world") - so the archive is always taken from a stopped server. The archive is written to a .tmp name and moved into place when complete, so a failed or interrupted backup never leaves a half-archive where a good one used to be.

Every archive carries a small manifest of what it holds (_playport-backup.json: the tag, the creation time, the server, its type and version, the categories and extra paths chosen, and the file and byte counts). That is why the list can say "player data, server settings" instead of making you remember, and why an archive written before the plan existed is reported as everything - because that is exactly what it is.

Retention: what is kept, and what is not

Retention is counted per kind of backup, not per server. That is deliberate: the moment you add an hourly player-data snapshot beside a weekly full archive, one shared limit means the small ones evict the big one - and the thing you were protecting is the thing that goes. Counting by tag keeps both promises. The count is the panel's Backup keep setting (5 by default in this build), and a prune prints each archive it removes into the server's console.

Restoring

Restore writes back exactly the files the archive contains, over the server folder, creating directories as needed - and anything the archive does not contain is left exactly as it is now. The console says which of the two cases you are in before it writes anything ("player data, server settings (files outside the archive are left alone)"), because that distinction is the whole risk:

• restoring a players archive from last night gives you last night's inventories and today's world - it is a rollback of what the archive holds, not of the server;
• restoring an Everything archive is a rollback of the folder;
• a restore is refused while the server is running or starting: stop the server first. The panel says "Stop the server before restoring." rather than fighting a live world;
• the world folder itself is the one part a restore cannot fix afterwards if you replaced it with an older one the players have since moved past - take a fresh backup before a large restore.

Downloading is the safe option when you are unsure: you get the file and nothing touches the server folder.

Backups that leave the machine

A backup sitting on the same disk as the server it protects is the failure mode that catches people, so each server can also copy every archive to one or more destinations as it is written. Destinations themselves are set up in Settings and are admin-only, because they hold credentials and decide where a customer's world ends up.

Details that matter:

• Which servers copy to which destination is per server, and lives with that server's backup plan, so the same checkbox you already use for contents also decides where it goes.
• The local copy is always written first and always kept. A destination is a copy, never the only copy, and the copy is sent before the local prune runs - so a retention sweep on this machine can never be the reason the last copy is gone.
• The same per-tag retention is applied where the copy lives, so an hourly small archive cannot evict the weekly full one on the NAS either.
• Each destination's row keeps the last success and the last failure and the reason, so a destination that has been failing is visible rather than assumed. There is a Test to prove one before you rely on it.
• A failed copy leaves the panel as an alert - it is exactly the event nobody notices until they need the archive (the alert plumbing is chapter 10).
• Credentials are stored in the panel's own settings (settings.json) and are never returned to the browser: you see a hint of the last few characters, not the secret. See chapter 11 for the security model.

Backups on other machines. The tab lists what each destination actually holds - name, size, when, and whether that archive is also on this machine - with per-file Download and Delete. An archive that exists only on a destination can still be downloaded: the panel fetches it back first and then serves it, so a world can be recovered from a bucket through a browser. If you click Download for an archive that is neither here nor reachable, the panel tells you which destinations hold it instead of a bare "not found".

Schedules

Schedules is a per-server list of timers and the actions they fire. Each schedule is one of two shapes:

• every N minutes - it fires when N minutes have passed since it last fired;
• at HH:MM, optionally on chosen weekdays (Sunday = 0 through Saturday = 6).

The actions a schedule can fire are start, stop, restart, backup, command (with the command text) and update. A backup action may carry its own contents selection, which is how "player data and settings nightly, everything weekly" is one server with three schedules. Schedules are stored with the server (instance.json), including the last time each one fired, and the Overview shows the next time each is due.

What actually happens on the clock, precisely, because the difference bites:

• The list is evaluated on the panel's own tick (about every fifteen seconds).
• An interval schedule that came due while the panel was not running fires on the first tick after the panel is back - the "last fired" time is persisted, so a nightly backup missed by a crashed panel still happens when you start it again.
• A clock-time schedule only fires inside its own minute, and cannot fire twice in that minute. So a 04:00 restart missed because the panel was off at 04:00 does not happen at 09:00 when you start it up; it waits for the next matching day.
• Long actions do not block the tick: a stop, restart, backup or update runs in the background and reports into the server's console and the Activity list.

Warning the players first. A restart or stop schedule can carry a warning time in minutes. When it comes due and the server is actually running, the panel announces it over the server's own console at the full wait, again at one minute and again at ten seconds - which is when players finish what they are doing - and then performs the action. A restart at 04:00 with no warning is the single most common complaint about a server; a schedule that wants one asks for it. If the server is not running there is nobody to tell and the action happens at once.

Two behaviours that exist so a cancelled restart cannot surprise you: editing or deleting a schedule inside its warning window cancels the pending action (the console records "Scheduled restart cancelled before it ran."), and a second warning for the same schedule replaces the first rather than queueing two restarts behind each other.

When a schedule fails it is not silent: the action's own outcome lands in the server's console (with the ! prefix for a failure) and, for the long ones, in Activity as a job. Jobs the panel knows how to redo offer Retry; a failed off-machine backup copy raises an alert. The failure of a schedule to fire (a stopped panel, a clock change) is not reported, because "it did not fire on time" has no event to report - which is the honest reason to keep the interval shape for anything you depend on, and to check the Overview's next-run time after a big clock change.

Server start/stop policy is not here. Auto-start on panel launch, auto-restart after a crash, the crash-loop budget and the plain-English crash banner are the server's own settings - see chapter 03 - and a schedule is the timer on top of them.

Storage accounting and alerts

Settings -> Storage answers "where did the disk go" without a file manager, and Settings -> Alerts is what tells you when a line is crossed.

Storage totals the data root - game servers, websites, backups, Java runtimes, the database, SteamCMD - together with the volume's free space and a breakdown of the largest children of a folder, biggest first, plus the loose files at the top level. Per server it shows three numbers, which is the reason the screen exists: the server folder, its archives, and the total - because a server whose world is 30 GB and whose archives add another 60 GB is a backup-retention problem, not a world problem. Measurements are cached for about twenty seconds so opening the screen does not walk tens of thousands of files, there is a Re-measure that throws the cache away, and a pathological tree reports itself as truncated rather than hanging the panel (the walk stops after 400,000 files).

Alerts push a webhook (Discord/Slack-compatible JSON) and/or email when:

• a server crashes;
• auto-restart gives up;
• an off-machine backup copy fails;
• the data volume crosses your threshold.

The same event is held back for a configurable window (ten minutes by default) so a crash loop does not send the same line every few seconds; 0 means tell me every time. With mail in capture mode the messages are readable on the Email page, which is how the wiring can be proved without anything leaving the machine. Alert delivery, mail and the model configuration are chapter 10.

What keeps a server in its box

Two guarantees come from the way the panel starts a server, and both are worth knowing before you point the panel at a game it did not write.

• A memory cap. Each server process is started inside a Windows job object whose per-process memory limit comes from that server's own RAM setting, so one server cannot eat the whole machine and take the co-hosted websites and databases with it. Exceeding it is the OS hard-killing the server, which then looks exactly like a crash - and the crash reader explains it as an out-of-memory limit rather than leaving you with a stack trace.
• Kill on close. Every server lives inside a job whose handle only the panel holds. If the panel dies by any means - a crash, a taskkill /F, the console window being closed - the OS closes that handle and kills every server instantly: no orphaned processes, no RAM leaked, no zombie still holding a port. Child processes inherit the same job, so a launcher that spawns its own children stays covered.

The consequence for a game the panel did not write is that its launcher and its children share one memory budget and one lifetime with the panel. That is the intended trade: a server that outlives the panel is a server nobody is watching, and its port would be taken from the next launch. Stopping a server by hand from the panel gives Minecraft the game's own stop command and waits for the save (StopWaitMs, 40 seconds in this build); everything else gets a short grace period and is then force-stopped. Closing the panel window itself stops every server the same way, gracefully, rather than leaving them running with nothing watching them.

Gotchas worth knowing before they cost you a world

• A backup needs a stopped server. The button and the schedule both refuse while it is running, so schedule your backups for a moment the server is down, or accept that the scheduled one is skipped (the skip is written to the console).
• A restore needs a stopped server, and it writes only the paths the archive holds - plan for "players only" and "everything" to mean very different things.
• A file you edit in the Files tab can be overwritten by a running server's next save.
• Schedules are not serialised against each other. Each due action is dispatched on its own - a stop, restart, backup or update runs in the background while the tick carries on - so two schedules due in the same minute both fire, in whatever order they sit in the server's list. Keep timers apart, and remember that an update refuses while the server is running or starting ("Stop the server before updating.") rather than doing half a job.
• The panel's console buffer is memory; the file beside the server is the durable copy, and it keeps one generation (the .old file).
• Retention is per tag, so "5" means five manual and five scheduled archives, and the same count is applied on every destination.
• A copy that fails is an alert, not a failure of the backup: the local archive is written and kept first, and the copy is what failed. Check the destination's row for the reason before assuming the archive is bad.

Files behind this chapter

Chapter 05. Websites and HTTPS

PlayPort hosts websites on the same machine as your game servers: static files, PHP, or a reverse proxy in front of an application you run yourself. Each site gets its own port, its own folder on disk, its own file manager and - if you want it - its own TLS certificate and a public URL without opening a single router port. This chapter is the app-hosting half of the product; the game-server half is chapter 03, MySQL for these sites is chapter 06, and the mail a PHP site can send is chapter 10.

Two facts decide almost every complaint in this chapter, so they are first:

• A site binds to one port and serves one thing. Static files, PHP, or a forwarded upstream - the type is a property of the site, and changing it restarts that site's listener.
• Sites listen on loopback by default. The panel's setting Website bind defaults to 127.0.0.1 so that hosting costs you no administrator URL ACL - which also means no other device can reach a site until you change it. See Domains, ports and the network path.

What a site is

A site is a record in playport-data/sites.json plus a folder. The record (src/Sites.cs) holds exactly what the panel's pages show:

The managed folder is playport-data/sites/<site-id>/. Importing an existing folder does not copy it: root points the site at the folder where it already is, and PlayPort serves it in place. That is the setting to use for a web app you develop elsewhere.

The site's own page has two tabs - Files and Settings - plus three buttons that matter in this chapter: Preview site (a disabled site, served on a throwaway loopback port so you can look at it before it is public), Open site ↗ (a link to the loopback URL, drawn inert with a reason when the site is switched off), and Diagnose external access.

Creating a site

Websites → + Host a website (or the + New server-style picker on a fresh panel):

1. Name - what the list shows.
2. Type - Static files, PHP (FastCGI) or Reverse proxy.
3. Port - leave it empty and the panel takes the next free site port.
4. Proxy target (upstream) - only for a proxy site, e.g. http://127.0.0.1:9000.
5. Note - free text, shown beside the site.
6. Import an existing folder (optional) - an absolute path. Empty means the site's own managed folder, and for a new static or PHP site the panel writes a small default page there so the site shows something immediately rather than a 404. Filling it in serves that folder instead, untouched.

If the folder you import is an un-built frontend project (it has a package.json, no dist/ or build/), PlayPort starts npm install + npm run build in the background and points the site at the build output - see Building a frontend project.

The site list's row actions are enable/disable and delete; deleting asks separately whether to delete the folder and all files (the Delete the site folder and all files checkbox in the danger zone). Deleting a site does not delete a folder you imported from elsewhere, because the panel never owned it.

Static sites

Static is the default and the simplest. Requests are resolved inside the site's folder (Util.Resolve refuses anything that would leave it), and:

• A directory is served from index.html, index.htm, default.htm or default.html, in that order. A directory with none of them answers 403 Forbidden - directory listing is deliberately disabled, so a missing index is not a file listing of your site.
• A missing path without a file extension is served index.html if the site looks like a client-rendered app - the check is whether the root index.html pulls in a script (type="module" or any <script), cached for 30 seconds. That is what makes deep links and a page refresh work in a React/Vite/Next-static build instead of white-screening.
• A missing path with an extension - a real asset - still answers 404. A typo'd /assets/app.css must not be answered with HTML, because a browser would then report a syntax error in CSS.
• Nothing else is rewritten, cached or compressed by the panel; what is on disk is what the visitor gets.

Import ZIP… in the Files tab unpacks an archive into the site root (1 byte to 512 MB). A single common top-level folder is stripped automatically (dist-2023/ becomes the root), and every entry - files and folders - is checked for containment, so an archive cannot write outside the site.

Building a frontend project

Point a site at a source folder and the panel detects the framework from package.json and builds it. The table it uses is in src/Sites.cs:

The build runs with the Node runtime PlayPort already has: a bundled .runtime/node-*/node.exe next to the exe, then node.exe on PATH. npm install is retried with --legacy-peer-deps when strict peer resolution refuses a tree, and each step has a five-minute timeout. If no Node is found the site is not built and nothing is guessed: the site says it is an un-built source project and names the two ways forward (build it yourself and point the site at the output, or install Node.js). A build that finishes yet finds no index.html in any expected output folder is an error, not a silent "serving nothing".

This builds frontends, not backends. A Django/FastAPI/Go/.NET/Express process is a program you run and put a reverse-proxy site in front of - see Hosting an application you run yourself.

PHP sites

A PHP site is served by the official php-cgi.exe, downloaded by the panel on first use and spoken to directly over FastCGI. There is no IIS, no nginx, no Apache and nothing to configure:

1. Create the site as type PHP (FastCGI). The panel writes an index.php default page.
2. Put files in it (the Files tab, an Import ZIP…, or by serving an existing folder).
3. The first request downloads PHP (~35 MB) and starts the worker: expect that visit to take a moment, after which the page reports the PHP version it is using.

What the panel installs and how it runs, so you can reason about your site:

• The build is read from PHP's own release list at install time (windows.php.net/downloads/releases/) with the newest 8.4.x preferred, and a pinned php-8.4.26-nts-Win32-vs17-x64.zip as the last resort, into playport-data/php/. That is deliberate: a pinned file name goes away when the branch moves on, and a 404 there used to mean "no PHP at all".
• A base php.ini is generated next to it: cgi.force_redirect=0, cgi.fix_pathinfo=1, date.timezone=UTC, extension_dir="ext", openssl, mbstring, memory_limit=256M, max_execution_time=60, max_input_vars=2000, display_errors=1, log_errors=0. A per-site php-<site-id>.ini adds the mail settings (chapter 10) on top.
• One php-cgi.exe per site, listening on a free 127.0.0.1 port in 9100-9400, with the site's folder as its working directory, killed with the panel through a Windows Job Object. The worker's stdout/stderr are drained so they can never fill a pipe and stall a request.
• The first request waits for the port (up to four seconds) rather than running the request twice - a POST that inserts a row must never be executed again because the first attempt raced the worker.
• PHP warnings and errors from stderr are logged to the panel's log for that request, with the tail kept, so display_errors output and the log agree.

An important detail read from the FastCGI environment: SCRIPT_FILENAME is the real absolute path of the script, while DOCUMENT_ROOT is the site's managed folder (playport-data/sites/<id>). For a site serving its own folder the two agree; for a site pointed at an imported folder they do not, and a framework that builds absolute paths from DOCUMENT_ROOT can disagree with the file that ran.

Hosting WordPress or another real app: upload or import it into the site folder, then use the MySQL database panel on the same page for its database (chapter 06) and fill in the app's own configuration as its documentation says. The site serves index.php automatically.

The honest limit. A PHP site runs with the panel's own privileges and open_basedir is not set, so PHP code in one site can read any file the panel can read - including the panel's own data folder. Treat a website you host for somebody else as code you are choosing to trust, or host it on a separate panel. The contained fix (a per-site open_basedir plus upload_tmp_dir and session.save_path inside the site) is written down in the repository's README.md under Honest limitation: hosted PHP is not filesystem-isolated.

Reverse-proxy sites

A Reverse proxy site forwards every request to its Proxy target and returns the answer. This is how a website becomes the public address of an application: the app listens on a local port, the site listens on the site port, and the site does the forwarding.

What it forwards: the method, the path and query, the request body, the User-Agent and Content-Type, and an X-Forwarded-For header (the visitor's address, or an existing one if the request already carried it). It does not follow redirects from the upstream (AllowAutoRedirect = false), it waits up to 60 seconds to connect and up to 120 seconds to read or write, and an upstream that cannot be reached answers 502 Bad Gateway with the target named, which is what a visitor sees while your app is restarting.

What it does not do, and this is worth knowing before you put an app behind it (SiteApp.Proxy in src/Sites.cs): the response the visitor receives keeps the upstream's status code, its body and its Content-Type, and no other response header. Set-Cookie, Location, Cache-Control, CORS headers and the like are not passed back, and the request's Host header is not rewritten. In practice that means an app that keeps a session with a cookie will not keep it through this proxy, and an app that answers 302 will have its redirect turned into a body with no Location. Nothing here rewrites HTML or rewrites URLs. If your app needs those headers, put a real reverse proxy (nginx, Caddy) in front of it, or serve the app as PHP or static output and let PlayPort serve it directly.

Hosting an application you run yourself

The pattern that works today:

1. Add the program under Game Servers as a Manual server (or as any instance type that knows how to start it). It gets a console, a log, a working directory and auto-restart - chapter 03.
2. Note the port it listens on.
3. Create a Reverse proxy site whose target is http://127.0.0.1:<that port>.

Then the website is the front door and the process is managed like everything else in the panel.

About the App behind this website card. A site's Settings page draws a card offering Run this folder as an app, which promises to install, build and run the folder's project as a managed process. Read against this checkout: the panel's own site API (src/Api.cs) implements the actions toggle, files, tls, preview, importzip and diagnose - there is no app action, and no site object carries the appInstance/appKind fields the card reads. So in this tree that button answers unknown action 'app' and the card stays in its "what this could do" state. Use the Manual server plus reverse-proxy pattern above until that route exists.

Domains, ports and the network path

Four things have to line up before a stranger can open http://your-domain/, and they line up in this order:

1. The site's listener must bind an address the network can reach. Site bind defaults to 127.0.0.1 (loopback only). Change it in Settings → Websites - an empty value means all interfaces - and the panel rebinds every enabled site for you. This is the single most common reason "it works on the machine and nowhere else".
2. Windows must let the port through. When the panel runs as administrator it adds an inbound firewall rule itself as each listener binds (Util.EnsureFirewallRule). Without admin rights, add-firewall.ps1 does the same for ports 80, 8080 and 8081 - and only those, so a site on any other port needs its own rule (New-NetFirewallRule), or run the panel elevated once.
3. http.sys must allow the prefix if you bind a site (or the panel) to all interfaces without running as administrator. add-urlacl.ps1 reserves the prefix forms for ports 80, 8080 and 8081 (+, *, 127.0.0.1, localhost, and a LAN IP) for everyone. Two notes before you run it: it is Windows-specific, and the LAN IP inside it is a fixed 192.168.1.225 - edit that line, or add your own address, rather than assuming the script knows your network.
4. Your router must forward the port to this machine's LAN address if the traffic comes from the internet. That is the one step no panel can do for you (and the reason Cloudflare tunnels exist - see Public access without opening ports).

Sites do not need a URL ACL for HTTPS. HTTPS is served by the panel's own raw socket server (TlsHost in src/Tls.cs), not by http.sys, so it works on any port with any certificate and needs no administrator reservation - which is why a tlsPort of 8443 is a perfectly normal thing to use.

Diagnose external access answers this chain for you instead of leaving you to guess. It reports the site's status and message, the detected LAN address, the machine's public IP (looked up live), the current Site bind, and a list of concrete hints: the site is not running, the port is shadowed by another program's HTTP reservation, the bind is loopback-only, another site owns that HTTPS port, the firewall has no rule for the port, and what to forward on the router or which tunnel to use instead.

Port collisions you should know about

• A shadowed port looks like success. If another program holds an http.sys reservation for a port, a site can bind it and every visitor still gets a 503 from Windows before the site is reached. The panel probes for this after binding and reports it with the fix (netsh http delete urlacl url=http://+:<port>/, as administrator), so the site says reserved on this machine by other software rather than "running".
• One site per HTTPS port. Two sites cannot share a tlsPort; the second reports the collision with the fix (give one of them a different port).
• Every site needs its own HTTP port as well. A collision there is a bind error, named in the site's message.

HTTPS

Everything about TLS is on the site's Settings page, in one panel, because a certificate is only useful when HTTPS is switched on with it.

1. Domain (TLS / PHP) - the name the certificate is for, e.g. example.com. Let's Encrypt needs this; a self-signed certificate will fall back to localhost if you leave it out.
2. HTTPS (also serves TLS) - tick it, and set HTTPS port (default 443). The site keeps serving HTTP as well; both listeners run at once.
3. Pick one of the four buttons:

The certificate card above the buttons shows the domain, whether the certificate is installed (or that the key is missing), its expiry date and its issuer.

Automatic renewal applies to Let's Encrypt certificates only, and that is a deliberate rule: a self-signed or uploaded certificate is never replaced behind your back. With Renew automatically on, the panel renews inside the renew when this many days remain window (30 by default, capped at 60), never more often than once every six hours, and writes what it is doing to Last status - including the honest reason it is waiting (HTTP-01 requires this site's HTTP port to be 80) when the site is not on port 80. Every attempt, success and failure is logged.

Where the certificate lives: playport-data/sites/<site-id>/ssl/ - cert.der and privkey.xml for the panel to load, fullchain.pem as the real chain Let's Encrypt returned, meta.json with the issuer, the domain and the expiry. The Let's Encrypt account key is playport-data/acme/account.json; if that file cannot be read, the panel keeps a copy aside and says so rather than silently registering a new account (Let's Encrypt counts accounts per address).

Getting a LetsEncrypt certificate needs the CA to reach port 80 on the domain - which means the site's HTTP listener has to be the one answering on 80, on a machine the internet can reach, before you press the button.

Public access without opening ports

Tunnels put a site on the internet without forwarding anything, because everything in PlayPort already listens locally.

Install it once: Settings → Cloudflare tunnels → Install cloudflared. The panel downloads the official Windows binary (cloudflared-windows-amd64.exe, about 60 MB, from Cloudflare's own GitHub release) into playport-data/cloudflared/. The site's card offers the same install button when it is missing.

Quick tunnel (per site): on the site's Public access - Cloudflare tunnel card, start the tunnel. Within seconds the card shows a live https://<random>.trycloudflare.com address. It needs no account, no DNS and no open port - and it is temporary: anyone with the URL can reach the site until you stop the tunnel or close the panel, the hostname changes every time you start it, and the panel kills every quick tunnel when it exits.

Named tunnel (stable hostnames): Settings → Cloudflare tunnels → Generate named-tunnel config writes playport-data/cloudflared/config.yml routing every enabled site that has a domain to its local port, with a commented-out entry for the panel itself. The one-time setup is on you, in a terminal, and the generated file repeats it verbatim:

cloudflared.exe tunnel login
cloudflared.exe tunnel create playport
cloudflared.exe tunnel route dns playport <domain>     # once per domain
cloudflared.exe tunnel --config config.yml run playport

The other tunnel is playit.gg, which fronts raw TCP and UDP - what a game port needs rather than a website - and it is documented in chapter 09. If you want the panel itself reachable from outside, both tunnels can publish the panel's own port; put something in front of it, because its login is not a firewall.

Where a site's data lives

Backups of a site are part of the backup system described in chapter 04: the Files tab is the same file manager as a game server's, and a site's folder can be backed up, zipped and copied off the machine the same way.

When a site does not answer

The app-hosting API, in one table

Everything the pages do is an API call, so a script can do it too. Authentication and the full route reference are chapter 11; these are the site routes (src/Api.cs):

Files behind this chapter

Chapter 06. Databases

PlayPort runs one managed MariaDB 11.4 server (MySQL-compatible) for the whole machine, and hands out one isolated database + user to any website or game server that needs one. This chapter covers installing and starting that server, creating a database, giving its credentials to a site or a game server, where the credentials live, what backups do and do not cover, and every failure the panel knows how to explain.

If you only want the core plugin to keep its player records in SQL, you do not need most of this: that is one button on Plugins → PlayPort Core → Use a database, and it is described under giving a game server a database. Nothing else in this chapter is required for it.

The ports and the data-root layout this chapter refers to are summarised in the manual's appendices; the other chapters are linked where a topic crosses over.

What the panel runs

• One MariaDB for the whole panel, not one per site. It is global: every website and every game server shares the server process, and each of them gets its own database and its own user inside it.
• A portable zip, not an installer. The panel downloads ~90 MB from archive.mariadb.org and unpacks it into the panel's data folder. No Windows service, no registry entry, no administrator rights. The paths (from Db.cs) are:

• It listens on loopback only. It is started as mariadbd --datadir=… --port=3306 --bind-address=127.0.0.1 --console --skip-networking=0, so nothing outside this machine can reach it, by design - databases here are for the sites and servers on this machine. The panel's own Server readiness report deliberately asks for no firewall rule for it, which is how it stays private.
• It is sandboxed like a game server: a 1 GB memory cap, and it dies when the panel dies.
• Its state is always a pair - a state (stopped, starting, running, installing, error) and the sentence explaining it are written together, so a failure sentence is never shown beside a state it does not belong to.

Where you meet it in the panel:

Installing and starting it

1. Settings → Components → the MariaDB row → Install. This is a background job ("Install MariaDB" on the Activity page), so the button returns immediately; the panel re-reads the state until the server is up.
2. If you are on a site's or a server's own database panel and there is no server yet, an admin gets the same button there - the panel does not send you to another page to start a download.
3. Press Start (or install, which starts it) and the dashboard's Database row turns green: "MariaDB is running on port 3306."
4. Stop is on the same row. The panel also stops it cleanly on shutdown (a SHUTDOWN command first, then a kill if it does not go), so a normal exit does not corrupt a data folder.

The install does three things in order: download and unpack the zip, run mariadb-install-db.exe --datadir=… to create the data folder, then (on the first start, because it cannot be changed while the server is down) generate a random root password, set it, and write it to databases.json. That root password is the panel's own; you should not need it, and it is a secret (see where the credentials live).

The port is 3306 and comes from the panel's own record (databases.json), not from a settings field: there is no supported way to move MariaDB to another port in this panel. If something else already holds 3306, read that failure below - the panel tells the two cases apart.

Creating a database and its user

From a site's page or a server's page (or POST /api/db/issue, which is what both panels call):

1. Open the site or server and find the MySQL database panel (a server's is titled MySQL database (manual) and says which case it is for).
2. Press Create database. The panel runs, in one transaction against MariaDB:

   CREATE DATABASE IF NOT EXISTS `<name>` CHARACTER SET utf8mb4;
   CREATE USER IF NOT EXISTS '<name>'@'localhost' IDENTIFIED BY '<random>';
   CREATE USER IF NOT EXISTS '<name>'@'%'         IDENTIFIED BY '<random>';
   GRANT ALL PRIVILEGES ON `<name>`.* TO '<name>'@'localhost';
   GRANT ALL PRIVILEGES ON `<name>`.* TO '<name>'@'%';
   FLUSH PRIVILEGES;

1. The credentials appear in the panel: host 127.0.0.1, port 3306, user, pass. They stay visible on that page afterwards (the panel stores them), so you can come back for them.

The naming is not arbitrary - it comes from Db.cs:

• a site's database is wp_<slug>_<4 hex>, a game server's is gs_<slug>_<4 hex>, where the slug is the resource's name with everything but letters and digits removed, cut to 40 characters before the random tail is appended;
• the user is named exactly like the database - there is no separate user name to remember;
• the password is pp- followed by 16 random hex characters.

What the user may do. GRANT ALL - but only on its own database. It cannot read another database, cannot create or drop databases, and cannot touch MariaDB's own tables. That is the whole point of the design: "Creates an isolated database + user with access to that database only - safe to hand the credentials to a client" (the panel's own words on the create button).

Who may do it. Admins and moderators can create a database for any site or server. A normal user can only do it for a site or a game server they own; the API answers Not your site. / Not your instance. otherwise. Dropping follows the same rule (an admin, or the owner of that database).

A press creates exactly one database. A server may legitimately have more than one - one per plugin or tool that wants its own - and each is listed on that resource's panel with its own Delete button.

Where the credentials live (and what that means)

Everything is in one file: playport-data/databases.json.

{ "rootPass": "pp-…", "port": 3306,
  "issued": { "<resource id>": [ { "db": "gs_hub_1a2b", "user": "gs_hub_1a2b",
                                   "pass": "pp-…", "port": 3306, "kind": "instance",
                                   "resource": "<instance id>", "owner": "<user id>" } ] } }

Three things follow, and they matter more than the JSON does:

1. This file is the only place a database's password exists. The panel shows a password when it creates it and stores it here; MariaDB keeps only a hash. If the file is lost and you have no backup of it, the credentials cannot be recovered - the panel says so in as many words when it cannot read the file: "PlayPort started without its record of the databases it handed out and of the MariaDB root password it uses." Include it in whatever you back the panel up with.
2. The panel repairs credentials rather than duplicating them. Linking the same server again, or restoring an older databases.json, does not mint a second database: the panel re-issues that user, its password and its grants, and then proves the credentials log in (SELECT 1 as that user) before it writes anything. The data is never touched - it is an account operation on a database that already exists.
3. Any panel login is close to full access to every database on the machine. The status the panel's own Databases page reads includes the MariaDB root password, because that is how the panel reconnects to it. Treat databases.json as a secret file, and treat panel accounts accordingly (see chapter 11 for the security model and roles).

Giving a website a database

1. Open the site, scroll to MySQL database, press Create database.
2. Copy the host, port, user and pass into the site's own configuration - the panel says it plainly: "Use these in your site config (e.g. WordPress wp-config.php) or the game server's database plugin."
3. The panel does not edit the site's files. There is no automatic wp-config.php writer; a PHP or static site finds its credentials wherever its own installer put them. If you install WordPress, the installer asks for exactly these four values.
4. If you own the site, you see its databases. An admin sees every database on the machine under Settings → Databases.

Sites and mail both live on this machine and talk to MariaDB over loopback, so nothing has to be opened in the firewall for a site to use its database. Website hosting itself is chapter 05.

Giving a game server a database

There are two different questions here, and the panel keeps them apart on purpose:

1. A database for the PlayPort core plugin (the common case, and the only one that needs no copying). On the server's page: Plugins → PlayPort Core → Use a database. That one button:

• creates the server's own database and user (the same provisioning as above, with the gs_ name);
• downloads MariaDB's JDBC driver once into the panel's data folder and copies it into plugins/PlayPortCore/lib/mariadb-java-client-3.5.1.jar on that server;
• writes the credentials into the plugin's own link file, plugins/PlayPortCore/db-link.txt - not into config.yml, which the panel never writes. The plugin reads the link file last, so a panel-written credential wins over anything typed by hand; delete the file, or press Unlink, and the plugin goes back to its own files exactly as before;
• proves the credentials log in before writing the link file, because a link file that does not work is worse than none: the plugin would report a database and quietly fall back to files;
• creates at most two databases per server, each reused rather than duplicated - the server's own, and its network's when some records are shared. Sharing is per group of records (money, playtime, hearts, rank, combat, claims, identity, plus each module's own declared data), so a balance can be the same on every server while hearts stay on the one that took them.

What the plugin then does with those tables - and the /playport sql commands that report the routing it is actually running under - is chapter 08; the panel side of it is chapter 07.

This route needs a server the core plugin can run on at all: a Bukkit-family server (Paper, Purpur, Spigot) with the plugin installed. Otherwise the panel says why instead of offering the button - "The PlayPort core plugin only runs on a Bukkit-family server (Paper, Purpur, Spigot)." or "This server does not have the PlayPort core plugin installed yet."

2. A database for a different plugin or an external tool. The server page's MySQL database (manual) panel does only that: it hands you credentials to paste wherever they belong. The panel's hint says exactly this when you are there, and a database created that way is reused by the core plugin's button later rather than duplicated - both are keyed to that server.

Seeing what exists, and dropping a database

• Settings → Databases (admin) lists every database the panel issued: name, the resource it belongs to, user, host and port, with a Drop button per row. A stat bar above the list shows the count and the server's state and port.
• A site's or a server's panel lists only that resource's databases, with a Delete per database.
• Both actions confirm first, in the buyer's terms: "Delete <db> and its user? A website or plugin using it will stop working until it is recreated." and "The database and its user are deleted permanently. All data in it is lost." A drop is DROP DATABASE plus DROP USER for both the localhost and the % account, then the record is removed from databases.json.
• Search (Ctrl+K) finds databases by name, alongside servers and sites.
• Storage accounts for the whole mariadb/ folder under database, so "where did my disk go" has an answer that includes the databases.

For scripts, the routes behind these screens are GET /api/db (status: installed, state, message, port, how many databases), POST /api/db with {"op":"install"|"start"|"stop"} (admin only; install returns at once and runs as a named job), GET /api/db/all (admin), GET /api/db/owner/<ownerId>, POST /api/db/issue with {"kind":"site"|"instance","id":…,"name":…} and DELETE /api/db/<database>. Chapter 11 has the full API reference, including what each one requires.

Backups and restore

This is the part most often assumed wrongly, so it is stated plainly:

• The panel's backup feature does not dump MariaDB. A server backup contains that server's files - world, configs, plugins folder - and a site backup contains that site's folder. Neither archive contains a database. Restoring a backup therefore restores files, not tables.
• databases.json is not inside those backups either. If you back the panel's data folder up yourself (a file-level copy, or the machine's own backup), both the dumps and that file are covered.
• To keep a database, dump it. The MariaDB package the panel installed carries MariaDB's own client programs, so no extra download is needed - the dump program sits beside them:

  playport-data/mariadb/mariadb-11.4.5-winx64/bin/mariadb-dump.exe \
      --host=127.0.0.1 --port=3306 -u <user> -p<pass> <database> > <database>.sql

(MariaDB 11 ships that program under the name mariadb-dump.exe; it is the tool MySQL calls mysqldump. Check the bin folder for the exact name in your copy.) Restoring is the mirror image with mysql.exe.

• Off-machine copies of a dump go wherever your backup destinations point - chapter 04 covers destinations if you want the dump to leave the machine.
• If you delete the panel's data folder you delete the databases with it: MariaDB's data lives inside playport-data/mariadb/data/.

When something goes wrong

Every sentence below is one the panel itself writes - they are the texts to match a screen against.

Install failures (Util.PlainDbError, chosen by which class of fault it was):

Start failures:

• "MariaDB started but stopped straight away." Another program may already be using port 3306, or the data folder is damaged or belongs to a different MariaDB version. The panel's log has the server's own message; try Start again, and if it keeps stopping, restore the mariadb folder from a backup.
• "MariaDB did not answer within a minute of starting." Normal on a slow disk or a first run - press Start again.
• "MariaDB is installed but not running" (the dashboard's Database row, marked as a failure) with "Start it from the Databases page." - the server is fine, it is just stopped.

When the port is already taken. The panel asks the port before it starts anything, and the answer decides what you are told:

• If whatever is there accepts the panel's root password, the panel adopts it and logs "MariaDB was already running on 127.0.0.1:3306 - using it." Nothing else is required; this is what a MariaDB left behind by a killed session looks like, and it means the databases are still yours.
• If it refuses the password, you get the honest sentence: "something is already listening on port 3306 but it refused the panel's root password, so no database can be created in it. That is what a databases.json from another data root (or a missing one) looks like. Stop that MariaDB, or start this panel against the data root that owns it; to reuse it, reset its root password once (start it with --skip-grant-tables and ALTER USER 'root'@'localhost' IDENTIFIED BY '<new>' once)."
• If the server there is not the panel's at all, that is the same answer - and the fix is the same three choices. Do not start a second MariaDB on the same port and read "mariadbd exited during startup" as the diagnosis; it named the wrong process, which is exactly why the panel stopped saying it.

A forgotten root password. It is in playport-data/databases.json (rootPass). If the file is gone, reset it once as described above with --skip-grant-tables.

A database that grows past the disk. Its bytes are inside playport-data/mariadb/data/, counted by Storage; the panel's disk alerts fire on the drive, not per database. Dump what you need and prune, or move the whole panel data root to a bigger drive (see chapter 01 for --data).

Connecting from another machine. You cannot, and that is deliberate: the panel starts MariaDB bound to 127.0.0.1 and there is no setting that changes it, because these databases exist for the sites and servers on this machine. If you need SQL from elsewhere, run your own database server for that. If you need to look inside these, use MariaDB's client programs on this machine - a client started from inside the panel's own folder can also create and inspect tables directly.

Files behind this chapter

Chapter 07. The core plugin, from the panel

The core plugin is one jar - PlayPortCore - that is a survival server, a hub, a prison or a lifesteal SMP depending on which template profile it is given. It is not downloaded from anywhere: the panel carries it inside the exe, and the Plugins tab of any Paper-family server can install it in one press. This chapter is the panel half of that story - installing it, updating it, the settings form, the profile picker, and the eighteen editor surfaces that write core content. What the modules do in game, their commands, their config.yml and their permissions are chapter 08; the module list itself is Appendix D.

The jar the panel already has

There is nothing to fetch and nothing to upload. The exe embeds the built jar under the fixed resource name playport-core.jar, so the panel never has to know the plugin's version to find it. Two details matter to an operator:

• A loose playport-core.jar next to PlayPort.exe wins over the embedded copy. That is deliberate - it is how a development build tries a new jar without recompiling the panel - and it is also the reason a server can pick up a plugin the panel does not think it is shipping. If you drop a file there, remember it is what every install will use.
• The version comes from the jar's own plugin.yml, not from its file name and not from a constant in the panel. One source of truth, so the panel cannot report a version the plugin disagrees with. This is why the card on the Plugins tab can say v1.0.0 and mean it.

A build made from a checkout that has never run build-plugin.sh has no jar inside it. The panel says so in one sentence - This build of PlayPort has no core plugin inside it - and tells you to run build-plugin.sh and rebuild the panel, or drop playport-core.jar next to the exe. Nothing else breaks; the rest of the product does not need the plugin.

Installing it into a server

1. Open the server and choose the Plugins tab.
2. Find the PlayPort Core card. It is drawn as a card rather than a search result, tagged included, because there is nothing to search for and nothing to download.
3. If the build ships template profiles, the card carries a profile picker beside the button - the template this server should run (see below). Leave it alone to accept the server's own answer.
4. Press Install (on a server that already has it, the same button reads Apply).
5. Restart the server. The install writes the jar and the link files; a running server loads a plugin only at start, so the card and the console both say Restart the server to load the core plugin.

What the install needs: a server that loads plugins. The card refuses a server that cannot with the reason rather than failing silently - Vanilla loads neither plugins nor mods (Create a Paper or Purpur server for plugins), a NanoLimbo lobby loads nothing at all, and a Fabric/Forge/NeoForge server takes mods, so the core plugin - a Bukkit plugin - is refused there. A manual/process server gets a sentence saying the panel does not know what runs inside it. The install is POST /api/instances/<id>/core, and the card's state is GET on the same route; the panel is the only caller.

Three rules the installer keeps, because getting them wrong is how a plugin update eats somebody's work:

• The jar is versioned (playport-core-<version>.jar) and older jars of ours are removed on install. The name pattern is ours, so a plugin of somebody else's with a similar name is never touched.
• A profile file that already exists is never overwritten. An operator who edited profile-survival.yml keeps that edit across an update; deleting the file is how you ask for the shipped copy back, and the plugin rewrites it on the next start.
• config.yml inside the plugin's folder is never written by the panel. The profile the panel chose goes into pack.txt, and the plugin reads that only when config.yml does not name a profile itself - so a hand edit always wins.

Which template a server runs

A template is a configuration of the one jar, not a list of downloads, and that is the whole design: pkg/profiles/*.yml are the shipped templates the panel installs from. The profile in effect is resolved in this order, and the order is the point - the operator's intent beats the pack's implication:

1. what was picked for this server (its stored CoreProfile),
2. otherwise what the pack it was created from implies - a pack is core-<profile> and its only item is the bundled jar, so a prison pack lands on the prison template without anyone choosing it twice,
3. otherwise nothing, and the plugin runs on its own defaults. That is the honest answer rather than a guess, and the log says it in those words: no template profile, so the plugin runs on its own defaults (name this server after a gamemode, or pick one, to give it a template).

Servers made before templates existed resolve through the older paper-* pack ids, and a name like Survival Hub still resolves to the hub template, so the template is refused while nothing has been built yet rather than leaving half a network behind.

The profile picker writes through the same install path: choosing a template and pressing Apply re-installs the jar with that profile, and an empty choice means "what this server's template would choose".

Updating it

There is no separate updater, and there does not need to be. The card always shows the version the panel is shipping, and when the copy installed on that server is a different version it adds a tag reading this server has <version> - which is what "an update is available" looks like here. Press Install/Apply on that card and:

• the new jar is written as playport-core-<newversion>.jar,
• the older playport-core-*.jar files are removed,
• the jar's SHA-1 is compared first, so pressing it when the server is already current logs already installed and up to date and changes nothing,
• an existing profile file is left exactly as it is,
• the server must be restarted to load the new jar. A running server gets the file on disk and keeps running the one it started with, which is why every note says Restart.

Updating the panel is what changes the shipped jar: a new PlayPort.exe carries the core plugin its build produced, and every server then reports the older version until it is updated - see chapter 01 for getting a new panel in place.

The link between the panel and the plugin

The card can only tell you what the server says, and the server only says it if the two are linked. The link is written by the install and it works in both directions:

Both files are deliberately plain text - key=value for settings, JSON for the report - and every failure in the link is soft. No panel, no token file, a refused connection, a malformed line: the plugin runs exactly as it did before, because none of it is load-bearing for the game server. The only trace is a line in the console and a panel: section in /playport status.

That softness has one visible consequence, and it is the sentence you will see most often in this chapter: a card that has nothing to show says so instead of showing an empty form. Before a server has ever reported, the settings button and the whole editor row are present but inert, each with its own reason - PlayPort Core has not reported to this panel yet, so there is nothing to read. Start the server once (or give it a minute if it is already running) and this opens.

The settings surface

Settings on the editor row is the plugin's own catalogue, not a panel-invented list. The form is built from the keys the plugin reported, so a setting added or renamed in the plugin turns up in the form without the panel being touched, and a setting the panel has never heard of cannot appear as a dead field. Saving it writes the overlay panel-settings.txt, and the plugin applies it live - which is why a change here does not need a restart, while a change made by hand in config.yml takes effect on the plugin's own reload or the next start.

Two kinds of switch live in that catalogue, and both are worth knowing by name because every module page in chapter 08 refers to them:

• modules.<id>.enabled - whether the module runs at all on this server. A module that is off claims no commands, loads no content and appears in /playport status as off. This is the switch the panel names in an inert editor's reason (Turn on modules.jobs.enabled and restart the server).
• modules.<id>.features.<flag> - the per-feature switches inside a module, for the parts of a module that exist precisely so it can share a server with a dedicated plugin. pkg/PARITY.md states the rule the other way round: there is no "out of scope" in this core, so the answer to "this server does not want it" is a switch, not an absence.

If the form is empty on a server that has reported, the card says what to do rather than leaving you to guess: run /playport check in the console, which names anything the plugin could not read. The same command is the authority on plugin-side config problems - see chapter 08.

The editor row

Everything that writes core content is on one row of the card, and the rule that draws it is worth stating because it is what makes the row trustworthy:

On a server with the plugin installed the row is always drawn, every editor is on it, and an editor the server cannot serve is inert - present, greyed, and saying why when it is pressed.

That replaced a row of eighteen "show this button if" ternaries, where this server is not running that module and this panel cannot do that were the same picture. The reason an inert button gives names the switch: The jobs module is off on this server and nothing is loaded in it, so there is nothing to edit here. Turn on modules.jobs.enabled and restart the server.

Every editor opens from the same payload - the plugin's report plus the installed-file list - and every one of them writes a file the plugin merges with its own config within a minute. None of them invents a format: what is written is the same shape config.yml holds, so a record made in the browser and one typed into the file are the same thing to the server, and the in-game commands cannot tell which of the two they are reading.

Four notes on that table, each of which changes what you can expect:

• Two editors are deliberately not editors. Worlds cannot be one: a world's terrain is fixed the moment it exists, so the page draws what a world is (its preset, the seed it was made from, whether it is loaded, what the generator answers at 0,0) and lets you ask for new ones. Asking is add-only: deleting a row stops asking and never deletes a world - that is /dimensions regen <world> confirm, in game. Seeds are handled as text everywhere on that page, because a 64-bit seed read through a JSON number becomes a different seed. LuckPerms is the same idea: it shows what the module found rather than editing the permissions plugin's own files.
• Dungeons lists blueprints and cannot invent one. A blueprint is a region of a world, made with the wand in game; the page shows what is on disk (size, blocks, what it carries) so one can be picked for a dungeon.
• A theme's pools stay in the file. The dungeons page edits a theme's scalars and says where the room pools live, because a pool is a list of lists and that is a file's job.
• Fishing is the one button in this build whose content file is not named in the plugin's own vocabulary (pkg/src/ppcore/ConfigVocab.java names a panel-*.yml for every other editor and no panel-fishing.* file), so what it edits travels with the settings overlay rather than with a content file of its own.

Save as profile… is the other direction of the profile picker and sits beside it. It asks the plugin to write this server's currently merged settings out as profile-<name>.yml - which is why the button is inert until the plugin has reported: a profile is the merged, layered config, and that exists only inside the running server. The card then reads the last export back from the server (the file it wrote, how many settings it carried, how much library content it deliberately left out, and, when it was refused, the sentence saying why), so a page reopened tomorrow says the same thing.

Player records: files or a database

Under the core card is a Player records card that answers two questions that look like one. A file or a database is one press. Which records does the whole network share is asked once per group of records, because one answer for a whole server cannot be right: a balance wants to be the same everywhere a player plays, a rank belongs to the ladder that gave it out, and lifesteal hearts belong to the world that took them. The seven groups are money, playtime, hearts, rank, combat, claims and identity, and the module list beside them comes from the plugin's own report (panel-sql.txt), never from a list in the panel - so a module that declares a new group of data shows up the next time its server loads.

A server with no database reads as one sentence about a file, which is the whole truth about it: The plugin's own players.yml - nothing here is shared with another server. Nothing a module keeps for itself is on this list at all: islands, plots, chests and arenas are per-server files, and no switch here reaches them. The database itself is chapter 06.

Packs: the plugin install plus the settings a fresh server needs

Installing the jar is only half of "plug and play", and the panel's starter packs are the other half. A pack (src/Starters.cs) is a named set of items whose one plugin item is playport-core, plus the non-download half in src/Presets.cs:

• server.properties is tuned, but never over an operator's choice. A property is only changed while it still holds the value Minecraft ships (or the value the panel wrote at creation), and every change is logged with what it was before (view-distance 10 -> 8). Anything already moved stays moved, and the console says so.
• Vanilla gamerules are run once, on the first successful start. They are queued at install (/gamerule playersSleepingPercentage 50 and the like), sent by the console pump the first time the server prints its readiness line, and never again - not even across a panel restart. Every one is a vanilla command with a documented name; nothing here guesses at a plugin's own syntax.
• Plugin config files are deliberately not written. Several of the plugins in those packs generate their own config at first run, so a hand-written one would be invented keys with a real chance of being wrong. The honest version is the note on the pack card, which says what still needs a human.

The same install also writes panel-worlds.yml when the server was created with worlds it should own, so the plugin makes them at first start rather than the panel guessing. The pack's note on the Plugins tab is where the remaining human steps are listed; read it before you hand the server to players.

What goes wrong

Files behind this chapter

Chapter 08. The core plugin, in game

This chapter is the core plugin as an operator meets it inside a running server: what it is, how its modules are switched and configured, the commands you type, the permissions it wants, what <command> check actually proves, and what it writes into the server's folder. Installing and updating the jar, and the panel's own Plugins tab, are chapter 07.

Read ../MANUAL.md first if you have not: it has the conventions this manual uses and Appendix D, which is the registry of every module id and label the plugin reports. This chapter deliberately does not repeat that table.

What it is, and the three rules it is built on

PlayPortCore is one Paper/Spigot plugin jar. It is the in-game half of PlayPort: economy, permissions and groups, ranks, homes and warps and kits, claims, mines, PvP hearts, a shop, an auction house, quests, jobs, dungeons, spawners, custom items and enchantments, cosmetics, teams, factions, minigames, and about a hundred other things - see Appendix D.

A template is a configuration of this one jar rather than a list of downloads. The panel drops the jar into plugins/ and writes a profile beside its config, and the same jar becomes a survival server, a prison, a lifesteal SMP or a hub.

Three rules hold everywhere in it, and they are worth knowing before you promise anything to players:

• Nothing in it can be bought. Money is earned by playing (time, and selling what you gather), ranks are earned by playing and are a permission set rather than a product, hearts change hands only when one player kills another, and claim blocks accrue from time online. There is no store hook and no purchase command anywhere in the jar. /playport fair prints this policy in game, in the plugin's own words, which is also a good line to give a player who asks.
• It does not fight the other plugins on your server. Every module, every feature and every command name is configurable, and a module stands down by itself when a plugin that already does that job is installed - see Hooks and the plugins beside you.
• It does not phone home. Nothing in it checks for a newer version of itself, submits statistics or usage data, or talks to a server you did not configure. The panel is what installs, updates and reports on a server. The one outbound call in the whole plugin is the stream module's live check, and it is configured per channel.
• A store plugin beside it gets a warning, not a ban. If BuycraftX, Tebex, Votifier, NuVoter or TokenManager is installed, the boot prints one line saying that selling ranks, hearts, claim blocks or money would break the fair-play promise of every template built on this jar. Nothing is blocked - it is your machine - but the mismatch is never silent.

The module model, in operator terms

Everything the plugin does lives in a module. A module owns:

• its commands (registered when it starts, named from your config);
• its config section (its id is the section name - shop:, arena:, jobs: ...);
• its own data in the server's plugins/PlayPortCore/ folder, if it keeps any;
• its switch, modules.<id>.enabled.

The single most important consequence: a module that is off claims nothing at all. Its commands do not exist for players, its listeners are not registered, its timers do not run, and it reads nothing. That is deliberate - it is what lets you run this jar beside EssentialsX, CMI or LuckPerms and take only the pieces you want - and it is also why a switched-off module can look like a deleted one. The plugin says so when it can: a module whose file still holds work a player would miss prints a line at boot naming the file and the count, because from inside the game "off" and "gone" look identical.

/playport status is the screen for this. It prints the template profile in effect, then one line per module, then every command currently registered. The same summary goes into the console at boot, with the panel link and the fair-play line (server.banner, default true), and debugConfig: true adds a line listing every module's switch - which is the quickest way to see what a template left on. The three states a module can be in are, in the plugin's own words:

The registry is generated from the source, not kept by hand. The ids and labels /playport status prints are read off each module's own source by a tool the plugin build runs before it compiles, so a module cannot be missing from the list while its code is in the jar. A module that runs without being in that table logs a warning naming it and telling you to regenerate the table - which is a build problem rather than something you can fix from the server console.

The commands you will actually type

/playport (aliases /pp and /core) is the platform's own command. It is registered with no permission of its own; each verb checks what it needs, so a player can type it and get a refusal rather than "unknown command".

Server operators also get /dimensions (alias /dims): the worlds this plugin owns, adopting one, and regenerating one. It needs ppcore.dimensions.admin.

Three things worth knowing before you use them. save and reload both touch every module's own files at once, and save uses each module's flush half rather than its teardown half - saving does not cancel a running fight, dismiss pets or drop anybody's permissions. And the importer has a dry run on purpose: /playport import <plugin> reports what it would carry, the confirm word is what writes it, import.enabled (default true) is the switch, and it never overwrites a value you set in config.yml - the report names the paths it skipped for that reason.

How commands appear (and why nothing is declared in the plugin's descriptor)

The plugin declares no commands in its plugin.yml on purpose. A command declared there is claimed by the server even when the module that owns it is switched off, which is exactly the interference this plugin is built to avoid. Commands are registered at runtime instead, and a disabled module registers nothing.

What that gives you, from config.yml:

Three behaviours worth expecting:

• Permissions are checked by the plugin, not by the server's command map. That is deliberate: a server that gates a command strips it from the list it sends the client, so a player without the node is told the command does not exist. Here every command stays visible and the refusal is the truth: You do not have permission to use /<command>.
• A name the server itself owns may be taken over, and only the ones a takeover genuinely replaces. With interop.takeOverBuiltInCommands: true (the default) /msg, /me, /time, /weather, /gamemode, /list and /enchant become this plugin's when the owning module is on. Where the built-in is richer in ways staff rely on - /give, /clear, /kill, /tp - the short name is left alone and ours stays reachable as playport:<name>. Every takeover is printed to the console at startup, so the list is a reading rather than a guess.
• A name another plugin holds is never taken. Yours stays reachable as playport:<name>, and the console says who owns the short name, what each of your aliases resolved to, and what the module is reachable as. /playport help follows the same rule: it only ever names a command a player can actually type, so the help cannot send someone to another plugin's command.

/playport help is built from the registration itself, not from a written list, which is why a switched-off module cannot appear in it. It names those modules at the end instead - "no such command" and "somebody turned that off" are different answers, and only one of them is worth a support ticket.

Permissions and groups

Every command carries a permission node of the shape ppcore.<module>.<verb> - ppcore.ah.use, ppcore.ah.sell, ppcore.ah.admin, ppcore.arena.spawnboss, ppcore.staff.teleport, ppcore.jobs.use, ppcore.ui.admin and so on. The platform's own nodes are:

The plugin's perms module can be your permission system: it owns groups, their nodes and the default group, and the earned-rank ladder drives group membership. If you would rather keep the permission plugin you already run, two things happen by themselves: perms stands down when LuckPerms, PermissionsEx, GroupManager or CMI is installed, and the hooks layer keeps answering questions through Vault's permission service when it is there.

config.yml: what it is, and which layer wins

The plugin writes plugins/PlayPortCore/config.yml on first start; it is a complete copy of the shipped defaults, heavily commented. The plugin never rewrites it, so your edits survive every upgrade and a re-applied template cannot overwrite them by accident.

Four layers are in play, highest first:

1. What you edit in the panel's Plugins tab. These are applied to the running server within a minute, and /playport panel lists exactly which settings came from the panel.
2. Your edit in config.yml. Because the file starts as the shipped defaults, "an edit" means a value that differs from the shipped default - a line you never touched does not block the profile below it.
3. profile-<name>.yml, selected by the profile: key. This is what a template installs.
4. The plugin's built-in defaults.

Set profile: "" to run on config.yml alone, or use /playport profile off for the same thing at runtime. Delete config.yml and any profile-<name>.yml and restart to get the shipped file back.

The file's shape, in the order an operator usually meets it:

A key the plugin does not read is not harmless, and that is the subject of the next section.

<command> check, and /playport check

This is the feature that keeps a config honest, and it is the one to run after every edit.

Every module's command answers <command> check - /shop check, /arena check, /plot check, /f check. The report is answered for every module in one place, so no module can quietly lack it. A clean answer names what was looked at:

[PlayPort] ess: config checks out - 12 kit(s), 4 warp(s).

A finding is a setting that would do nothing, which is the most expensive kind of wrong a config file can be, and it comes in two halves:

• values the module knows are wrong - a material, sound, entity or world this server does not have; a number outside the range the code can use; and the percent/fraction mix-up it names specifically (0.45 where 45 belongs, which reads in game as "my feature never fires").
• keys in the module's section that nothing reads - a renamed key, a key typed into the wrong section, or a feature removed from the code and left behind in the file. All three look exactly like a working setting.

/playport check (no argument) is the server-wide version: every live module's own problems, then every key of config.yml that no part of the plugin reads, each with a hint in the words of your file - there is no module called 'shpos', not a key shpos reads, nothing reads this section. That union is what makes the guarantee platform-wide: a key is inert only when nobody reads it, which is a claim that can be made out loud. /playport check needs ppcore.check.

Two honest edges:

• check is a verb, so it can collide with a name. /home check is a player asking for a home called check. The plugin resolves this by asking the module: if the command's first word is a name a player chose (a home, a warp, a kit, a rank), the word stays the player's and no report is printed. Commands whose first word is a subcommand or a number (/arena check, /pv check) answer as they always did, and /playport check <module> always reaches the report.
• The check knows your server, not your intent. A world that does not exist yet is reported, because the check runs against the worlds loaded at that moment. A template that creates its own world is not a fault; re-run the check after the world exists.

Templates and profiles

A profile is a small YAML file, profile-<name>.yml, in the plugin's folder. It carries the switches a template needs - which modules are off, and the values that make this server a hub or a prison - and nothing else. The panel applies one when it applies a template, and the plugin ships several of its own in pkg/profiles/ (hub, prison, lifesteal, skyblock, factions among them).

The operator-facing verbs, and the one subtlety:

/playport profile                 what is in effect, who chose it, what is available
/playport profile prison          switch to it now
/playport profile off             drop it and run on config.yml alone

• Settings take effect at once; both directions run a full reload.
• Module switches and command names are read once, at startup. The plugin says so after every switch: restart to apply those. This is not laziness - a module that is off must not have half of itself registered, so switches cannot be a live toggle.
• A profile: line in config.yml always wins over the runtime switch. If you are fighting the plugin about which profile is in effect, that line is the answer, and /playport profile names the layer that chose it.
• Your own edits still win. A value you changed by hand in config.yml is not overwritten by switching profiles, which is what makes "apply a template to an existing server" safe to try.

Hooks and the plugins beside you

Two mechanisms, one question each.

interop.yield - a plugin owning a whole job. The built-in table is long by design: EssentialsX, CMI, LuckPerms, PermissionsEx, GroupManager, GriefPrevention, Towny, Lands, WorldGuard, PlotSquared, RealisticSeasons, VotingPlugin and other vote listeners, Iris and other generator plugins, lifesteal plugins, PrisonRanksX, quest plugins, MineResetLite, auction-house plugins, enchant plugins, factions plugins, shop plugins, spawner plugins, ItemsAdder/Nexo/Oraxen/MMOItems, hopper plugins, random-teleport plugins, potion plugins, pet plugins, boss-arena plugins, NPC plugins, trading plugins, capture-the-hill plugins, fishing plugins, team plugins, cheat-detection plugins, chain-harvest plugins, elevator plugins, skyblock plugins, hide-and-seek plugins, tool-progression plugins and dungeon-wand plugins. The reasoning is the same in every row: two plugins holding the same job is worse than either alone - two anticheats is how a server gets false bans, two capture plugins double-pay every capture, two island plugins are two answers to "where is my island".

• It is resolved at startup from what is installed and enabled right then, not merely present, so a plugin that is disabled does not take a module away with nothing in its place. A reload resolves it again, which is how a plugin enabled later is still picked up.
• Every stand-down is printed to the console, with the exact fix: module 'perms' is standing down because LuckPerms is installed. Set interop.forceModules.perms: true to run it anyway, or turn the other plugin off.
• interop.forceModules.<id>: true runs a module anyway. interop.forceModules.<id>.off: true is the opposite, and interop.yield.<Plugin>.enabled / .modules overrides one row of the table.
• The whole table can be switched off with interop.yieldToInstalledPlugins: false, which is what you want on a server where you intend this plugin to own everything.

hooks - one question with a better answer when a real API is present. hooks.economy (Vault economy), hooks.permissions (Vault permissions), hooks.levels (mcMMO), hooks.bedrock (floodgate). With the switch on and the plugin installed, the answer comes from that plugin; with it absent or the switch off, this core answers the same question its own way. /hooks prints every row and where its answer came from, /hooks <row> details one, and /hooks has <node> answers for the caller, naming the path it went through. There is deliberately no combat switch: the combat-log plugins each publish a different API this jar does not link to, and a combat tag is a rule (hearts.combatLog) rather than a feature - so a switch there would switch nothing off.

Two optional layers with degraded modes, and they say which they are in:

• PacketEvents carries the packet-level half of guard (timer, aim, badpackets, groundspoof). Without it the plugin installs and runs exactly as it always has, and those four checks report not checked (no packet layer) rather than passing. guard is conservative and alerts-only by design; installing a real anticheat makes it stand down unless you force it.
• WorldEdit carries the schematic layer (schematics). With it, a world is written to and read from a real WorldEdit; without it, this core's own reader and writer do the job. The plugin links against neither API - every call is resolved by name and made reflectively - so a server with none of these plugins is unchanged.

What it writes on disk

Everything lives in the server's plugins/PlayPortCore/ folder:

The panel's own settings for this server are a file it writes beside the jar, in plugins/. That file is the top layer of the config load - which is why /playport panel exists: it names every setting the panel supplied, so "why is this value not what my config.yml says" is one command away.

Back up plugins/PlayPortCore/ with the rest of the server. It is small, and it holds the things your players would notice losing (jobs, rtp usage, lists of pages).

Reloading and upgrading

Upgrading is the panel's job (chapter 07): it installs a versioned jar and takes the older ones away, and because your config.yml is never rewritten, your edits survive the upgrade. Two things to expect after a version change: a new key appears in the shipped defaults and is not added to your file (set it explicitly if you want to change it - the shipped value is what applies until you do), and a key that no longer exists is reported by /playport check as a setting nothing reads, which is the same answer you would give it: delete it.

The plugin refuses to run on a Java runtime it was not built for, and the panel refuses it earlier with a console line rather than letting it fail at class load. That is deliberate - a plugin failing at class load reads as a broken server, not as a version mismatch. Chapter 03 covers the runtimes the panel installs.

Honest limits worth knowing before you hand this to players

• No purchases, anywhere, by design. If you want a store, you are adding a plugin rather than switching on a feature here - and nothing in this jar will offer the hook.
• Parity with the plugins it replaces is documented, not assumed. pkg/PARITY.md (../pkg/PARITY.md) is the authority on what a module deliberately does not copy from the plugin it was rebuilt from; read the row for any module you are migrating onto. Where a reference plugin's feature was a version checker, a metrics submission or a licence check, the module records it as deliberately absent.
• guard is a conservative observer, not an anticheat. It alerts; it does not ban. That is the setting the tree chose, and it is why installing a real anticheat makes it stand down.
• A module that is off is invisible from inside the game. Its commands do not exist. When a player reports a command that "stopped working", /playport status answers in one line.
• The plugin is one jar with about a hundred modules, and off is the honest default for most of them. A template is a choice; apply one, run /playport status and /playport check, and switch off what you are not using rather than leaving it on and hoping.

Files behind this chapter

Chapter 09. Networks and exposure

This chapter is about running several Minecraft servers as one address - a Velocity network with a hub, a lobby and as many game servers as you like, sharing one login, one chat and one staff team - and about giving a game server a public address when you cannot open a port on the router. It assumes you can already create a single server (chapter 03) and that you know what the core plugin does (chapter 07, chapter 08).

What a network is in PlayPort

A network is a group of servers behind one Velocity proxy:

The panel owns the whole relationship: which servers are in which network (each instance carries a network name), the shared forwarding secret, every generated config file, and the start order. That is the point of doing it here instead of by hand - a network's config is one record in the panel (networks.json) and every file is rewritten from it, so there is no set of files that can drift apart from each other.

The proxy is the address you hand out. Backends listen on their own ports too, but a player who connects straight to a backend bypasses the proxy and is normally rejected - that is what the shared forwarding secret is for.

Building one: Minecraft Network

Game Servers -> + New server -> the Minecraft Network category. The wizard builds the whole thing in one go:

Ports are chosen for you unless you type one: the hub starts at 25580, game servers at 25590, 25592, 25594…, limbo at 30066, and the panel scans every existing server and website so it never picks a port something else is already using. A network is refused if the name is already taken (A network named '<name>' already exists.) or the EULA was not accepted.

Each backend's core plugin is decided before anything is created. Every game row and the hub block carry a PlayPort Core picker: automatic (the name picks the template), a named template, or No core plugin. Automatic is the default and reads the server's own name and role, so a game server called Creative comes up on the creative template, Survival on the survival one, and a hub resolves to the hub template whatever the network is called; a template name this build does not ship is refused while the network is still empty, rather than leaving half of it built. A backend that cannot load plugins (Vanilla, or the limbo lobby) is told so in its own console and in Activity instead of being handed a jar it cannot use.

When the network is made, the panel creates the proxy first, then the hub, then limbo, then the game servers, and finally rewrites the proxy config - which is also when the bridge is installed and /hub is pointed at the hub. The proxy's console gets one line: "Network '<name>' created with N backend(s). Start the hub and games first, then the proxy." The toast names the templates it chose, because "Creative is creative" is the thing you just asked for and reading it back is how you know the name was understood.

Java for a proxy is not guessed. The panel reads the requirement out of the proxy's own jar (current Velocity builds ask for Java 25; older ones for 21 or 17) and downloads that runtime - see chapter 03 for the Java story. There is deliberately no javaVer pin on a network: a pin the jar cannot load is cleared with a line in the console rather than honoured, because a JVM rejects the class before any of the proxy's code runs, so such a pin could only produce a network that restarts forever.

What the panel writes

Everything below is generated. The header of each file says so, and the settings that drive them live in one place (the next section, not the files):

[servers] is written even when a network has no backends yet (it falls back to a limbo1 entry), because Velocity substitutes its own template defaults for a missing section - lobby.example.com mapped to a server called lobby - and then refuses to start.

The bridge: the proxy half of a network

The core plugin is a Paper plugin. It can see its own world and nothing else, so on a network it cannot know that a hub exists or move anybody to it. That job belongs to the proxy, and the bridge is the small Velocity plugin that does it: playport-bridge.jar, installed into the proxy's plugins/ folder, with its own config at plugins/playportbridge/bridge.yml.

Where it goes matters: on the proxy, not on a backend. The panel installs it as part of configuring a network, and the network card shows its state - bridge <version> on the proxy, bridge out of date, no bridge on the proxy, or no bridge in this panel build when the exe was built without one. The card's Install bridge / Update bridge button installs the build this panel ships and removes older ones of its own making.

The card's × on a member's name removes that server from the network and keeps the server and its world; the delete-network dialog offers Delete servers, keep their files and Delete everything for the same reason - "does the world survive this?" is the question a person actually has.

What the proxy answers itself

Server names are the names from velocity.toml - the panel writes them, and /server with no argument lists them, which is the quickest way to check one. An alias table in bridge.yml lets you add short names of your own.

What the proxy forwards

Some commands cannot be answered on the proxy at all, because the record they touch lives on a backend: /ban owns a player record, /vanish changes a player's state on their server. Those are handed over the playport:bridge plugin channel to the backend the player is standing on, and run there, as that player - so the backend's own permissions, ban records and command logic still decide. The list is configuration, never arbitrary text: the default is ban, kick, mute, warn, vanish, and each one is granted with playport.proxy.forward.<name> or by being staff.

Two consequences worth knowing:

• Velocity rate-limits a player's commands (one every 50 ms by default) and forwards the over-limit ones to the player's server. A routing verb that lands on a backend is handed back to the proxy over the same channel (the local request), and the proxy only ever runs a name it registered itself - which is also why the bridge module's own /staffchat on a backend is never the one that answers on a network.
• The console is always allowed, because an operator who cannot type into their own proxy console has no way out. A forwarded command from the console runs as the first argument that names an online player, since the record lives on that player's server; a console command with no player in it (/vanish) is refused by name rather than guessed at.

Who counts as staff on the proxy

Three sources, and any one of them is enough:

1. a name list in bridge.yml (staff.players), for a network whose backends run no PlayPort core plugin at all - Velocity grants a player nothing by itself, so without this list the staff half of a network would be unreachable on exactly the networks that need it most;
2. a permissions plugin on the proxy (LuckPerms, for instance);
3. the backends' own groups, reported over the link: the core plugin's perms groups carry the proxy's nodes and its bridge module sends them, so a network whose servers run the core plugin needs nothing installed on the proxy. The report is kept with the server it came from and only honoured while the player is still on that server, and only for node names the proxy itself owns - a backend cannot invent authority, and a player who moves to a server that does not run the core plugin walks away from the grant.

Starting and stopping a network

A network's card has one button: Start network or Stop network. Behind it the panel does the ordering for you:

• Start brings up the backends first - limbo, then the hub, then the game servers - waiting for each one to become live (45 seconds for limbo, up to 120 for anything else), and only then the proxy. Progress streams into Activity, and a failure names the server that did not come up (2 of 4 server(s) did not start - see the console for each one.) instead of starting a proxy in front of nothing.
• Stop shuts the proxy down first, then the backends in reverse, each with a clean shutdown so worlds save.

The card's dots are health, not process state: a backend that is running but does not answer a status ping is drawn as a warning, and its tooltip says running but not answering a status ping. Limbo is exempt from that check on purpose - NanoLimbo has no player list and does not answer server-list pings, so probing it would read as unhealthy. The player number on the card comes from the proxy, which is authoritative: somebody sitting in limbo or between servers counts there and not in any backend.

Starting a network is also a job: a start that failed is retryable with one click from Activity once the underlying problem (usually Java or a port) is fixed.

Adding a server to an existing network

The card's + Add server creates a new backend or attaches one you already have.

• Create & add asks what it is (Game server, Another hub / lobby, Limbo), the software (Paper or Vanilla), the name, the Minecraft version (defaulted to the hub's, so the network stays consistent), RAM and an optional port. Limbo has no software choice. The core plugin and its template follow the same rule as the wizard: what you asked for, then what the name and role imply.
• …or add a server you already have -> Attach takes any non-proxy server from Game Servers and joins it. Its world and files stay exactly where they are. A proxy cannot be a backend of another network (A proxy cannot be a backend of another network.), and a server already in the network is refused.

Either way the panel creates or enrols the server, rewrites the shared secret, the proxy's [servers] list and that server's own proxy settings - and tells you the one thing it cannot do for you: restart the proxy to apply the new routing. Detaching (× on the member, or Remove from the network) reverses it and keeps the server.

Network settings in one place

The card's Network settings dialog is the single source of truth for the network. It offers:

The dialog also lists the servers in the network with their roles and ports, and whether the shared forwarding secret is set and identical across all servers. Save & apply to every server rewrites every generated file and then reports what it touched, file by file; Re-push configs only does the same rewrite without changing a setting. Either way: "Restart the proxy for the proxy-side changes to take effect. Backends pick up their settings when they restart."

Two honest notes about this dialog in the current build:

• It is not where you rename a network. NetConfMgr.Rename exists, but no route in the panel's network dispatcher calls it, so a rename is not exposed here - the dialog edits the five settings above.
• The settings record is networks.json in the data root. If it cannot be read, the panel starts with defaults and says so; each network should be opened and checked, because slots, the MOTD and the login mode may have gone back to what they were when it was created.

playit.gg: a public address without opening a port

cloudflared fronts HTTP (chapter 05). A Minecraft client does not speak HTTP, so for a game server the tunnel to use is playit.gg, which fronts raw TCP and UDP. PlayPort downloads and runs their agent for you: Settings -> Components, or the health board's Install button (~5 MB, their signed Windows build, because Smart App Control refuses an unsigned binary on some machines).

One thing stays a human's job: the secret key. Generate it with playit's setup wizard - the panel links straight to it - and paste it into the panel once. It is stored beside the agent in the data root, never sent back to the browser (only its last four characters are shown), and deleting the folder deletes both halves. Then create the tunnel on playit's own dashboard and point it at 127.0.0.1:<port> - the panel prints that address on a game server's Overview and on a site's public access card. No router rule is needed.

What the panel does around that, and why:

• An agent you started is started again on the next boot (a wanted marker in its folder); an agent you stopped stays stopped. A panel that silently starts network-exposing software is a panel you cannot leave running.
• It will not start an agent that cannot serve anything. Run with no key it prints "Waiting for frontend secret provisioning" forever; the panel recognises that line, stops the agent and says which of the two states it is in, rather than leaving a process that looks running and serves nothing.
• A machine that already has playit set up by hand keeps working: the panel then runs the agent with no arguments, honouring playit's own stored setup.
• The tunnel definitions live on playit's dashboard, not in PlayPort - and the agent only exposes what you have told playit to expose.
• If you expose the panel itself this way, put something in front of it: the panel's login is not a firewall.

Ports and addresses an operator must get right

• Players connect to the proxy's port (default 25565), never to a backend's. The card prints connect <machine-address>:<proxy-port>.
• Backends and limbo have their own ports (25580+, 25590+, 30066+). They do not need to be reachable from the internet at all.
• Changing the proxy's port in the panel rewrites bind in velocity.toml - the file follows the instance, so there is no second place to change it.
• Both routes out of this chapter need the same three things to line up: the port the players use, the router (or the tunnel), and the machine's firewall - see chapter 11.

Gotchas

Files behind this chapter

Chapter 10. Mail, AI and the help assistant

This chapter covers the four things in PlayPort that are services with their own doors rather than pages in the panel: the mail service your websites send through, the local AI the panel runs on itself, the free cloud and linked machines it can borrow instead, and the help assistant that answers questions about the panel and can repair a few known problems. It also covers alerts, which are how all of the above tell you that something broke. None of it is required: a panel with mail off, no model loaded and no alerts configured still runs servers and websites.

Two of the doors in Appendix B belong to this chapter - 8100 (models and agents) and 8101 (the brain). They are separate from the panel's own port on purpose: publishing one must not publish the others.

Email: a real SMTP service for your websites

PlayPort runs its own SMTP service. The point of it is that a PHP site can call mail() the moment it is created, with nothing to configure and nothing to sign up for: each site's php.ini is generated with SMTP = 127.0.0.1, the submission port (1025 by default), and a sender derived from that site. If a mailbox is attached to the site, that address is used; otherwise the panel builds one from the site's domain and name, and falls back to noreply@playport.local when the site's domain has not been hooked up here. The submission port is loopback only and takes mail from any local process without a password, so it is never exposed - which is also why changing it is harmless.

Everything about it is on the Email page (#/mail), which is split into tabs because it answers six different questions: Overview, Delivery, Domains, Mailboxes, DNS records and Messages. ? Setup guide prints the registrar steps, the records and the ports; a plain user sees only Messages, because the rest is service plumbing the API refuses them anyway.

Hooking up a domain comes first

Mail is domain first. PlayPort does not register domains: you hook up one you already own, and the panel hosts the mail for it - locally, and out to the internet once the DNS records it prints are published. A mailbox only exists underneath a hooked domain, because a mailbox on a domain nobody has hooked up is a local address that can never send anywhere. The panel enforces that: Create mailbox on a domain that is not hooked up is refused.

Hooking a domain up gives it its own DKIM key pair and its own two switches:

• Send - sign and send outgoing mail as this domain. Off means no DKIM signature for its mail.
• Receive - host this domain's incoming mail.

A live DNS check runs when you hook the domain up and on demand afterwards. It queries the public resolver for the domain's MX, SPF, DKIM and DMARC records and reports a plain verdict - live, partly live or not live yet - with exactly what is still missing or different. It reports honestly rather than optimistically: a published DKIM key that does not match this panel's is called out as a mismatch, not as present.

The records themselves are on the DNS records tab, one line of explanation each, and they are yours to publish at your registrar: an A record for the mail host (mail.<domain>, or the configured hostname when it sits inside the domain), an MX record pointing at it, an SPF record, the DKIM record <selector>._domainkey (the selector ships as playport), and a DMARC record. Nothing in the panel can publish them for you, and sending to strangers' inboxes works badly until they are live.

Three delivery modes, because they fail differently

The Delivery tab is one switch with three settings, and the help text under each one says how it fails rather than how it works:

For relay the submission host, port, user, password and security (starttls, ssl or none) are typed in, with three presets one click away: TransIP, Gmail / Workspace and Outlook / Microsoft 365 (all on port 587 with STARTTLS). The relay password is stored in the panel data folder and is never sent back to the browser. Send test message walks the exact same path a site's mail() takes, so the chain can be proven end to end - the test returns a step list rather than a yes/no, and the summary says what the last failing step was.

A relay test result is remembered (its timestamp and summary are written to mail.json), and it is cleared the moment a relay setting changes, because a stale "it works" badge is worse than no badge.

Mailboxes, catch-all, and mail that arrives for nobody

Mailboxes live under a hooked domain, optionally attached to a website. Per domain you get one catch-all, and a message for an address with no mailbox is kept in the Unmatched folder rather than bounced away - accept-and-store is friendlier than a bounce when the domain is not fully set up yet. A mailbox can carry a password, but there is no IMAP or POP3 login behind it in this build: the password field is reserved for a future one, which is worth knowing before you hand an address to a customer who expects to collect mail from it.

Messages are readable per folder with headers and a plain-text body, and Raw headers shows the message as it arrived. Folders are the mailbox address (with @ written as _at_) plus the internal _sent and _unmatched; each folder keeps the newest 2,000 messages.

Incoming mail is opt-in

Receiving mail for a hosted domain means listening on port 25, which needs administrator rights, a firewall rule and an ISP that does not block the port. So it is a switch (Incoming mail), not a default. Turning it on binds the port, adds the inbound firewall rule the panel needs to be reachable at all (without it Windows silently drops the packets, which looks exactly like a wrong router forward), and lets you choose the port. Turning it off leaves the submission side running for your sites.

Where mail lives, and who may touch it

A damaged mail.json is not silent: the panel starts with shipped defaults and says so, naming the copy beside the original that still holds your addresses, relay host and passwords. The relay password and every per-domain DKIM private key stay in that file and are never sent to a browser.

Who may change what: a plain user may read the service status and their own messages, but not change the service, hook up a domain or read the internal folders. Admin and moderator may do all of it.

What this is not: it is not mailbox hosting. There is no webmail, no IMAP and no POP3 in this build, so treat it as the thing your websites send through (and, if you opt in, the thing that receives their mail for you to read in the panel). Sending to the internet from a home connection still depends on the reputation of whatever relay you point it at, which is why relay is the mode to use for real mail.

The models: the AI this panel runs on itself

The panel hosts a model of its own and uses it for four things, all of them local and all of them offline by default:

• Explain - a crash the rules did not recognise. The rules in Diagnose.cs stay authoritative: a known failure is explained from a written, tested rule and the model is not asked at all. The model covers the tail, reads the same evidence, and is told to answer "the evidence does not tell me" rather than guess.
• Triage - the log lines nothing matched, classified once and remembered. This is not a button: an unrecognised crash is filed in the review queue (see chapter 02) and worked out on the panel's own tick.
• Assist - the chat in the panel, which can propose changes with a confirmation on each one. ai_yolo turns the confirmation off; it ships off and is off again after a restart.
• Overview - the plain-language summary of what needs attention, written from the health items.

Every one of those obeys the hardware guard first: if the machine is busy or hot, the work is refused with the same sentence the guard would give any other request. A running game server outranks a nice paragraph.

The guard is about the machine, not about trust

This panel also hosts game servers, so a model competes with them for the same GPU, RAM and heat budget. The guard reads the machine and refuses starting work, rather than starting it and cutting it short. Its thresholds are settings with these shipped values:

An idle unload is not undone on a timer: the next question (or the page's button) loads the model back. A model that reloads itself only to sit idle again is a machine heating itself for nobody.

The engine, the models, and where they come from

The engine card on the Models page shows the runtime the panel drives. By default that is a llama-server from llama.cpp, started with flags computed for this machine: the number of layers on the GPU comes from the fit calculation rather than a fixed guess, the context window comes from the setting, and the model's own chat template is used (which is also what makes tool calling work). One model is loaded at a time - an 8 GB card holds one useful model, and switching stops the old server and starts the new one. The server's own output goes to a log file, and the interesting lines (the ones that say why a load failed) are read back and shown, because "the server exited with 1" is not a diagnosis. A process killed by application-control policy is reported as exactly that, from its exit code.

If you already run a runtime - Ollama, LM Studio - the Vendor runtime URL setting drives it through its own API instead of spawning llama.cpp, with Model to use in the vendor runtime and a hold time in minutes. A runtime like that loads on demand, and the panel treats it as able to answer: it takes the request and pulls the model itself.

Models (the catalogue card) come from Hugging Face. Weight files are data, not programs, so application-control policy does not apply to them. Three things the downloader is careful about, all of them visible in the transfer: it resumes (every file is written as .part and picked up with a Range request, because a 19 GB file over a home connection will be interrupted), it plans every shard of a split quant (half a split file is not a model), and it reports a gated repository as needing a Hugging Face account, which this panel cannot provide. Model files live under <data root>/models unless Where models are kept points somewhere else - a share on another machine is allowed, and the panel keeps its own caches elsewhere precisely because a share can be asleep.

The model this panel runs is chosen for you by default. autoload ships as auto: the panel ranks what this machine can actually run and says why - a model that is already here beats one that has to be fetched, one that fits entirely on the GPU beats one that spills into system RAM, and among equals the larger model wins - then fetches the pick, loads it, and reports each step in the feed. A candidate the guard would refuse is dropped before it can win, so the automatic pick is a model that can load on this machine as it is now; a machine that was busy at startup gets its model later, on the panel's tick, with nobody watching. Setting autoload to a model id pins that model, and leaving it empty means nothing loads by itself - which is what "do not touch my GPU" looks like as a setting. Let go on the page unloads it on purpose; it comes back when you ask.

The rest of the Models page is the state rather than the machinery: This machine (a live strip), Stats, Ask the panel (a chat that uses the model), and What happened (the feed of loads, refusals and answers). The hardware guard says: opens each card with the guard's own verdict, and a limit that has been crossed is stated with the measured value next to the threshold it broke.

Which model answers, and where: the tiers and the free cloud

One panel can answer from three places: a small model here, the big model this machine was measured for here, and a linked machine across the network. There is also a fourth: the free cloud.

Light and deep

Every request carries a weight. Routine work (the overview, the help box, a lookup, a thought) is light and is answered on this machine, always, on the small model: it costs nothing extra and never wakes anything. A hard question (a crash nobody has seen, a repair, an agent turn) is deep, and only a deep question may move:

1. the model that is already loaded, if it can do it;
2. the big model here, but only if this machine is idle enough for it - at or above Above this processor load the big model stays unloaded (tier_busy_pct, 60 % by default), or with a guard verdict against starting work, it is not loaded on top of what is already running;
3. a linked machine that is already awake;
4. a linked machine that can be woken - the last resort, because waking a whole computer is the most expensive thing the panel can do;
5. the small model here, saying so, because a shorter answer with a reason beats a failure without one.

Which machine answers (tier_mode) is the policy: auto (this machine first), local (never hand work to somebody else) or peer (prefer the other machine). Prefer a linked machine for hard questions (tier_prefer_peer) says whether a linked machine is tried before this one's big model, and Shortest time between model swaps (tier_min_secs, 45 s) stops a busy machine reloading itself continuously to answer polls. The Models page shows both paths with the reason for each, read from the panel rather than re-derived by the page.

The free cloud

cloud_tier is one switch in three honest positions:

It points at any OpenAI-compatible router (cloud_url, default https://router.requesty.ai/v1), with cloud_model naming the model. The key is a secret: it lives in its own file under the panel's state directory (ai/cloud.json), never in settings.json, because a setting is something the panel shows, logs and hands to every page. One key from the router's own key page opens it, and tier_mode=local still wins over all three positions: a panel told to keep its questions local is never overridden by this switch.

Two things the panel is careful about, and both are things you should know before switching it on:

• A free model has to stay free. The catalogue of no-cost models is measured and then written down - every shipped entry answered GET /v1/models with an input and output price of exactly zero - and the panel refreshes that list from the router whenever it can reach it. A model that has started charging is named as charging before a chip is clicked, rather than offered as free and quietly costing money.
• A rate limit is ordinary, not exceptional. These are shared free quotas, so when the chosen model answers 429 the request walks the free catalogue and another one takes the question. The reply says which model was asked first and why it stepped aside (a rate limit, a retired model, a router error), in the words of the refusal that actually happened, and whatever answered is named - an answer that quietly comes from a model nobody picked is worse than a refusal. A rate-limited model stands aside for cloud_cooldown_secs (120 seconds by default) so the next question does not pay for the same discovery, and the Models page can put it back in play by hand.

Other machines: two panels using each other's hardware

A second PlayPort running this same software can answer for this one, and this one for it. That is a decision, not a default: nothing is sent anywhere until somebody links a machine, and this one answers other machines only while Serve this machine's models to linked machines (peer_serve) is on.

A machine is linked by the address of its model port (not its panel) and a key minted on its Agents page. Getting that right by hand means three things at once on the correct machine, so the Other machines card pairs instead: on the machine lending its hardware, Pair a machine shows a one-time code (eight characters from an alphabet with no 0/O or 1/I/L in it, because a code read off a screen should not have two possible readings) and a ticket carrying that machine's own address. On the other machine the ticket goes in one field - no address is typed and no key is minted by hand.

The code is the credential for that one exchange and nothing else. It works once, it expires (15 minutes by default, and the page counts down), ten wrong tries throw it away, and what comes back is an ordinary API key named after the machine that paired. It asks for no key on the redeem route because the code is the key for that exchange. A paired machine does not bypass peer_serve: the machine that showed the code keeps its right to refuse, and pairing says so up front instead of letting the first hard question fail.

• In the same house the link is a LAN address and it works as it is.
• Across the internet one of the two has to be reachable, so the Models page can publish this machine's model port through the cloudflared the panel already manages - it prints an https://….trycloudflare.com address to paste into the other machine. Three rules make that safe: it is off unless somebody turns it on (and a published machine comes back published on the next start); it refuses while this panel has no key, because publishing a port before there is a key is advertising a model anyone could use; and it says what it is doing - the address, whether the tunnel is up, and that the port is reachable are on the page and in the feed. Only the model port is published; the panel and the brain are separate doors and stay shut.

Waking a linked machine is a standard magic packet on the local network (the peer's MAC is typed in with the link) plus an optional wake URL - a relay on the peer's own network, since a broadcast cannot cross the internet. Everything the panel says about a peer is what the peer itself answered: /health on its model port needs no key and reports the model it has loaded, its guard state and its load, so "asleep", "busy" or "running qwen3:14b" are its own words rather than a guess from the last time this panel looked. A peer that refuses, is busy or is not there is a fallback for the caller, never an error in the middle of somebody's answer. The list lives in <data root>/ai/peers.json, and the keys in it never travel anywhere except to the peer they belong to.

Looking things up, for a model that has no internet

A model running on this machine cannot browse and cannot know anything released after it was trained - which is exactly what a hosting panel gets asked: is this build newer than what that plugin wants, what does this exception mean, which Java does 1.21.4 need. The panel does have an internet, so with Let a model ask the panel to look things up online (ai_web) on, the model may ask: it replies with a search request instead of guessing, the panel runs the search, reads the page, and hands the model what it found.

It is off by default, and that is deliberate: it is the only place in the panel where something leaves the machine on the panel's own initiative, so a switch is what makes that a decision rather than a surprise. The engine (ai_web_engine) is one of duckduckgo (the plain HTML endpoint, no key), wikipedia, or searx - your own instance, by URL, which is the homelab answer because nothing goes anywhere you did not point it. Engine base URL carries the searx address or a mirror, and the ceilings are settings: Lookups one answer may spend (2), Lookups allowed per hour (20, for the whole panel) and Characters of a page the model may see (6000). When the engine asks for a human check - the scripts-in-a-browser kind of block - the panel says so and suggests a searx instance rather than pretending the lookup found nothing.

The agent API: other AI tools using this panel's models

The Agents page (#/agents) is the whole story in one screen: The three ports with what each is for, the Keys, who is Connected now, the Two-way channel (a box to say something to an agent and the feed of what agents said), and Pointing a tool here - a ready-made curl and the OpenAI-compatible base URL (/v1/chat/completions) for the tool you are about to point at it.

The surface is on port 8100 (Settings, Model and agent port), and it is deliberately small: nothing on this listener can reach instances, settings, users or the panel's own state. That is the property that makes it safe to hand a key to a tool somebody else wrote.

Making a key (Agents, then New key) shows the secret once, with a copy button, and the modal says so in the same breath as showing it. Only a hash is kept, so a lost secret means a new key rather than a recovered one. Auth is Authorization: Bearer ppk_..., X-Api-Key: ppk_..., or ?key=ppk_... for a tool that cannot set headers - the last one exists because the alternative is a tool that cannot connect at all, and it is worth knowing it puts the key in a URL.

What a key may do is one grant per key, editable later (What "<name>" may do): a workspace, whether it may write outside that workspace, run commands, delete files, and whether it may read and write the shared brain. Writing outside the workspace, running and deleting are all off until a person ticks them, per key. Keys can be paused and revoked - revoking stops the key everywhere at once - and each key carries its own per-minute request limit (60 by default).

What a key cannot do, deliberately: touch instances, read files you did not grant, or change settings. It can use models and it can talk. And the guard applies to an agent exactly as it applies to the panel's own AI: an external tool asking for a completion while the machine is hot gets the same 503 with the same sentence. An agent cannot outrank the hardware, and it cannot outrank a running game server.

If you publish this port - to a tool on another machine, or through a tunnel - remember which door you opened: the answer is a key on 8100, not the panel's login page, and a tunnel aimed at 8100 must not also carry 8080. Reachable from the network binds it beyond loopback and the key remains the gate whatever the bind; where Windows refuses that bind, the port still comes up on loopback and the log names the exact command that would fix it.

The brain: what this machine has learned

The brain is a folder of markdown under the data root (brain/entries/*.md, with brain/index.json beside it), so you can read it, grep it, copy it or edit it by hand with no PlayPort running. Each entry has frontmatter (id, type, title, tags, scope, created, updated) and a body, and the types are knowledge (a durable fact), memory (what happened: this crash, this fix), decision (a choice and why) and note (anything else).

Two ways entries get written: the model writes them when it learns something worth keeping, and the panel writes them as memory after work that changed files, so the record of what an agent did survives the agent. The help assistant's Remember this button is the only way a model's answer becomes an entry, and it is a button on purpose: a brain feeds every later prompt, so a guess must not land there on the model's own say-so.

It is served two ways - the panel's own routes (a person, with a session) and port 8101 (a program, with a key). Reading is open to any valid key; writing needs that key's brain permission, which is on by default for keys a person creates here, because a shared brain nobody may write to is just a document.

The notes are compressed, not truncated. A note is written for a person and read by a model, and a prompt pays for every character twice, so a note is compressed against the question: the blocks that answer are kept in their original order and the rest is dropped and counted - the answer says how much it left behind and how much of the budget it spent (the block's ceiling is 1,400 characters), so a reader can ask for the entry by id rather than believing they read the whole thing. A question nothing answers reports the size of the store it searched rather than pretending nothing is known.

With no panel at all, the same store answers from the command line:

PlayPort.exe --data <root> --brain-context "port 8080 already in use" --brain-budget 300

The help assistant, and the hands it is allowed to use

Help in the sidebar (or F1 from anywhere) opens one box that answers questions about this panel, using the model the panel already runs. Buddy is the same assistant as a page (#/buddy), with the conversation, the model's own thinking above each answer, the free models one click away, and the switch that decides which machine answers.

What makes an answer checkable rather than merely fluent is the evidence the box is given before the model sees anything:

• its pages, each with what it is for, read from the same list the sidebar draws - so an answer names only pages that exist, a route the model invents is dropped rather than followed, and it can say "the panel does not do that";
• its settings, with the label each is shown under, read from the settings code itself so the list cannot go stale;
• the machine: what the health check says, and the names of the servers that exist;
• the brain: what this machine has already learned, ranked for the question, so a fix worked out here once is an answer it gives away for free the next time.

When no model is available the box is still not a dead end: it says so, names the note that looks relevant, and points at Models to see what this machine runs and why.

Buddy's hands

An assistant that can only talk is a consultant. Buddy's hands is the middle ground between talking and having a shell, and the whole of it is one idea: a rulebook that says where the lines are. Every failure the panel already recognises by name knows which file is worth opening for it, so a rule carries the symptom it answers to (the same rule ids the crash page uses), the files to open and the pattern that picks the lines out of them with a sentence saying what they are, and - where one exists - the single safe edit that removes the cause. Nothing is invented at the time, by the panel or by the model. The rulebook ships with ten entries and four fixes (a half-made world, a taken port, a view distance a machine cannot afford, and the EULA line), and it is listed on the card with where each rule looks.

Pick a server in the composer and the answer changes. The panel reads that server's console through the same feeder the crash page uses, adds the tail of the server's own logs/latest.log, and opens only the files the rulebook names for the symptoms it recognised - the model is handed those lines with their file and line numbers and told to quote only what it was given. It never reads a whole log: a 40 MB latest.log costs a 256 KB tail read.

A fix is written by the panel, not by the model. A model can only name a fix the panel has already decided applies to that server as it is now, so a fix card is a file, a key, the value it holds and the value it would get. Four rules make that safe, and all four are checked in code before the card exists:

• a fix is offered only when it applies - a view distance already at 8 offers nothing, and a world folder is set aside only when it really is half-made and has no land in it;
• every write goes through the tool layer, so what it replaced is journalled and Undo this puts it back from the same card;
• the machine's own guard can refuse the write, and the file is read back afterwards and the new value reported from what it now holds, never from the intention;
• a fix that worked becomes a brain entry, so the next server that dies this way does not need a model at all.

The mode is ai_buddy_hands, and it follows who is doing the thinking by default:

That auto is the honest answer to "can a 7B model be given hands": it can be given a rulebook and a journal, and it does not have to author the change. Running commands and deleting files are switches (Run commands (panel assistant), Delete files (panel assistant)), off by default, and a manager sets this - it decides what the panel's assistant may change on this machine. A job runs in the server's own folder, and the card says so before you ask for one.

Alerts: being told when something breaks

A hosting panel that only speaks when you are looking at it is not much use at 03:00. Alerts sit on the Settings page and push the handful of events that actually matter to a Webhook URL (Discord or Slack - the panel sends content, text and username, so one URL works for either) or by Email address through the panel's own mail stack, or both.

Repeat the same alert after this many minutes (0 = always) is the flood guard, and it is on by default (10 minutes): a crash loop fires the same event every few seconds and a webhook that floods is one people mute. The key is the event plus the server, so two servers crashing at once are both reported. Set it to 0 to be told every single time.

Send a test proves the wiring and reports what each channel actually said - and it decides success by the status code, not by the text, because a webhook that was deleted still returns a body. A test that reaches only some channels says so. Two further properties worth knowing: an alert is never sent more than once per window, and an alert never throws into the caller - a webhook that is down must not be able to break a game server. Email alerts need the mail module running; the panel says so rather than failing quietly.

Files behind this chapter

Chapter 11 covers the health and diagnose screens these features report into, and the ports/firewall reference. Chapter 09 covers playit.gg, which is a different way of exposing a game server than the Cloudflare tunnels used here.

Chapter 11. Operations, the API and troubleshooting

This chapter is for the person who keeps a PlayPort machine running: what to watch, what to back up, what the health board is telling you, what the panel's API actually serves, and what to do when something breaks. It assumes the panel is installed and has servers or sites on it (chapter 01); it does not repeat how to create them.

Everything here was read out of this tree's sources. Where the code is ambiguous the chapter says so rather than guessing, and the Files behind this chapter table at the end names the file each section describes.

Running a panel day to day

The panel is a normal Windows program with a console window and a data folder. Its own operation comes down to four things: knowing whether the pieces are up, knowing when something failed, not running out of disk, and having a copy of the data folder that is not on the same disk.

A reasonable routine:

1. Look at the health board once a day (Health in the sidebar, or GET /api/health). It walks every subsystem once and answers per row - see the health board below.
2. Look at the activity list (Activity, GET /api/tasks). Everything that takes time - an install, a backup, a MariaDB download, a certificate order - is a job with an outcome, and a failed job stays in the list with a Retry button. A job nobody retried is the usual way a feature is quietly dead for a week.
3. Watch the storage number (Settings, Storage, GET /api/storage). It measures the whole data root and lists the servers and sites by size. Its ?fresh=1 form is the Re-measure button: it throws the measurement cache away first, which is what to use when the number looks stale rather than when it looks large.
4. Keep a copy of the data folder somewhere else. See backing up and moving the panel's own data.
5. After an update, look at the health board and the panel's own version line again. The panel reports the build's check line on its Panel row when the build was not verified by this tree's gates (--version prints the same line as its second line): that is not a failure, it is the artifact telling you it was built with the checks skipped.

Two logs carry almost every answer in this chapter:

The health board

Health.Report walks the machine's subsystems once and returns one row per area with a verdict in words an operator can act on. It is staff only: GET /api/health answers 403 for a plain user, because the board reports on the machine, not on one tenant's corner of it.

Four verdicts, and the fourth is the one most panels get wrong:

The board is only useful because the second line of every row is the next step rather than a restatement, and because each row is produced by measuring something. The areas it covers:

• Panel - the version and build, and where it is listening (loopback only, or reachable from the network), plus uptime. When the build was not checked by the gates, this row says so.
• Saved settings - the files that remember what the owner chose. A settings.json the panel could not read used to be replaced with defaults in silence; now every unreadable file is recorded once, by name, with the copy it kept, and this row is where an owner finds out. The row separates the two directions: a file that could not be read is not a change that could not be saved.
• Foreign files - files that are somebody else's: a server's server.properties, the whitelist and ban lists the server writes, a downloaded modpack. The panel reads them and must never rewrite one, so this row carries the whole answer rather than a repair.
• Unfinished work - background actions whose outcome never came back.
• Volume, Database, Email, Php, Java, Steam, Tunnels, Certificates, Websites, Backups, Servers - one row per subsystem: disk space, the MariaDB server (chapter 06), the mail listener and its records (chapter 10), the PHP pool (chapter 05), the Java runtimes (chapter 03), SteamCMD, Cloudflare tunnels, certificates near expiry, the sites, the backups and the game servers.
• Work - the panel's own detached work: whether anything it started is still running.

The board ends with a summary sentence and a single verdict (fail beats warn beats ok), so a script can watch it without parsing the rows.

The Settings page also carries a separate Server readiness panel. That one is a preflight for a machine about to face the internet - see reachability below.

Diagnose: what the panel says when a server broke

The panel explains a server failure with a rule engine over the console output, not with an AI and not with a service. That is deliberate: sending a customer's console to somebody else's computer is a privacy leak and a paid dependency, and the engine works offline, instantly and for free. Its one honest limit is that it can only say "I don't recognise this" - it never invents a cause.

Every finding carries the same fields, and they answer the three questions a non-technical owner actually has:

Where it is reachable:

• In the panel: the server's Console tab (and its own diagnose view) - GET /api/instances/<id>/diagnose, with ?full=1 for the whole scan rather than the summary.
• From a shell, without the panel running: PlayPort.exe --diagnose <log-file>. It prints the same JSON the API returns - file, lines, count, findings[], unexplained, summary - which is exactly what makes it the thing to attach when you ask for help, and why this chapter says "why did the panel say that about my log" is answerable without the panel running.

What the engine does not recognise is kept, not dropped. Every crash no rule explains is filed in the review queue (Activity in the panel) and written to unknown-crashes.json in the data root:

• entries are grouped by a signature of the "error-ish" lines, so a crash loop becomes one entry with a count rather than a wall - the ranked list is what makes fix the 40-times one first possible;
• each entry keeps a trimmed copy of the log (40 lines, 300 characters a line) so the evidence does not scroll away;
• a crash loop inside 30 seconds updates one entry instead of racing the counter;
• the file holds at most 60 entries;
• when a new rule is added, every stored entry is re-checked at the next start and flips to understood - so the normal loop is: a crash lands here, a human reads it, the rule is added, the entry can be cleared.

The panel's routes over that queue are /api/unknowns (list, rescan, re-check, clear). This is a filing cabinet, not a diagnosis: nothing in it leaves the machine either.

The ports and firewall reference

Appendix B is the authoritative table of every port the panel listens on and what proves who is talking. This section is the Windows half - what has to be open, and what Windows refuses.

The panel and every HTTP website are served through http.sys, which is why two separate things have to line up for a machine that faces the internet:

1. A URL ACL - Windows checks the http:// prefix form separately for each spelling. Binding a non-loopback HTTP port without a reservation answers access denied, and the panel prints the exact command to fix it: netsh http add urlacl url=http://+:8080/ user=Everyone add-urlacl.ps1 in this repository does it once, for ports 8080, 8081 and 80, and for every prefix form http.sys checks separately (+, *, 127.0.0.1, localhost, and one hard-coded LAN address - that last one is a script you should read before you run it, because the address in it is not yours). A site that was refused says the same sentence with its own port (Util.PlainPortError), which is the difference between a website that is broken and a website that is not allowed to listen.
2. An inbound firewall rule per port - the panel's HTTP is http.sys, so a rule scoped to PlayPort.exe never matches. add-firewall.ps1 adds rules named PlayPort web TCP <port> for 80, 8080 and 8081. Every other port - a game server, a site on 8092, a TLS port - needs its own rule, which the panel adds itself while it is running elevated.

"The port is taken" is two different faults. A port already bound by another program is one; a port shadowed by another program's wildcard reservation (http://+:8080/, which some vendor tools and phone-link utilities install) is the other, and it is much nastier: the panel binds successfully, answers its own health check, and every browser gets an HTTP 503 from a queue nobody is serving. PlayPort measures this rather than assuming it - at startup it asks itself on the selected port, and if the answer does not come back it moves to a port that does answer and saves the choice, then records the one admin command that gives the old port back:

netsh http delete urlacl url=http://+:8080/     # or: netsh http show urlacl

The moved-from port is shown in the panel (the settings/installation card, portMovedFrom in /api/install), which is why the address a panel answers on can change without anyone choosing it.

HTTPS is not the same path. A TLS listener is its own socket rather than an http.sys prefix, so a site on a tlsPort does not need a URL ACL - it needs the certificate and the port open (appendix B, chapter 05).

Running elevated is what lets the panel open non-loopback ports and add firewall rules for you. Without it, loopback-only panel plus loopback-only sites still work, and the readiness board says so in as many words.

The security model

Stated plainly, because a hosting panel's security is mostly a list of what is not protected.

What is protected, and how

API keys are a different door from the panel. An agent key is minted under Agents, looks like ppk_..., is shown once at creation, and is presented as Authorization: Bearer ppk_..., X-Api-Key: ppk_... or a key= query parameter (for tools that cannot set headers). It is accepted by the model and brain ports, not by the panel's own /api/* surface, which takes the session token. A key can also carry a per-minute limit, a model allow-list and a tool grant - that is chapter 10's subject.

What is not protected - read this part

• Hosted PHP is not filesystem-isolated between customers. The site's PHP runs with an open_basedir restriction, which is a boundary against accidents rather than a sandbox against a hostile tenant. Chapter 05 states the limit in full.
• The data root is the crown jewels. It holds auth.json (accounts, sessions), settings.json, every server's files, every site's files, databases.json with the MariaDB credentials, mail and the mail's signing keys. Anything that can read that folder can own the panel. Directory permissions and a backup that does not travel over an untrusted channel are the real controls.
• Backup destinations hold credentials and decide where a customer's world ends up, so they are admin-only in both directions.
• The panel has no TLS of its own by default - it speaks HTTP on a loopback address. If you expose it beyond this machine, put it behind a tunnel or a reverse proxy with TLS rather than opening a plaintext port.
• The mail module serves mail, so its port is as exposed as you make it (chapter 10).
• Nothing here protects you from a game server that misbehaves. Servers run under the panel's user account. The panel caps memory and kills children with the panel (job objects, chapter 04); it is not an operating-system boundary.

Backing up and moving the panel's own data

The panel does not have a button that archives its own data root - its backup feature archives servers (chapter 04). The panel's own state is a folder, and the honest procedure is a file copy that respects what is running:

The consistent copy (recommended)

1. Stop the game servers that matter (their worlds are the part that is painful to lose) and stop the mail/DB-dependent things you care about.
2. Stop the panel: the console window closed, or PlayPort.exe --stop for a graceful shutdown that lets saves finish.
3. Copy the whole data root. It is the folder the Settings page names (dataRoot), normally playport-data/ beside the exe.
4. Start the panel again.

What is in that folder (appendix C, and the rest grows with the features you switch on): settings.json and auth.json, instances/ (every server), sites/, steamcmd/, MariaDB's own data/, databases.json, mail, peers.json, networks.json, unknown-crashes.json and playport.log.

Two cautions that are worth more than the procedure

• MariaDB's files must not be copied out from under a running database. Either stop MariaDB first (Settings -> Components, or POST /api/db with op: stop) or take a dump with the bundled client - chapter 06 gives the exact command. A half-written InnoDB file is worse than no backup, because it looks like one.
• A copy taken while servers run is a usable copy, not a consistent one. The panel warns and does not pretend otherwise: a world being written at that instant may need the repair path or an older backup. If you are copying while everything runs, copy twice and keep both.

Restoring is the reverse: stop the panel, put the folder back (whole, or only the parts you restored), start it. --purge-data on an uninstall is what deletes that folder, and data is kept by default when you uninstall (chapter 01).

Moving the installation or the data root has a documented path rather than a drag-and-drop: --install --dir DIR, --data DIR, --move-data / --no-move-data, and --finish-install for the case where a panel is running and could not move its own folder - chapter 01 owns that procedure.

The REST API reference

The panel's API is /api/* on the panel port. It is not the model API: an OpenAI-compatible client pointed at the panel gets an answer that names the model port, the base URL and the kind of key to use, instead of a 404 that reads like the feature was removed. The three doors are appendix B.

Authentication. Everything needs a signed-in session token except the six public endpoints. The token is the value returned by POST /api/login (or from first-run setup); it is sent the way the panel's own page sends it, and POST /api/logout deletes it. Agent keys (ppk_...) are for the model and brain ports and are not accepted here.

The public endpoints - no session, and each one is deliberately small:

The resource surface. The dispatcher reads the third path segment as the resource and then matches sub-routes, so the shapes below are patterns, not a list of every generated path. :id is a server or site id; { } is the request body.

Instance sub-actions (/api/instances/:id/<action>), with the capability each one needs. The mapping is enforced per request, and it is the same table whether the caller is an admin or a grant-holder:

Site sub-actions (/api/sites/:id/<action>): toggle (control), files and importzip (files), tls (view for reading, edit for changing), preview and diagnose (view), and GET/POST on the site itself (view/edit).

Two honest caveats about this table. First, the dispatcher is a chain of prefix matches with dynamic segments, so a route added by a newer build will not appear here; what is listed is what this tree's Api.cs names. Second (and this is the reason the manual says it): a control drawn in the panel's page is not proof that a route exists - a sibling chapter found website controls whose backend is not in this tree at all. When in doubt, the code is the authority and this table is a map.

Errors. A request body that is not a JSON object is 400 Request body is not valid JSON.; a missing or expired session is 401 Not logged in; a missing right is 403 with a sentence; an unknown route is 404 unknown endpoint; a handler that throws logs the whole stack to playport.log and answers with a plain sentence rather than the exception's own words. That last rule is this tree's: what a buyer reads is a sentence, and the stack goes to the log.

Troubleshooting by symptom

Each entry names the check and the chapter that owns the detail. Where a command is given, it is the one this tree prints.

The panel will not start

• Read the console window - fatal startup errors pause rather than vanishing when the exe was double-clicked, so the sentence is still on screen.
• The usual cause is the port. The panel retries for a few seconds (http.sys can hold a prefix briefly after a restart) and then says so, suggesting PlayPort.exe --port 8081.
• If it starts and your browser gets 503 while the console says it is up, the port is shadowed by another program's reservation: the panel now measures this, moves itself to a port that answers and saves the choice. To claim the old port back: netsh http show urlacl / netsh http delete urlacl url=http://+:8080/. See the ports section.
• A non-loopback bind that answers access denied needs the URL ACL (add-urlacl.ps1, or the exact command the panel prints).
• Chapter 01 owns installation faults (a non-writable folder, a second copy already on the port, the data-root fallback).

The console window was closed

The panel and the game servers it started are that process tree. Closing the window stops them, and Windows may not let a server finish its world save. Start the panel again and check the servers' consoles for what was cut short (chapter 04); a world that was being created at that moment is the case the repair path exists for (chapter 03).

A server will not start, or keeps restarting

1. Open its Console tab and read the diagnosis - it is usually one of five things, and the engine names which: Java too old or missing (java.too-old, java.missing), memory (java.heap), a port another server already holds (port.in-use), the EULA (mc.eula), or a bind refused by Windows (port.lan-acl). Each finding carries the steps.
2. If nothing matches, the crash is filed in the review queue - that is the case where the panel is saying "I don't know" rather than "nothing is wrong".
3. PlayPort.exe --diagnose <the server's console.log> gives the same answer as JSON without the panel running.

Chapter 03 owns versions, loaders, the start executable, restart policy and the world repair.

A website answers 404, or nothing at all

• 404 with a file extension: the file is not there - the file manager's path is the site root.
• 404 without an extension: a client-rendered SPA falls back to index.html by design; a site that is not an SPA has no such fallback, and a missing page is a missing page.
• 403: the site is a static site with no index file.
• Nothing: check the bind. Sites bound to 127.0.0.1 are only reachable from this machine, and the readiness board fails that row out loud. Chapter 05 owns the rest.

TLS fails, or a certificate does not renew

Readiness has a Certificates row and a Websites row, and the site's own TLS panel reports the last order. The common causes are structural: the CA cannot reach port 80 on that domain (http-01 challenge), the domain does not resolve here, the site is bound to loopback, or the port is held by another program. Chapter 05 owns the ACME flow, staging vs production and the self-signed and PFX alternatives.

The database will not start

The health board's Database row says which of the states it is in, in its own words, and chapter 06 maps each sentence to a cause - most often port 3306 already taken by another MySQL, a data folder that another MySQL instance owns, or a disk that is full. The panel deliberately does not adopt a foreign 3306 without saying so.

The core plugin is not loading in a server

• The server's Plugins tab reports the embedded jar, what is installed, and whether the server is the kind that can take it at all (chapter 07).
• The plugin needs a Java the jar can run; a plugin that fails at class load prints the same Java-version refusal a server does, and java.too-old catches it.
• The plugin's own diagnostics are in game: /playport status lists the modules, and each module's <command> check reports its settings (chapter 08).

A model will not load

The guard comes first, and it is about the machine rather than about trust: this panel also runs game servers, so a model competes for the same GPU, RAM and heat budget. A limit that was crossed is stated with the measured value next to the threshold it broke, and a load is refused rather than started and cut short. Chapter 10 owns the model screen and the tiers.

The machine is unreachable from the internet

Run the Server readiness preflight (staff, GET /api/ready). It measures rather than repeats: your public address, whether the DNS records would name a private address (the single most common way a real deployment fails while every field looks plausible), reverse DNS, outbound port 25 and 587, the mail domains, the website bind address, HTTPS coverage, and the panel's own exposure. It uses four verdicts - pass, warn, fail, info - and every row carries the next step.

The three things that must line up for anything to be reachable: the router forwards the port, Windows has an inbound rule for it, and the program is bound to something other than loopback. A tunnel or playit.gg exists so you can skip the first of those (chapters 05 and 09).

A change could not be saved

The health board's Saved settings row names the file, and playport.log carries the full sentence. The two directions are different faults: a file that could not be read (a damaged settings.json, left where it is or kept aside) and a change that could not be written (a read-only file, a full disk, another program holding it). The panel records both rather than replacing a file it could not read with defaults - which is what used to make this silent.

What to send when you ask for help

The people who can actually answer have to reproduce what you saw. In order of value:

1. The diagnosis, as JSON - PlayPort.exe --diagnose <log> output, or the server's diagnose view with ?full=1. It carries the rule ids, the severities and the console lines that matched.
2. The server's own log - <data>/instances/<server>/console.log (and console.log.old if the failure rotated away).
3. The panel's log - playport.log from the data root. This is where an API failure's stack went: the response deliberately carries a plain sentence instead, so the log is the only place with the detail.
4. The health board - a screenshot or the JSON from GET /api/health, including the summary line.
5. The version - PlayPort.exe --version, both lines: the build, and whether the build's checks ran or were skipped.

Please do not send auth.json, databases.json or the mail credentials: the first two are the panel's keys to itself, and the third is other people's mail. The diagnosis and the two logs are enough for almost every fault in this chapter.

Files behind this chapter

Chapter 12. The module reference

The core plugin is one jar built out of modules, and chapter 08 explains what that means: each module has an id, a label, its own switch, its own config section, its own commands and its own <command> check. Appendix D in the top-level manual is the registry of all of them - the list /playport status prints, in the order it prints it.

That table answers which modules exist. This chapter answers the question a reader has next, module by module: what does this one do, how do I turn it on, and what can I tell it to do?

Every module has an entry on one of the pages below, and every entry answers those three questions in the same shape. The pages are grouped by what their modules have in common rather than by registry order, so read them as thematically related batches and use the table here (or /playport status) to find a module by id.

How to read an entry

Each entry is headed by the module's id and the label the plugin itself reports:

### `econ` - Economy, /pay, /sell and a salary for time played

The label is not decoration: it is the same string /playport status, the help menu and the panel's Plugins page show, so a heading you can search for in the manual is one you can search for in the product. Under it, three answers:

• What it does. The behaviour, in the terms a player and an operator would use - the commands a player sees, the thing that changes, and what the module is a replacement for where it replaces a plugin. Where a module does something an operator would not expect (a rule that only fires in PvP, a feature that needs a world of its own, a limit that is deliberately conservative), that is here.
• Turning it on. The switch - modules.<id>.enabled: true in config.yml - plus anything else the module needs before it does anything useful: a section you have to fill in, a world, a permission group, a first command that creates the content, or a profile that ships it switched on. A module that yields to an installed plugin (the yield table is in chapter 08) says so here, with the plugin it steps aside for.
• What you can configure. The keys, by their path in config.yml, with the values the shipped file has where the default is the interesting part. Where a module is a command with nothing to configure, the entry says that instead of inventing keys - "nothing to configure" is a fact about the module and worth knowing before you go looking.

Some entries add further labels when there is something more to say: Commands. with the usage, Permissions. with the nodes (see chapter 08 for how nodes reach groups), and Panel. where the panel gives the same content an editor of its own (the editors are in chapter 07).

Where a module's settings live. Almost always in a top-level section of pkg/config.yml named after the module - econ:, shop:, dungeons: - and the switch is not in that section but in the modules: block at the top of the same file. The small modules near the end of the registry (the batch that closed the last gaps against the reference plugins) are often a command and a handful of keys in a section of their own, and a few take their arguments on the command line and have no keys at all. Each entry tells you which it is.

Precedence is the one thing that applies to every module. An edit you make in config.yml wins over the profile, and the profile wins over the shipped defaults: config.yml starts as a complete copy of the defaults, so a line you have never touched does not block the profile. The full statement of that rule, with the profile: key, is in chapter 08.

The pages

Adding a module to the manual

The registry is generated, so half of this reference maintains itself and half does not - and it is worth knowing which is which when you add a module:

• pkg/src/ppcore/ModuleIndex.java is written by node config-audit.js off each module's own id() and label(), so a new module appears in /playport status and in Appendix D as soon as the table is regenerated. The manual's table block is generated from it too: node harness/gates/manual-gate.js --write rewrites the block, and harness/gates/manual-gate.js fails the build while the two disagree.
• The entry on one of the pages above is written by hand, and the same gate holds it to the registry: every module the registry names has exactly one entry, no entry names a module the registry does not have, each heading carries the registry's own label, and each entry answers the three questions. A module added without an entry fails the build with the module named - which is the point, because the alternative is a registry that lists a feature nobody wrote down.

Files behind this chapter

Server foundations - the modules every server switches on

These are the modules a server of almost any kind switches on: who a player is and what they may do (perms), money (econ), the everyday essentials (ess), land (claims), staff tools and chat, and the commands an operator types. Each one is a section of pkg/config.yml plus a switch in the modules: block at the top of it; chapter 12 explains that shape and the precedence rule that applies to all of them (your edit beats the profile, the profile beats the shipped defaults). The five switches to look at first are modules.econ.features.pay, modules.ess.*, server.afk.pause-salary, perms.groups and ranks.ladder - they are the ones a fresh install gets wrong in a way players notice.

perms - Groups and permissions (replaces a permissions plugin)

What it does. This module is the server's permission system: groups with a prefix, an inherits chain and a list of nodes, plus the ladder in ranks that hands a group out. It replaces a permissions plugin - a server running this does not need LuckPerms - and it is where every other module's node reaches a player. ppcore.perm.admin is the staff half (creating groups, editing them, reading somebody's effective nodes), and a node that no group grants is a finding in harness/gates/perm-gate.js, not a surprise in game.

Turning it on. modules.perms.enabled: true, which is the shipped default. It has nothing else to switch on, but it is the module you must configure first, because everything below it in this file is gated by the groups here: a fresh install whose default group omits a node is a feature that answers "you do not have permission" to every player. The staff group in the shipped file is the worked example of the whole surface.

What you can configure. perms.defaultGroup (the group a player is put in when nothing else says otherwise) and perms.groups.<name> with four keys per group: