Docker - Palworld Dedicated Server

This Docker image includes a Palworld Dedicated Server based on Linux and Docker.

[!TIP] Do you want to chat with the community?

Join us on Discord

[!WARNING] Heads-up — RCON has been removed. This image no longer uses RCON for any container tooling. All server management (player detection, backups, restarts, CLI) now runs via the Palworld REST API.

• RCON_ENABLED now defaults to false — this only controls the game server INI setting, not container functionality.
• Make sure RESTAPI_ENABLED=true is set in your default.env.
• See the Changelog for the full migration guide and renamed environment variables.

[!CAUTION] Public Service Announcement — Custom Script Feature

After many community requests, this image now supports running a custom script before the server starts. This feature is entirely opt-in and is controlled by the CUSTOM_SCRIPT_ENABLED environment variable, which defaults to false.

This image will never ship with a custom script of any kind.

If you come across a Docker image that appears to be this one but includes a bundled custom script, please be careful — it is not this image and I have no affiliation with it.

This feature was added at the request of the community. While I am glad to offer the option, I will not be providing support for it, and I refuse to accept any liability for any harm, data loss, corruption, or security issues that may result from its use. Please use it at your own discretion. — Public Service Announcement.

Table of Contents

• Docker - Palworld Dedicated Server
  • Table of Contents
  • How to ask for support for this Docker image
  • Requirements
  • Minimum system requirements
  • Changelog
  • Credits / Shoutout / Contributions
  • Getting started
  • Environment variables
  • Docker-Compose examples
    • Gameserver with REST API
  • Run REST API commands
    • Administration commands
    • Diagnostics & data commands
  • Backup Manager
  • Webhook integration
    • Supported events
  • Companion sidecar: web panel & Discord status card
  • Deploy with Helm
  • FAQ
    • Does this image support Xbox Dedicated Servers?
    • How can I use the interactive console in Portainer with this image?
    • How can I look into the config of my Palworld container?
    • I'm seeing S_API errors in my logs when I start the container?
    • I'm using Apple silicon type of hardware, can I run this?
    • I changed the BaseCampWorkerMaxNum setting, why didn't this update the server?
    • How does the random part of the default server name work?
  • Planned features in the future
  • Software used

How to ask for support for this Docker image

If you need support for this Docker image:

• Feel free to create a new issue.
  • You can reference other issues if you're experiencing a similar problem via #issue-number.
• Follow the instructions and answer the questions of people who are willing to help you.
• Once your issue is resolved, please close it and please consider giving this repo and the Docker-Hub repository a star.
• Please note that any issue that has been inactive for a week will be closed due to inactivity.

Please avoid:

• Reusing or necroing issues. This can lead to spam and may harass participants who didn't agree to be part of your new problem.
• If this happens, we reserve the right to lock the issue or delete the comments, you have been warned!

Requirements

To run this Docker image, you need a basic understanding of Docker, Docker-Compose, Linux, and Networking (Port-Forwarding/NAT).

Minimum system requirements

Changelog

You can find the changelog here

Credits / Shoutout / Contributions

This 2 persons helped a lot along to way and made me and this project better! So if you do not like my version of the Docker image or looking for other features, feel free to check out the following 2 images:

• @thejcpalma - https://github.com/thejcpalma/palworld-dedicated-server-docker - https://hub.docker.com/r/thejcpalma/palworld-dedicated-server - ❤️🫡
• @thijsvanloef - https://github.com/thijsvanloef/palworld-server-docker - https://hub.docker.com/r/thijsvanloef/palworld-server-docker - ❤️🫡

Getting started

1. Create a game sub-directory on your Docker-Node in your game-server-directory
   • (Examples: /srv/palworld, /opt/palworld or /home/username/palworld)
   • This directory will be used to store the game server files, including configs and savegames
   • In older versions we asked you to setup permissions via CHMOD or CHOWN, this should not be needed anymore!
2. Set up Port-Forwarding or NAT for the ports in the Docker-Compose file
3. Pull the latest version of the image with docker pull jammsen/palworld-dedicated-server:latest
4. Download the compose.yml and default.env
5. Set up the compose.yml and default.env to your liking
   • Make sure you setup PUID and PGID according to the user you want to use
     • PUID and PGID 0 will error out, thats on purpose!
     • if you use Docker as root, then you can just use 1000 inside the container
   • Refer to the Environment-Variables section for more information
