PhValheim Server

The Valheim world and mod manager that keeps everyone in sync.

Modding Valheim is easy. Keeping mods perfectly in sync across your server and every player? Nearly impossible. Mod managers like Thunderstore work great individually, but they don't coordinate across a group — eventually someone's client drifts out of sync and the session breaks.

PhValheim is a two-part system (server + client) that locks server and client mod configurations together. Deploy worlds with any combination of Thunderstore and Hexium mods, and every player automatically gets the exact same files when they connect. No more "which version do you have?" conversations.

Not every world needs mods, though. PhValheim also hosts vanilla worlds — stock Valheim, zero mods, joined with the ordinary Valheim client — so you can run plain servers alongside your modded ones without managing a second stack.

services:
  phvalheim:
    image: theoriginalbrian/phvalheim-server:latest
    container_name: phvalheim
    ports:
      - "8080:8080/tcp"    # Public UI
      - "8081:8081/tcp"    # Admin UI (do NOT expose publicly)
      - "25000-26000:25000-26000/udp"  # Game ports
    volumes:
      - /path/to/data:/opt/stateful:Z
      - /path/to/backups:/opt/stateful/backups:Z   # ideally a separate disk
    restart: unless-stopped

That's it. Start the container and open http://your-host:8081 — the Setup Wizard will walk you through configuration.

docker create \
  --name phvalheim \
  -p 8080:8080/tcp \
  -p 8081:8081/tcp \
  -p 25000-26000:25000-26000/udp \
  -v /path/to/data:/opt/stateful:Z \
  -v /path/to/backups:/opt/stateful/backups:Z \
  theoriginalbrian/phvalheim-server:latest

docker start phvalheim

Search for PhValheim in the Community Apps store.

A Helm chart is included in the repo at helm/phvalheim/.

# Minimal install
helm install phvalheim ./helm/phvalheim/

# With Ingress for the public UI
helm install phvalheim ./helm/phvalheim/ \
  --set ingress.public.enabled=true \
  --set ingress.public.hosts[0].host=phvalheim.example.com \
  --set ingress.public.hosts[0].paths[0].path=/ \
  --set ingress.public.hosts[0].paths[0].pathType=Prefix

# With an existing PVC
helm install phvalheim ./helm/phvalheim/ \
  --set persistence.data.existingClaim=my-phvalheim-pvc

How it works:

• The pod runs with hostNetwork: true by default so Valheim's UDP game ports (25000-26000) bind directly to the node — no NodePort or LoadBalancer gymnastics required.

• Two ClusterIP Services are created: one for the public UI (8080) and one for the admin UI (8081). Each has an optional Ingress resource (disabled by default).

• A 20Gi PersistentVolumeClaim is created for /opt/stateful. An optional separate PVC for backups can be enabled with persistence.backups.enabled=true.

• Without Ingress enabled, access the admin UI via port-forward to run the Setup Wizard:

  kubectl port-forward svc/phvalheim-admin 8081:8081
  # Then open http://localhost:8081

See helm/phvalheim/values.yaml for the full set of configurable values.

All settings are configured through the Admin UI after first launch. No environment variables are needed for new installations.

Upgrading from an older version? Your existing environment variables will be automatically migrated to the database on first boot. A one-time migration notice will confirm the imported values.

PhValheim includes a full backup system with activity-aware scheduling, compression, tiered retention, and one-click restore.

Mount a separate volume for backups to keep them isolated from game data:

volumes:
  - /path/to/data:/opt/stateful:Z
  - /path/to/backups:/opt/stateful/backups:Z   # separate disk recommended

If no dedicated backup volume is detected, the admin UI will display a warning and automatic backups are disabled. Manual backups can still be created.

Disk space note: Compression requires temporary space for both the uncompressed tar and the compressed output (~2x world size). If insufficient space is available, the backup is saved uncompressed with a warning.

Backups are pruned automatically using a tiered retention policy. Manual backups are never auto-pruned.

These settings control how aggressively backup operations use system resources. Lower priority = less impact on active players.

Each world can override the global backup settings. In the world settings modal, switch to the Backups tab and uncheck Use Global Defaults to configure per-world intervals, retention, compression, and performance settings.

Restoring a backup replaces the current world directory with the backup contents:

1. A pre-restore safety backup is created automatically (unless disk space is insufficient).
2. The current world directory is cleared.
3. The backup is extracted. Legacy backups (pre-2.38) are detected and extracted to the correct path.
4. File ownership is fixed and the world is set to rebuild on next engine cycle.
5. The world process is restarted.

Restores are blocked while a world is in a transitional state (starting, stopping, updating, etc.).

On startup, PhValheim reconciles backup records with files on disk:

