A self-contained, bootable Palworld dedicated server that lives entirely on a USB drive, SSD, VM disk, or spare partition. Plug it in, boot from it, and you have a full Palworld server with a web management UI — no host OS install required.
Latest: v1.2.8. Debian 13 (Trixie), Secure Boot–signed GRUB, Docker Compose stack, WireGuard-based remote access, Wi-Fi onboarding hotspot.
- Plug-and-boot Wi-Fi setup — on first boot, if no network is configured,
PPSA serves a
PPSA-Setuphotspot so you can pick a Wi-Fi network from the Web UI (details) - Debian 13 (Trixie), booted directly from USB/SSD/VDI, or installed alongside an existing OS via the installer ISO (details)
- Docker Compose stack: Palworld game server, a FastAPI Web UI, WGDashboard (WireGuard peer management), an automated backup agent, and Watchtower
- UEFI Secure Boot support — signed shim + Debian-signed GRUB chain, no MOK enrollment needed (see Architecture)
- First-boot automation — installs and starts the whole stack unattended, auto-resizes the root partition to fill the disk
- WireGuard-gated remote access — game/Web UI/WGDashboard ports are reachable only over a WireGuard tunnel by default, not the open LAN/WAN (see Networking & firewall)
- Automatic backups (daily, cron'd) and automatic container updates (opt-in)
Grab the latest release from github.com/kaiser62/ppsa/releases:
| Asset | Use for |
|---|---|
ppsa-usb-vX.X.X.img.zst |
Physical USB / SSD (recommended) |
ppsa-vbox-vX.X.X.vdi.zst |
VirtualBox VM |
ppsa-installer-vX.X.X.iso.zst |
Installer ISO — installs PPSA onto a spare drive/partition without touching your existing OS (guide) |
*.sha256 |
Checksum for the matching asset |
Windows (Rufus):
- Decompress
ppsa-usb-vX.X.X.img.zstwith 7-Zip - Open Rufus → select your USB drive → SELECT → choose the
.imgfile - START → DD image mode (not ISO mode) → OK → OK
- Wait for the write to finish, then eject safely
Linux / macOS:
zstd -d ppsa-usb-vX.X.X.img.zst
sudo dd if=ppsa-usb-vX.X.X.img of=/dev/sdX bs=4M status=progress conv=fsync
sync- Plug the USB into the target machine, power on, and enter the boot menu (F12 / F2 / DEL, depends on the BIOS)
- Select the USB device — GRUB auto-boots into PPSA
- Log in at the console with
ppsa/ppsa(see default credentials) - First boot runs unattended in the background — the console shows live progress
First boot takes a few minutes (pulling Docker images and the Palworld Steam update, ~4 GB). Once it's done, the console prints the Web UI URL. Open it from a machine that can reach the PPSA host — by default that means the same WireGuard network, not plain LAN (see Networking & firewall for why, and how to connect over WireGuard).
Default login: admin / admin — change this on the Settings tab immediately.
zstd -d ppsa-vbox-vX.X.X.vdi.zst- Machine → New → Type Linux, Version Debian (64-bit)
- Memory: 4 GB minimum (8 GB recommended), 2+ CPUs
- Use an existing virtual hard disk file → select the extracted
.vdi - System → Enable EFI (recommended — matches the Secure Boot chain used on real hardware; legacy BIOS also works)
- Start the VM
First boot behaves identically to physical hardware.
By default, nothing except SSH and the WireGuard tunnel itself is reachable from your LAN or the internet. The game server, Web UI, and WGDashboard are only reachable from clients connected to the PPSA's WireGuard network. This means you can hand a WireGuard config to a friend and they can reach your server from anywhere, without opening a single port on your router. Full details, including the opt-in build flag to also expose SSH on the LAN, are in docs/architecture.md.
- docs/architecture.md — boot chain, Docker stack, networking/firewall model
- docs/installation.md — all install paths (USB, VirtualBox, dual-boot installer, bare metal)
- docs/deployment-guide.md — end-to-end deployment walkthrough with reference detail
- docs/dual-boot-install.md — installer ISO: install PPSA on a spare drive/partition
- docs/wifi-onboarding.md — the
PPSA-SetupWi-Fi hotspot - docs/wireguard-setup.md — WireGuard auto-registration, hosting your own hub, player onboarding
- docs/troubleshooting.md — common issues and fixes
- docs/local-builder.md — the PowerShell local CI/CD builder (fast local iteration without waiting on GitHub Actions)
- CLAUDE.md — contributor/agent-facing build & architecture notes
| User | Password | Where to change |
|---|---|---|
ppsa (SSH) |
ppsa |
passwd ppsa (sudo) |
artho (SSH, port 10022) |
arthoroy |
passwd artho (sudo) |
admin (Web UI) |
admin |
Web UI → Settings tab |
| Palworld admin (in-game) | changeme |
Web UI → Config tab |
Images are built by GitHub Actions, not locally — see docs/architecture.md for why and how the pipeline is structured.
# Real release: push a version tag. build-release.yml and build-installer.yml
# both fire automatically and publish a GitHub Release with all three assets.
git tag v1.3.0 && git push origin v1.3.0
# Manual test build (does NOT publish a release, uploads a workflow artifact):
gh workflow run build-release.yml -f version=v1.3.0-test
gh workflow run build-installer.yml -f version=v1.3.0-test.
├── scripts/
│ ├── build-live-usb.sh # Image builder (debootstrap + chroot + GRUB)
│ ├── install.sh # First-boot: docker pull + up, firewall, WireGuard
│ ├── ppsa-firewall-apply.sh # Rebuilds the WG_FRIENDS iptables chain
│ ├── ppsa-wireguard-register.sh # Auto-registers as a wg-easy peer
│ └── ppsa-wifi-onboard.sh # PPSA-Setup hotspot for first-time Wi-Fi setup
├── compose/
│ ├── docker-compose.yml # Main stack (palworld, webui, wgdashboard, backup, watchtower)
│ └── docker-compose.monitoring.yml # Optional Prometheus + Grafana overlay
├── docker/webui/ # The only live WebUI code (FastAPI + vanilla JS)
├── installer/ # live-build config for the dual-boot installer ISO
├── modules/ # PowerShell modules for the local CI/CD builder
├── docs/ # Documentation (see above)
└── .github/workflows/
├── build-release.yml # CI: build USB img + VBox VDI, release on tag push
└── build-installer.yml # CI: build installer ISO, attaches to the same release
Semantic version tags (vX.Y.Z) are the only thing that publishes a public
release. Each release includes the raw USB image, the VirtualBox disk, and the
installer ISO. See the Releases page
for the full history and changelogs.
- Change all default passwords before exposing PPSA to any network
- By default, only SSH and the WireGuard tunnel ports are open on the LAN/WAN — the game server, Web UI, and WGDashboard are WireGuard-only (see Networking & firewall)
- Web UI uses JWT tokens (24h expiry)
.env(secrets) is git-ignored and never baked into the image
Report security issues via GitHub Issues (mark as security).
MIT — see LICENSE.
- Palworld server:
thijsvanloef/palworld-server-docker - WGDashboard:
wgdashboard/wgdashboard - Backup agent:
offen/docker-volume-backup - Watchtower:
containrrr/watchtower - wg-easy:
wg-easy/wg-easy - Base OS: Debian 13 (Trixie)