Palbox — Palworld Server Manager

Manage, Monitor. Master Your World.

Self-hosted ops panel for your Palworld dedicated server(s).

---

Screenshots

Dashboard	Metrics
Players & Moderation	Backups
Server Build & Updates	Mods (UE4SS)
Live Console	Cluster Overview
Audit Log	Settings

---

Which installer do I need?

┌─────────────────────────────────────────────────────────────────────┐
│  Running Palworld on a Windows VPS / dedicated server?              │
│  → Use Option B (server ZIP).  Access the panel via your browser.  │
│                                                                     │
│  Want a native desktop app on your PC / laptop to manage a server? │
│  → Use Option A (desktop installer).                                │
└─────────────────────────────────────────────────────────────────────┘

Do NOT install the desktop .exe on your VPS. Electron is a full Chromium browser process — it requires a GPU-capable desktop session, consumes significant RAM, and stops working when you disconnect from RDP. The headless server package is the correct choice for any server environment.

---

Installation

Option A — Desktop installer (your PC / laptop)

Install on the machine you manage from, not the server itself.
Go to the Releases page:

File	Platform
Palbox-Setup-vX.Y.Z-windows.exe	Windows — NSIS guided installer
Palbox-vX.Y.Z-mac-arm64.dmg	macOS — native on Apple Silicon, works on Intel via Rosetta 2
Palbox-vX.Y.Z-linux-x64.AppImage	Linux — portable, no install required
Palbox-vX.Y.Z-linux-x64.deb	Linux — Debian/Ubuntu package

Windows: Node.js 22 is automatically detected and installed if missing.
macOS: Right-click → Open if macOS warns about an unverified developer.
Linux (AppImage): chmod +x Palbox-*.AppImage && ./Palbox-*.AppImage

The desktop app embeds its own API server and opens the panel in a native window.
Point it at your remote Palworld server via Settings after first launch.

---

Option B — Headless server package (Windows VPS / dedicated server)

1. Download palbox-server-vX.Y.Z.zip from Releases and extract it.
2. Open PowerShell as Administrator inside the extracted folder:

   .\Install-Palbox.ps1

3. Follow the prompts — the script installs Node.js 22 LTS if needed, writes .env, and registers a Windows service via NSSM.

Requirements:

• Windows 10 / Server 2019 or newer
• NSSM — place nssm.exe on your PATH
• Node.js 22+ (auto-installed by the script if absent)

After setup the panel is available at http://<your-vps-ip>:4000 from any browser.
Open that URL on your PC / phone — no desktop session on the VPS needed.

Firewall: open port 4000 (TCP inbound) in Windows Firewall and your hosting provider's network rules.

---

Option C — Build from source

git clone <repo>
cd Palbox-Manager
npm install
cp .env.example api/.env
# Edit api/.env with your server details
npm run dev          # http://localhost:5173 (dev proxy)

For production, build then register as a service:

npm run build
nssm install PalboxAPI "C:\Program Files\nodejs\node.exe" "C:\Palbox\api\dist\index.js"
nssm set PalboxAPI AppDirectory C:\Palbox\api
nssm set PalboxAPI AppEnvironmentExtra "DOTENV_CONFIG_PATH=C:\Palbox\.env"
nssm start PalboxAPI

---

Upgrading

Server package — in-panel (recommended)

Open the panel in your browser and go to Settings → Panel updates.
If a newer version is available you'll see an Apply Update button.
Click it — Palbox downloads the new release, registers a Windows Scheduled Task that runs outside the service process tree, and automatically stops + restarts the PalboxAPI service. The panel comes back online within ~30 seconds.

Check C:\Palbox\palbox-update.log if anything goes wrong.

Server package — manual fallback

nssm stop PalboxAPI
# Extract the new palbox-server-*.zip over your install directory
# (api-dist/, node_modules/, ui-dist/ are replaced; .env is untouched)
nssm start PalboxAPI

Desktop installer: Re-run the new Palbox-Setup-*.exe — it will upgrade in place.

---

Features

Phase 1 (core)

Feature	Details
Authentication	Username + password + optional TOTP 2FA, JWT cookie
Server control	Start / Stop / Restart / Save via NSSM + RCON
Live console	Captured server output plus a Palbox event feed over WebSocket, send RCON commands
Backups	Manual & scheduled .zip archives, rolling retention, restore
SteamCMD updates	Steam API polling, one-click update with RCON warning
Settings editor	Form + raw INI modes for PalWorldSettings.ini
Mods (UE4SS)	List / enable / disable / upload / remove mods
Player roster	View history, kick / ban / unban, whitelist
Discord webhooks	Per-event notifications

Phase 2 (advanced)