6. Start the container via docker-compose up -d && docker-compose logs -f
   • Watch the log, if no errors occur you can close the logs with ctrl+c
7. Now have fun and happy gaming! 🎮😉

Environment variables

See the environment variables documentation

Docker-Compose examples

Gameserver with REST API

services:
  palworld-dedicated-server:
    container_name: palworld-dedicated-server
    image: jammsen/palworld-dedicated-server:latest
    restart: unless-stopped
    logging:
      driver: "local"
      options:
        max-size: "10m"
        max-file: "3"
    ports:
      - target: 8211 # Gamerserver port inside of the container
        published: 8211 # Gamerserver port on your host
        protocol: udp
        mode: host
      - target: 8212 # Gameserver API port inside of the container
        published: 8212 # Gameserver API port on your host
        protocol: tcp
        mode: host
      - target: 25575 # RCON port inside of the container
        published: 25575 # RCON port on your host
        protocol: tcp
        mode: host
    env_file:
      - ./default.env
    environment:
      # Read-only view of the companion's data dir - settings-overrides.env
      # written by the web panel is applied from there at boot
      COMPANION_DATA_DIR: /companion-data
    volumes:
      - ./game:/palworld
      - ./companion:/companion-data:ro

  # Companion sidecar: web operation panel + Discord status card & bot.
  # Disabled by default - it idles until you enable PANEL_ENABLED and/or
  # DISCORD_STATUS_ENABLED in default.env (ALL companion variables live there,
  # in the "Companion-sidecar-settings" section).
  # Docs: https://github.com/jammsen/docker-palworld-companion
  companion:
    container_name: palworld-companion
    # develop tag during the testing grace period - switches to latest with
    # the companion's first stable release
    image: jammsen/palworld-companion:develop
    restart: unless-stopped
    depends_on:
      - palworld-dedicated-server
    ports:
      # (Needs: PANEL_ENABLED=true)
      # Warning! DO NOT expose this port to the internet, use a reverse proxy or VPN/LAN only
      - target: 8213 # Web panel port inside of the container
        published: 8213 # Web panel port on your host
        protocol: tcp
        mode: host
    env_file:
      - ./default.env
    environment:
      RESTAPI_HOST: palworld-dedicated-server
      COMPANION_DATA_DIR: /data
    volumes:
      - ./game:/palworld:ro
      - ./companion:/data

Run REST API commands

[!NOTE] Please research the REST API commands on the official source: https://docs.palworldgame.com/category/rest-api

You can use docker exec palworld-dedicated-server restapicli <command> right on your terminal/shell.

Administration commands

Day-to-day server and player management — announcements, moderation, quick lookups, saving and shutdown.

$ docker exec palworld-dedicated-server restapicli announce "Hello players!"
> Announced: Hello players!

$ docker exec palworld-dedicated-server restapicli ban steam_76000000000000123 "You are banned."
> Banned: steam_76000000000000123

$ docker exec palworld-dedicated-server restapicli banlist
> Ban list (2 entries):
steam_76000000000000123
steam_76000000000000456

$ docker exec palworld-dedicated-server restapicli info
> Server info: {"version": "v0.7.3.90464", "servername": "...", ...}

$ docker exec palworld-dedicated-server restapicli kick steam_76000000000000123 "Goodbye!"
> Kicked: steam_76000000000000123

$ docker exec palworld-dedicated-server restapicli players
> Players: {"players": [...]}

$ docker exec palworld-dedicated-server restapicli save
> Saving world...
> World saved.

$ docker exec palworld-dedicated-server restapicli shutdown 60 "Server restarting soon"
> Shutting down server in 60s...
> Shutdown issued.

$ docker exec palworld-dedicated-server restapicli unban steam_76000000000000123
> Unbanned: steam_76000000000000123

Diagnostics & data commands

Read-only raw JSON dumps of server state — from a quick metrics overview up to a full world actor snapshot.

$ docker exec palworld-dedicated-server restapicli metrics
> Metrics: {"currentplayernum": 1, "serverfps": 120, ...}

$ docker exec palworld-dedicated-server restapicli settings
> Settings: {"Difficulty": "None", "DayTimeSpeedRate": 1.0, ...}