• Orphaned records: DB entries pointing to missing files are flagged as orphaned.
• Untracked files: Backup files on disk with no DB record are discovered and imported.
• Recovery: If an orphaned file reappears (e.g., backup volume remounted), the orphan flag is cleared.

Orphaned records are shown in the dashboard Storage card and in the per-world backup table. Use the Clean up button to purge orphaned records.

PhValheim reads mods from Thunderstore and Hexium. Both are enabled by default and a world can use either or both; search results show a coloured pill for each mod's origin (Thunderstore blue, Hexium purple).

Disabling a catalogue hides its mods from the picker but does not remove mods a world has already selected.

Version pinning. Every published version of every mod is stored, not just the newest. Select a mod and pick a version from the dropdown in its row to freeze it there; Latest (auto) keeps following new releases. A pinned version is kept in the database even if the source later delists it, so a pinned world does not silently move.

Both catalogues are checked every time the server starts, and on the configured interval after that. So a container you have just restarted comes back with a current mod list rather than whatever the last scheduled check left behind — the start-up sync ignores the interval deliberately, and costs about a second when nothing has changed.

It runs in the background, so a slow or unreachable catalogue never delays your worlds starting.

There is nothing to tune. The sync is designed so that the common case does almost no work:

• Thunderstore sends a Last-Modified header, so PhValheim makes a conditional request and normally gets a bodiless 304 Not Modified back in about a tenth of a second.
• Hexium sends no validator, so its (much smaller) response body is hashed and compared against the previous run.
• Every stored row carries a content hash, so even when a catalogue has changed only the rows that genuinely differ are rewritten.

Measured on a normal host, against the live catalogues:

The Sync & Maintenance card shows a live panel per catalogue: current phase, packages and versions seen, how many mods and versions were added, changed or removed, how long it took, and how that compares with the previous run. Progress is in /opt/stateful/logs/modSync.log.

Each catalogue's panel has its own live sync log — expand it to watch a sync happen: the endpoint used, how change detection decided to fetch or skip, what was added, updated or delisted by name, which dependencies could not be resolved, and a per-phase timing breakdown. A per-mod detail toggle hides the individual mod lines when you only want the summary.

To force a sync immediately, use the per-catalogue sync link in the Sync & Maintenance panel. A forced sync ignores change detection and rebuilds the dependency graph, so it takes considerably longer than a routine check.

Upgrading from 2.42 or earlier: existing mod selections are migrated automatically on first start and the old Thunderstore tables are left untouched, so nothing is discarded. The Thunderstore Local Sync and Thunderstore Chunk Size settings have been removed — they configured the old parallel-worker sync, which no longer exists. The sidebar's Thunderstore Sync button is gone too; syncing is automatic, and the Sync & Maintenance panel has a per-catalogue sync link if you want to force one.

Add one or more providers under Server Settings → AI Setup. A five-step wizard tests the endpoint, the credential and the model separately, so a failure tells you which of the three is wrong instead of surfacing later as a chat error.

PhValheim has no built-in list of models. Every provider publishes its own catalogue over HTTP, so the model dropdown is fetched live from your endpoint and cached briefly. When a vendor retires a model it simply stops appearing, and a model we have never heard of is sent exactly as you entered it — never silently substituted. Configure as many providers as you like, including several of the same type, and switch between them from the panel header.

Hugin reads logs, world settings, the resolved mod list, catalogue sync state, backups and host health on its own, and shows which of them it consulted in every reply. It can also act: start, stop, restart, update or delete a world, take or restore a backup, and change world options, access lists, backup policy, mods or server settings.

Nothing that matters happens without your say-so. Anything that stops a service, changes configuration or destroys data is shown first as a card listing every change, old value to new, with Apply and Dismiss. That card is built on the server from the validated change — not from Hugin's description of it — works once, expires after fifteen minutes, and is re-checked at the moment you click. Deleting a world and restoring a backup additionally require you to type the world's name.

Hugin refuses changes that would quietly break something: an access list that would be enforced but empty (which opens a world to everyone), listing a vanilla world with no password (Valheim will not start), and crossplay or a password on a modded world (where they do nothing). The "What can Hugin do for me?" button lists every capability and every refusal, generated from the live capability list, and works with no provider configured.

If your model cannot call tools — some smaller self-hosted models cannot — Hugin answers anyway and tells you it could not inspect anything and cannot make changes.

A world can be created as vanilla: stock Valheim with zero mods and no BepInEx. Players join with the ordinary Valheim client, so no PhValheim client install is required.

Tick Vanilla world (no mods) when creating a world, or flip it later in the world's Settings modal (the world needs an update/restart to apply).

Players see a dedicated card on the public UI with the server address, the password (show to reveal, copy to put it on the clipboard), and a Join button. They can also connect from Valheim's own Join IP screen using the address shown.

