PortalPass

PortalPass is a client-only Valheim 1.0 mod that automatically supplies server passwords from a private local file. It works at Valheim's normal password handshake, so direct joins and connections initiated by Cross Server Portals Continued use the same rules.

Made for cross-server portal travel

PortalPass works especially well with Cross Server Portals Continued (source on GitHub). When a portal moves you to another password-protected server, PortalPass supplies that destination's configured password automatically. The portal mod is optional; PortalPass also works with normal direct joins.

Why

Repeated password entry is especially awkward on Steam Deck and during cross-server portal travel. PortalPass makes those joins seamless without putting credentials in a shared r2modman profile.

Requirements

• Valheim 1.0
• BepInExPack Valheim 5.4.2350 or newer compatible release
• PortalPass installed on the client only

Install

Install the release ZIP as a local mod in r2modman, or copy PortalPass.dll into the client's BepInEx/plugins/PortalPass/ directory. Start the game once to create com.jcruse03.portalpass.cfg.

Secret file

The default path is deliberately outside r2modman profiles:

• Linux / Steam Deck: ~/.config/portalpass/passwords.env
• Windows: %LOCALAPPDATA%\PortalPass\passwords.env

Create the directory and file yourself. On Linux, protect it with:

chmod 600 ~/.config/portalpass/passwords.env

Format:

# Host-wide default
valheim.example.net = common-password

# Exact endpoint wins over the host-wide default
valheim.example.net:2471 = test-server-password

# IP addresses work the same way
203.0.113.20 = another-password
203.0.113.20:2459 = specific-password

# IPv6 exact endpoints use brackets
2001:db8::1 = ipv6-default
[2001:db8::1]:2459 = ipv6-specific

Passwords may be unquoted or wrapped in matching single or double quotes. The first = separates the endpoint, so = is allowed inside a password.

To use another location, edit SecretFilePath in BepInEx/config/com.jcruse03.portalpass.cfg. A ~/... path is supported.

Matching and safety

1. Exact normalized host:port
2. Normalized host/IP without a port
3. No match: the normal Valheim password dialog remains active

Hostnames are case-insensitive and ignore a trailing dot. IP addresses use their canonical textual form. PortalPass does not resolve DNS, so a hostname and its IP address are separate rules. Duplicate normalized endpoints or any malformed line invalidate the file for that attempt; PortalPass then leaves the vanilla prompt alone. Passwords are never logged or learned from manual entry.

The file is read fresh at every password handshake, so edits do not require a game restart.

Valheim may resolve a dedicated IP or hostname to a PlayFab backend before the handshake. PortalPass preserves the original dedicated endpoint for matching, so the file continues to use the human-readable host or IP from the join request or cross-server portal tag.

Development

The local .game path must point at a Valheim installation with BepInEx. Then:

mise trust
mise run check

This builds against the local Valheim 1.0 assemblies, runs pure parser tests, and creates artifacts/PortalPass-v0.1.1.zip.

Status

PortalPass 0.1.1 has passed live client connection tests on Windows and on Linux through Proton, including Valheim's PlayFab backend resolution path.

Changelog

0.1.2 - 2026-09-10

• Make the read-only, user-controlled password model prominent in the package documentation: PortalPass never collects, records, learns, or edits passwords.
• Clarify that only the player creates and maintains passwords.env, and that vanilla fallback is an intentional safety boundary.

0.1.1 - 2026-09-10

• Preserve the original dedicated host and port when Valheim resolves a direct connection to a PlayFab backend before the password handshake.
• Add safe diagnostics for unavailable and unmatched endpoints without logging passwords.

0.1.0 - 2026-09-10

• Initial client-only Valheim 1.0 release.
• Add exact endpoint and host-wide password matching with deterministic precedence.
• Add IPv4, hostname, and bracketed/bare IPv6 support without DNS guessing.
• Keep secrets outside exported r2modman profiles and fall back to vanilla on missing or invalid files.