$ docker exec palworld-dedicated-server restapicli gamedata
> Game data: {"Time": "2026-07-13 21:26:54", "FPS": 118.77, "InGameTime": "14:03", "ActorData": [...]}
# Warning: snapshot of ALL world actors - output can be huge, pipe it to jq or a file
# Note: Needs GAMEDATA_API_ENABLED=true, which starts the server with the
# -enable-gamedata-api launch option. See the example output below and the
# official endpoint documentation:
# https://docs.palworldgame.com/api/rest-api/game-data

{
  "Time": "2026-07-13 21:26:54",
  "FPS": 118.77287292480469,
  "AverageFPS": 118.79257965087891,
  "InGameTime": "14:03",
  "InGameDays": 4,
  "ActorData": [
    {
      "Type": "Character",
      "InstanceID": "4DCC09FB000000000000000000000000 : 0487098280F5417DB596B73ED985A5BC",
      "UnitType": "Player",
      "NickName": "jammsen123",
      "TrainerInstanceID": "",
      "TrainerNickName": "",
      "TrainerClass": "",
      "userid": "steam_XXXXXXXXXXXXXX123",
      "ip": "1.2.3.4",
      "level": 2,
      "HP": 1,
      "MaxHP": 500,
      "GuildID": "06362322142040BFBBC718C816B49E6D",
      "GuildName": "Unnamed Guild",
      "Class": "BP_Player_Female_C",
      "Action": "",
      "AI_Action": "",
      "LocationX": -357583.59375,
      "LocationY": 268633.40625,
      "LocationZ": 7951.2998046875,
      "RotationX": 0,
      "RotationY": 0,
      "RotationZ": 68.5,
      "Stage": "None",
      "IsActive": "true"
    },
    {
      "Type": "Character",
      "InstanceID": "00000000000000000000000000000000 : 0CCB7376B14641599BB08EA339FED55E",
      "UnitType": "NPC",
      "NickName": "Scouting Party Survivor",
      "level": 22,
      "HP": 1211,
      "MaxHP": 1211,
      "Class": "BP_NPC_Female_Soldier_C",
      "Action": "BP_Action_NPC_GroundSit",
      "AI_Action": "BP_AIAction_NPC_Relax_GroundSit",
      ...
    },
    {
      "Type": "Character",
      "InstanceID": "00000000000000000000000000000000 : 8B1215C3C7D546AB83D4E647BC1AA421",
      "UnitType": "WildPal",
      "NickName": "Lamball",
      "level": 2,
      "HP": 585,
      "MaxHP": 585,
      "Class": "BP_SheepBall_C",
      "AI_Action": "BP_AIAction_WildLife",
      ...
    },
    ...
  ]
}

Backup Manager

[!WARNING] If RESTAPI_ENABLED is set to false, the backup manager will not announce backup start/success/failure in-game and will not trigger a world save before creating a backup. This means that the backup will be created from the last auto-save of the server. This can lead to data-loss and/or savegame corruption.

Recommendation: Please make sure that RESTAPI_ENABLED=true is set before using the backup manager.

[!WARNING] Please use in the following part always the --user steam option or your files will be written as root

Usage: docker exec --user steam palworld-dedicated-server backup [command] [arguments]

Examples:

$ docker exec --user steam palworld-dedicated-server backup create
>>> Backup 'saved-20240203_032855.tar.gz' created successfully

$ docker exec --user steam palworld-dedicated-server backup list
>>> Listing 2 backup file(s)!
2024-02-03 03:28:55 | saved-20240203_032855.tar.gz
2024-02-03 03:28:00 | saved-20240203_032800.tar.gz

$ docker exec --user steam palworld-dedicated-server backup clean 3
>>> 1 backup(s) cleaned, keeping 2 backup(s).

$ docker exec --user steam palworld-dedicated-server backup list 1
>>> Listing 1 out of 2 backup file(s).
2024-02-03 03:30:00 | saved-20240203_033000.tar.gz

Webhook integration

To enable webhook integrations, you need to set the following environment variables in the default.env:

WEBHOOK_ENABLED=true
WEBHOOK_URL="https://your.webhook.url"

After enabling the server should send messages in a Discord-Compatible way to your webhook url.

You can find more details about these variables in the webhook settings in ENV_VARS.md.