Note: Valheim has no way to pre-fill a server password from a launch argument, so players type it at the prompt — which is why the card shows it.

Because these worlds run no mods, a few PhValheim features that depend on the companion mod do not apply to them: boss progression ("hung heads"), player join/leave events, and tick-health metrics — so the HEALTH bar is hidden for them in the admin UI.

Seeds. Valheim's dedicated server has no seed argument — the seed is fixed when the world is first generated. Choosing one needs the CustomSeed mod, which a vanilla world does not run, so the seed control is hidden when creating one. PhValheim reads the seed Valheim actually generated out of the world's .fwl after first start and displays that; until then the card shows generated on first start.

If you want a specific seed on a vanilla world, generate the world in the Valheim client (where you can type a seed) and use Import World — no mod required.

A vanilla world cannot have mods: Edit Mods is disabled for it, and turning the vanilla switch on clears any existing mod selection. Turn the switch back off to make it a modded world again, then use Edit Mods and run an Update.

Modded worlds are unaffected by any of this — they continue to be gated by the Citizens list.

Each world has three per-world player lists, all in the world's Settings modal:

• Citizens — who may join (permittedlist.txt). Setting a world Public here removes the restriction entirely and lets anyone join.
• Admins — who gets in-game admin commands (adminlist.txt).
• Banned — who is blocked from the world (bannedlist.txt). A ban applies even when the world is public.

Have them join any public world and press F2. The panel shows their Platform User ID — note it down and paste it in. This is the only method that works for every player: Xbox, PlayStation, Nintendo and GameCenter players have no SteamID64 at all.

A plain SteamID64 (17 digits) also works for Steam players. PhValheim stores what you type and converts it on write.

For Steam players you can also use Look Up SteamID in the Citizens editor — enter a Steam username and it returns the ready-to-paste V_… form. (Requires a Steam API key in Server Settings.)

Why the conversion: since Valheim 1.0, a bare SteamID64 in these files does not match. ZNet.ListContainsId() finishes by looking up the display-prefix form of the ID (Steam → V) and assigns that result over the earlier checks rather than OR-ing it, so only V_<steamid64> can match. PhValheim writes that form for you. This is a bug in Valheim — it is also why Valheim's own ban console command writes an entry its own matcher cannot match, and why older "put your SteamID64 in permittedlist.txt" guides no longer work.

Changes take effect without a restart — Valheim re-reads all three files while running. The one exception is admin status, which a connected client caches until it reconnects.

The database is the source of truth. All three files are regenerated from it every time a world starts, so a world that was restored from a backup or rebuilt converges back to what the admin UI shows instead of quietly keeping an older list.

Upgrading from 2.39 or earlier: your stored IDs are converted to the V_ form automatically on first start, and the Access tab explains it once. Entries that were already prefixed, and console IDs, are left alone; anything unrecognised is kept exactly as you left it rather than dropped.

Note: Use Access List controls the Citizens gate only. It does not publish the world to the Valheim server browser — that is the separate List in server browser option on vanilla worlds.

Use Access List sits at the top of the Access tab, because it decides whether the Citizens list is consulted at all. On, only the players on the list may join. Off, anyone may join, so the editor is hidden — the list is kept, not cleared, and comes back when you switch it on again.

Each world's Settings modal has a Custom Launch Parameters field, appended to the Valheim server command line after everything PhValheim generates, so it can override the defaults.

-saveinterval 900 -instanceid myserver

Shell metacharacters are rejected. Invalid Valheim arguments will stop the world from booting, with the reason only visible in the world log — change these one at a time.

The server is only half the equation. PhValheim Client is a cross-platform companion app (Windows, Linux, macOS) that registers a custom phvalheim:// URL protocol. When a player clicks a launch link:

1. The client compares the remote world's checksum against the local copy.
2. If outdated, it downloads the new payload (mods, configs, dependencies).
3. It launches Valheim, connecting to the correct server and world automatically.

Vanilla worlds skip steps 1 and 2 — there is no payload — and are joined directly, so players do not need the client for them at all.

Client repo: brianmiller/phvalheim-client

Access to each world is controlled by the PhValheim database. Steam IDs are associated with each world, gating both the web UI (world visibility) and the game server allow-list.

Example NGINX config for TLS termination:

server {
    listen 80;
    server_name phvalheim.example.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name phvalheim.example.com;

    ssl_certificate     /path/to/fullchain.pem;
    ssl_certificate_key /path/to/privkey.pem;

    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_read_timeout 1200s;
        client_max_body_size 0;
    }
}

PhValheim makes mod management effortless, but not all mods play well together. If you're experiencing crashes or unexpected behavior, deploy a vanilla world (no mods) first to rule out mod conflicts. Most mod issues occur after major Valheim updates.

Join the Discord · Report an Issue · PhValheim Client