PortalPass

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.

Private by design

PortalPass does not discover, collect, record, learn, or edit passwords. You

create and maintain passwords.env; PortalPass only reads it when Valheim asks

for a password. It never copies a password from manual entry, writes credentials

back to disk, logs them, or adds them to an exported mod profile.

This is a security feature, not a bug: the player remains the only authority that

can add or change a saved password. If the file is missing, invalid, or has no

matching server, PortalPass changes nothing and Valheim shows its normal password

prompt. The mod will never populate passwords.env for you.

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

• Exact normalized host:port
• Normalized host/IP without a port
• 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.2.zip.

Status

PortalPass has passed live client connection tests on Windows and on Linux

through Proton, including Valheim's PlayFab backend resolution path.