Supported events

• Server starting
  • This even is not server started. Just add like 5 seconds on top and the server is online
• Server stopped
• Server updating
• Server updating and validating

Companion sidecar: web panel & Discord status card

The web operation panel (dashboard, player moderation, settings editor with persistence, one-click restart) and the Discord live status card (one message, edited in place with live server stats and an event log) live in their own repo and run as an optional sidecar container next to this image:

jammsen/docker-palworld-companion - image: jammsen/palworld-companion:develop (until the first stable release)

The companion is part of the compose example and disabled by default - it starts alongside the gameserver and idles until you enable a feature. Your server directory looks like this:

.
├── companion    # companion data dir (created on first start)
├── compose.yml  # both services
├── default.env  # ALL variables for both services, in one file
└── game         # game data dir

Enabling it is done entirely in default.env, in the Companion-sidecar-settings section: set PANEL_ENABLED=true plus a PANEL_PASSWORD for the web panel, and/or DISCORD_STATUS_ENABLED=true for the Discord card - then docker compose up -d again. RESTAPI_ENABLED=true and ADMIN_PASSWORD (already in the file) are required - the companion talks to this image through the REST API and two shared volume mounts.

Full documentation:

• README with screenshots
• every variable (ENV_VARS.md)
• Discord bot mode walkthrough
• icon sets for the Discord card.

Security warning: The panel speaks plain HTTP - do NOT publish port 8213 to the internet. Use it LAN/VPN-only or put a TLS reverse proxy (Caddy, Traefik, nginx) in front.

Deploy with Helm

A Helm chart to deploy this container can be found at palworld-helm.

FAQ

Does this image support Xbox Dedicated Servers?

Yes just change the value from ALLOW_CONNECT_PLATFORM from Steam to Xbox. See here for more documentation: https://tech.palworldgame.com/getting-started/for-xbox-dedicated-server

How can I use the interactive console in Portainer with this image?

You can run this `docker exec -ti palworld-dedicated-server bash' or you could navigate to the "Stacks" tab in Portainer, select your stack, and click on the container name. Then click on the "Exec console" button.

How can I look into the config of my Palworld container?

You can run this docker exec -ti palworld-dedicated-server cat /palworld/Pal/Saved/Config/LinuxServer/PalWorldSettings.ini and it will show you the config inside the container.

I'm seeing S_API errors in my logs when I start the container?

Errors like [S_API FAIL] Tried to access Steam interface SteamUser021 before SteamAPI_Init succeeded. are safe to ignore.

I'm using Apple silicon type of hardware, can I run this?

You can try to insert in your docker-compose file this parameter platform: linux/amd64 at the palworld service. This isn't a special fix for Apple silicon, but to run on other than x86 hosts. The support for arm exists only by enforcing x86 emulation, if that isn't to host already. Rosetta is doing the translation/emulation.

I changed the BaseCampWorkerMaxNum setting, why didn't this update the server?

This is a confirmed bug. Changing BaseCampWorkerMaxNum in the PalWorldSettings.ini has no effect on the server. There are tools out there to help with this, like this one: https://github.com/legoduded/palworld-worldoptions

[!WARNING] Adding WorldOption.sav will break PalWorldSetting.ini. So any new changes to the settings (either on the file or via ENV VARS), you will have to create a new WorldOption.sav and update it every time for those changes to have an effect.

How does the random part of the default server name work?

If SERVER_NAME contains ###RANDOM### (the default), it is replaced with a random 6-character token so your server does not collide with every other unconfigured server in the browser list. The token is generated once and persisted in server-name.token in your game volume - your server keeps its name across restarts and container re-creation. Delete that file to roll a new token on the next start, or set a real SERVER_NAME to opt out entirely.

Planned features in the future

• Feel free to suggest something. Under Issues there is a Feature Request issue-type.

Software used

• CM2Network SteamCMD - Debian-based (Officially recommended by Valve - https://developer.valvesoftware.com/wiki/SteamCMD#Docker)
• Node.js 22 + Hono - companion service (web panel and Discord status card)
• Supercronic - https://github.com/aptible/supercronic
• jq - https://jqlang.org/
• Palworld Dedicated Server (APP-ID: 2394010 - https://steamdb.info/app/2394010/config/)