Feature	Details
Multi-server	Add any number of instances; sidebar switcher changes active server
Watchdog	RCON heartbeat every 30 s, grace period, auto-restart if offline
Player join/leave events	Detected via ShowPlayers diff, stored in DB, Discord notified
Scheduled restarts	Daily / 12 h / Weekly cron, configurable time + timezone + warn
Historical metrics	Up to 30 days of player / CPU / memory data charted
RCON Macros	Named command presets, run with one click
Timed Broadcasts	Recurring in-game messages on a cron schedule
Alert Rules	CPU / memory / player-count / status thresholds → Discord
Chat Log	Live server log viewer
Player Profiles	Notes, tags, playtime history per player
Audit Log	All admin actions recorded
World Overview	Key settings parsed from PalWorldSettings.ini
World Map	Live player positions on the in-game map, projected with the community-calibrated transform
Guilds & base camps	Read straight out of Level.sav, including offline members and claimed territory
Pal Browser	Every Pal in the world with icons, elements, IVs, passives and owner, filterable and sortable
Pal spawning	Give a Pal to a player or drop one on the map — needs PalDefender
Base Camp Inspector	Click a camp on the map for its workers, their sanity and health, and where its work coverage has gaps
Scheduled events	Timed rate changes such as a double XP weekend, applied and reverted automatically — costs two restarts
Multi-user accounts	Owner / Operator / Viewer roles with JWT auth
Two-factor auth	TOTP (Google Authenticator / Authy) via QR code
Maintenance mode	RCON broadcast warnings + whitelist lockdown
Uptime tracker	SLA %, outage count, status timeline
Player notes & tags	Custom colour-tagged labels per player
Cluster view	Single-page grid of all instances with live metrics
Palworld REST API	Proxy to the game's built-in HTTP API (port 8212)
Color themes	Violet / Emerald / Ocean / Crimson / High Contrast

---

Architecture

Palbox-Manager/
├── api/          Express + TypeScript backend  (port 4000)
├── ui/           React + Vite SPA              (proxied in dev, static in prod)
├── electron/     Desktop shell — runs on your local PC/laptop, NOT on the server
└── scripts/      Install-Palbox.ps1, Uninstall-Palbox.ps1

All three packages are npm workspaces.

Deployment model:

Windows VPS (Palworld + Palbox API)        Your browser (anywhere)
┌──────────────────────────────────┐       ┌────────────────────────────┐
│  palbox-server.zip               │       │  http://<vps-ip>:4000      │
│  ├─ Node.js API  :4000           │◄─────►│  Chrome / Firefox / Edge   │
│  └─ NSSM service (always-on)     │       └────────────────────────────┘
└──────────────────────────────────┘

Your PC / laptop (optional desktop app)
┌──────────────────────────────────┐
│  Palbox-Setup-*.exe              │
│  └─ Electron window + local API  │──► manages a remote Palworld server
└──────────────────────────────────┘

---

CI / CD

Workflow	Trigger	What it does
ci.yml	Push / PR to main	Builds UI + API + type-checks Electron
release.yml	Push of a v*.*.* tag	Builds both artifacts, creates a GitHub Release

To publish a release:

git tag v1.0.0
git push origin v1.0.0

GitHub Actions will build and attach:

• Palbox-Setup-1.0.0.exe (Electron NSIS installer)
• palbox-server-1.0.0.zip (headless server package)

---

Multi-server support

Palbox can manage multiple Palworld instances on the same VPS (or different ports).

1. Start Palbox — it seeds a Default instance from your .env values.
2. Open Settings → Instances → Add server to create more.
3. Each instance stores its own: service name, paths, RCON port, backup dir.
4. Use the server picker in the sidebar to switch — every view updates.

---

Environment variables reference

See .env.example for the full list. Variables for the default instance are seeded into the instances table on first boot; you can change paths later via the Settings UI.

---

Save file compatibility

Palworld 1.0 changed two things about Level.sav, and Palbox handles both automatically — there is nothing to configure:

• Compression. 1.0 writes an Oodle/Kraken container (PlM) instead of the older zlib one (PlZ). Oodle is proprietary, so Palbox decodes it with ooz-wasm, an open source reimplementation compiled to WebAssembly.
• Guild layout. 1.0 inserted two fields into the guild struct. Palbox reads a save with both layouts and keeps whichever one decodes it cleanly, so pre-1.0 worlds still work.

This affects the World Map overlay and the Pal Browser, the features that read the save directly. Everything else runs off the REST API.

---

Spawning Pals

Vanilla Palworld has no command for spawning a Pal — not over RCON, and not in the REST API. The Spawn tab therefore drives PalDefender, which adds givepal and spawnpal to RCON.

Palbox detects this by asking the server for its command list, so the tab explains what is missing rather than offering a button that does nothing. With the mod installed you can hand a Pal straight to an online player, or place one at a point on the map using the same coordinates the in-game map shows.

pals.spawn is deliberately not granted to the Operator role: handing out Pals rewrites a server's economy. An owner can grant it per role under Users & Roles.

---

Scheduled events

An event is a window of time during which some PalWorldSettings.ini values are replaced — double experience over a weekend, a capture rush, faster egg hatching — after which the originals are put back.

This costs two server restarts. Palworld reads its settings once, at boot, and neither RCON nor the REST API can change a rate on a running server. So the panel warns players, saves the world, and restarts when the window opens, then does the same when it closes. The warning period is per-event.

The values displaced at the start are recorded on the event and restored verbatim at the end, so an event never resets a setting to a stock default that the server was not already using. Only rate and rule settings can be driven this way; ports, passwords and the server name are rejected, since an event changing those would lock players out.

Windows are evaluated once a minute rather than fired by a timer at the boundary, which means a panel that was restarted or offline across a boundary still ends up in the right state. One event runs at a time; overlapping windows queue rather than fight over the same setting. If the server is stopped when a window opens, the new settings are written and take effect whenever it next starts — nothing is booted up behind you.

---

License

GPL-3.0-or-later.

Palbox links ooz-wasm to read Palworld 1.0 saves, which is GPL-3.0-or-later, so the panel as a whole is distributed under the same terms.

The Palpagos Island map texture and the Pal icons in ui/public/ are game artwork owned by Pocketpair, included for in-panel display only. The Pal reference table in api/src/data/paldex.json is likewise extracted game data. Both are regenerated by scripts/build-paldex.mjs from the tables published by palworld-save-pal, which keys them on the same internal ids the save uses.