AutoModSync

By
gordonfreesay
Mods

Automatically keeps a Valheim server's synchronized BepInEx plugin set matched on trusted clients, including verification, restart, and reconnect.

VALHEIM AUTOMODSYNC 2.6.0

Join the server. The mods follow.

AutoModSync is a client/server synchronization utility for Valheim + BepInEx.

Instead of requiring every player to manually locate, compare, update, and install the same server-required files, AutoModSync lets a trusted server maintain its synchronized BepInEx set automatically.

Players connect to the Valheim server normally.

AutoModSync can synchronize:

BepInEx/plugins files
Required BepInEx/patchers files
Explicitly allowlisted BepInEx/config files
Client-required files from BepInEx/AutoModSync/ClientPayload/plugins

Server synchronization behavior is configured in:

BepInEx\config\com.gordonfreesay.valheimautomodsync.server.cfg

When an AutoModSync client joins an enabled server, it can verify the server identity, compare installed files against the signed manifest, transfer only missing or changed files, verify them, safely apply updates, restart Valheim when required, reconnect to the same server, and continue using the previously selected character when possible.

Version 2.6 is a major reliability, scale, safety, and user-experience update focused on large synchronized payloads, interrupted downloads, multiple joining clients, safer file ownership, crash-resistant updates, and clearer synchronization telemetry.

✨ FEATURES

• Automatic server-to-client synchronization
Downloads missing or updated synchronized BepInEx files required by the server.

• Plugins, patchers, selected configs & client-only payloads
AutoModSync can synchronize normal plugins, required preloader patchers, explicitly allowlisted configuration files, and dedicated client-only payloads.

• Client-only server payloads
2.6 adds:

BepInEx\AutoModSync\ClientPayload\plugins\

This lets a dedicated server distribute required client files without loading those files into the dedicated-server process itself.

• Pre-handshake synchronization
AutoModSync synchronizes before Valheim's normal compatibility handshake continues. Existing Jotunn/ServerSync-style compatibility systems still run normally afterward. AutoModSync does not bypass those systems.

• Delta synchronization
Only missing or changed synchronized files are transferred.

• Content-addressed bundle caching
2.6 can reuse the same immutable prepared bundle when multiple clients need the same synchronized file set instead of rebuilding the ZIP separately for every request.

• Startup bundle prewarming
Servers can prepare the common nearly-bare-client bundle during startup so the first fresh client does not necessarily have to wait for ZIP construction during the join.

• Single-flight bundle construction
If overlapping clients request the same uncached bundle, one build can be shared instead of independently recompressing identical content.

• Interrupted-download resume
2.6 can retain one bounded partial package after an interrupted transfer. Resume is accepted only when the trusted server identity, requested change set, bundle digest, size, and transfer geometry still match.

The server independently verifies the retained prefix against the current immutable artifact before continuing from a nonzero resume point.

• Bounded multi-client scheduling
2.6 adds a server-wide transfer scheduler with bounded active and waiting work. Active peers share an aggregate transfer budget instead of each client independently attempting to consume the full configured bandwidth.

• Round-robin transfer grants
Active transfers receive bandwidth grants in rotation.

• SteamNetworkingSockets backpressure awareness
AutoModSync can defer sending when Steam's reliable queue is already under pressure.

• No extra sync port
AutoModSync uses Valheim's existing game connection.

• Signed server manifests
Each AutoModSync server maintains its own signing identity.

• SHA-256 verification
Transferred files are verified against the authenticated server manifest before application.

• Safer first-contact server trust
2.6 displays a short human-comparison security code on first contact instead of showing the complete fingerprint in normal UI.

The full 256-bit fingerprint remains internal for cryptographic signature verification and trust pinning.

• Fail-open discovery for non-AutoModSync servers
If the selected server does not respond as AutoModSync during the short discovery window, normal Valheim behavior continues.

• Fail-closed behavior after AutoModSync recognition
Once a server positively identifies itself as AutoModSync, protected trust, signature, path, transfer, verification, resource, and apply-preparation failures block that join instead of silently falling back.

• Transactional apply & recovery
2.6 uses a durable PREPARED / COMMITTED transaction model so interrupted updates can recover the complete previous state or preserve the complete committed new state.

• Ownership-safe stale cleanup
AutoModSync records ownership only for files it actually installs or replaces.

A matching pre-existing file is not automatically claimed. A stale synchronized file is removed only when its current bytes still match the exact digest AutoModSync previously installed for the same trusted server.

Locally modified and unrelated files are preserved.

• Stronger path safety
2.6 adds fixed-root containment, Windows device-name protection, trailing-dot/trailing-space alias protection, traversal rejection, and reparse-point safeguards.

• Bounded ZIP extraction
Compressed size, expanded size, file count, individual file size, transfer geometry, and ZIP expansion are bounded.

• Branded synchronization UI
The 2.6 AutoModSync panel displays:

Comparison counts
Queue position
Current throughput
Average throughput
ETA
Resume-retained bytes
Verification state
Apply state
Restart state
Reconnect state
Completion
Failure state

• Passive server-browser AMS presence
Supported Steam-backed servers can advertise passive AutoModSync version/protocol rules.

AutoModSync-aware clients can display a small local AMS badge beside positively identified server-browser entries without changing the advertised server name.

Server advertisement and client badge display can be disabled independently.

• Automatic restart
If synchronized files changed, AutoModSync stages the verified update and restarts Valheim.

• Automatic reconnect
After updates are applied, Valheim is relaunched and AutoModSync returns to the originating server.

• Selected-character continuation
When possible, AutoModSync continues using the character selected before synchronization restarted the game.

• Server/client classification
Server-only and optional client-required patterns let administrators avoid advertising dedicated-server-only files to players.

• Package-manager support
Supported package-manager launch contexts can be preserved through restart and reconnect.

• Package-managed AutoModSync files stay package-managed
AutoModSync does not overwrite its own package-manager-owned binaries through server synchronization. Update AutoModSync through the distribution channel that installed it.

• Official build provenance
Official GitHub-built standalone and store packages receive SHA-256 manifests and GitHub/Sigstore artifact attestations.

INSTALLATION

Close Valheim and any running Valheim Dedicated Server before installing.

1\. INSTALL BEPINEX

Install BepInExPack Valheim 5.4.2350 or another compatible current Valheim BepInEx 5 installation.

BepInEx is a separate requirement for this CurseForge package.

2\. INSTALL AUTOMODSYNC

Extract the AutoModSync archive into the Valheim game directory or dedicated-server directory while preserving its directory structure.

The package should place the AutoModSync components under:

BepInEx\plugins\GordonFreesay-ValheimAutoModSync\

3\. LAUNCH NORMALLY

Start Valheim or the Valheim Dedicated Server through the BepInEx-enabled installation as usual.

The same CurseForge package contains the AutoModSync client role, server role, and apply helper.

On valheim_server.exe, the client role disables itself automatically.

On a normal Valheim client, the server role remains passive unless that client is hosting.

SERVER CONFIGURATION

AutoModSync's server synchronization rules are configured in:

BepInEx\config\com.gordonfreesay.valheimautomodsync.server.cfg

ExcludePatterns

Located under:

[General]
ExcludePatterns =

A semicolon-separated wildcard list for files that should not be sent to clients from synchronized roots.

ServerOnlyPatterns

Located under:

[Compatibility]
ServerOnlyPatterns =

Use this for plugin or patcher files that exist on the server but must never be copied to clients.

ClientRequiredPatterns

Located under:

[Compatibility]
ClientRequiredPatterns =

This is an optional plugin/patcher allowlist.

When empty, every non-excluded and non-server-only plugin/patcher file remains client-required.

When populated, only matching plugin/patcher files are advertised as required client files.

If a mod has dependency DLLs or assets beside its primary DLL, include the appropriate folder wildcard.

Example:

ClientRequiredPatterns = SomeMod/*;AnotherRequiredMod/*

SyncPatchers

Located under:

[Compatibility]
SyncPatchers = true

Controls recursive synchronization of required files under:

BepInEx\patchers

Individual server-only patchers can still be excluded with ServerOnlyPatterns.

SyncConfigPatterns

Located under:

[Compatibility]
SyncConfigPatterns =

BepInEx config files are not synchronized by default.

Only add config files that genuinely need to be identical on clients.

Patterns are semicolon-separated and relative to:

BepInEx\config

Example:

SyncConfigPatterns = com.example.required.cfg;RequiredMod/*.json

The following are always blocked from config synchronization even if a broad pattern would otherwise match them:

ValheimAutoModSync.private.xml
ValheimAutoModSync.public.xml
BepInEx.cfg

ClientPayload

2.6 adds a dedicated server-side source for files clients require but the dedicated server itself should not load:

BepInEx\AutoModSync\ClientPayload\plugins\

Files beneath this tree can be synchronized to client plugin destinations without placing them inside the dedicated server's active BepInEx\plugins tree.

Large-payload controls

2.6 adds configurable resource and scheduling controls including:

Bundle-size limits
Expanded-size limits
Active transfer limits
Waiting queue limits
Aggregate transfer bandwidth
Bundle cache retention
Bundle-cache disk budget
Optional fresh-client bundle prebuild

Important distinction:

ExcludePatterns broadly prevents matching synchronized files from being sent.
ServerOnlyPatterns classifies plugin/patcher files that stay server-side.
ClientRequiredPatterns optionally restricts which plugin/patcher files clients require.
SyncConfigPatterns explicitly opts configuration files into synchronization.
ClientPayload provides client-required files the dedicated server itself should not load.

THIRD-PARTY MOD REDISTRIBUTION

AutoModSync is a synchronization/transport tool. It does not grant redistribution rights for third-party mods.

Before configuring AutoModSync to send a third-party mod or related file to connecting clients, the server operator is responsible for confirming that the mod's license or author permissions allow that redistribution and for complying with any applicable conditions.

A private, password-protected, friends-only, or noncommercial server does not by itself grant redistribution permission.

This is especially important for public servers, where synchronized files may be distributed to an unrestricted number of players.

Mods that prohibit redistribution, or whose redistribution permissions are unclear, should be excluded from AutoModSync transfer unless the server operator obtains appropriate permission from the rights holder.

AutoModSync itself does not bundle arbitrary third-party gameplay mods and does not download them from Nexus Mods, Thunderstore, GitHub, or other mod repositories on behalf of the server operator.

Full policy: https://github.com/GordonFreesay/ValheimAutoModSync/blob/main/THIRD-PARTY-MOD-REDISTRIBUTION.md

CURSEFORGE PACKAGE

This is the lightweight CurseForge distribution of AutoModSync.

It does not include:

ValheimAutoModSyncInstaller.exe
Bundled BepInEx
The standalone GitHub/website installation package
A nested standalone ZIP/archive

Install BepInExPack Valheim 5.4.2350, or another compatible current Valheim BepInEx 5 installation, separately.

The standalone GitHub/website package contains the AutoModSync GUI installer and bundled hash-pinned BepInEx package for clean standalone installation.

Standalone package: AutoModSync website

GitHub releases: AutoModSync releases on GitHub

All distribution channels use the same AutoModSync software version. Different archive names identify packaging targets, not separate software versions.

HOW IT WORKS

01 — DISCOVERY

AutoModSync briefly checks whether the selected server supports AutoModSync before Valheim's normal compatibility flow continues.

If the server does not respond as AutoModSync, normal Valheim behavior continues.

02 — TRUST

Every AutoModSync server has its own signing identity.

On first contact, AutoModSync displays a short human-comparison security code so the player can decide whether that server operator should be trusted.

The complete cryptographic fingerprint remains internal for signature verification and trust pinning.

Only trust AutoModSync servers operated by people you recognize and trust.

03 — COMPARE

AutoModSync compares the client's synchronized file hashes against the server's signed synchronization manifest.

Files that already match do not need to be downloaded again.

04 — QUEUE / PREPARE

If a transfer is required, the request enters the server's bounded scheduler.

The server prepares or reuses the immutable bundle corresponding to the required change set.

05 — DOWNLOAD / RESUME

Only synchronized files that are missing, outdated, or different from the server version are transferred.

If a compatible partial transfer was retained after a disconnect, 2.6 can resume it only after the server independently verifies the retained prefix against the current bundle.

06 — VERIFY

Transferred package data and extracted files are verified before live installation.

07 — PREPARE TRANSACTION

Required live-file changes are staged. Existing destinations that must be replaced are backed up before the apply transaction modifies live synchronized files.

08 — APPLY

The complete verified update is applied transactionally.

If an interruption occurs before COMMITTED, AutoModSync can recover the previous complete state. If the transaction is already COMMITTED, AutoModSync preserves the complete new state and finishes cleanup.

09 — RESTART

If synchronized files changed, AutoModSync restarts Valheim so BepInEx can load the synchronized set cleanly.

10 — RECONNECT

AutoModSync attempts to return the player to the same server.

When possible, it also continues using the character selected before synchronization restarted the game.

Valheim still handles the normal server-password prompt when applicable.

INTERRUPTED DOWNLOAD RESUME

2.6 can retain one bounded partial synchronized package if a connection is interrupted during transfer.

The partial transfer is associated with:

The trusted server identity
The requested synchronized change set
The immutable bundle digest
Bundle size
Transfer/chunk geometry
The retained complete prefix

Before continuing from a nonzero resume position, the server independently verifies the retained prefix against its current immutable artifact.

If the relevant identity, requested content, or bundle changed, the partial is rejected and synchronization starts again safely.

TRANSACTIONAL APPLY & RECOVERY

2.6 adds a durable apply transaction so a partially completed file replacement is not treated as a successful synchronized state.

The transaction enters PREPARED before live synchronized files change and reaches COMMITTED only after the required destinations have been installed and verified.

If AutoModSync or the system is interrupted before COMMITTED, recovery can restore the previous complete state before retrying.

AutoModSync should not intentionally accept a mixed half-old / half-new synchronized state.

OWNERSHIP-SAFE FILE CLEANUP

AutoModSync claims a synchronized file only when AutoModSync actually installs or replaces it.

A pre-existing local file that already matches the server is not automatically claimed.

A stale owned file is removed only when it still exactly matches the bytes AutoModSync previously installed for the same trusted server.

If the player modifies the file locally, AutoModSync preserves it and relinquishes ownership instead.

🔌 NO EXTRA SYNC PORT

AutoModSync uses Valheim's existing game connection.

You do not need to:

Open another synchronization port
Add another AutoModSync firewall rule
Add another router port-forward
Run a separate web server for mod synchronization

CLIENT

On a normal Valheim game process, the AutoModSync client handles synchronization with AutoModSync-enabled servers.

DEDICATED SERVER

On valheim_server.exe, the client role disables itself automatically.

The server component can:

Create and maintain the server's signing identity
Publish the signed synchronization manifest
Synchronize plugins, patchers, selected configs, and client-only payloads
Cache and prewarm immutable bundles
Share one build across identical requests
Schedule active and waiting transfers
Apply aggregate bandwidth limits
Respect Steam reliable-queue backpressure
Verify retained prefixes before interrupted-download resume
Advertise optional passive AMS server-browser presence

HOST & PLAY

The same package supports a normal Valheim installation that hosts a world.

The server role remains passive on an ordinary client unless that Valheim instance is hosting.

🔐 SECURITY MODEL

IMPORTANT

BepInEx plugins and preloader patchers can execute code.

AutoModSync intentionally allows a trusted Valheim server to provide synchronized files that can run on the client.

Only approve first-contact AutoModSync trust for server operators you recognize and trust.

AutoModSync verifies:

Server signing identity
Signed synchronization manifest
SHA-256 hashes
Bundle integrity
Extracted file integrity
Allowed synchronization destinations
Configured resource limits

SHA-256 verification does not determine whether a third-party plugin or patcher is safe or trustworthy.

AutoModSync is not an antivirus scanner.

SERVER SIGNING IDENTITY

Each AutoModSync server receives its own signing identity.

The server's private signing key must never be distributed to clients.

Normal 2.6 UI shows a short human-comparison security code. The complete 256-bit fingerprint remains internal for cryptographic verification and trust pinning.

FAIL-OPEN VS FAIL-CLOSED

NON-AUTOMODSYNC SERVER

If the server does not respond as AutoModSync during the short discovery window, normal Valheim behavior continues.

RECOGNIZED AUTOMODSYNC SERVER

Once a server positively responds as AutoModSync, protected synchronization failures do not silently fall back to an unprotected join.

Examples include:

Invalid acknowledgement
Invalid or incomplete manifest
Invalid manifest signature
Declined trust
Server-reported AutoModSync error
Invalid bundle metadata
Corrupt or out-of-order transfer data
Invalid final bundle verification
Unsafe synchronization paths
Resource-limit violations
Apply/restart preparation failure

RESOURCE & PATH SAFETY

2.6 adds stricter client, server, and apply-helper safeguards including:

Maximum compressed bundle size
Maximum expanded bundle size
Maximum synchronized file count
Maximum individual file size
Maximum transfer/chunk count
Streaming ZIP expansion limits
Fixed synchronization roots
Rooted/traversal-path rejection
Windows reserved device-name protection
Trailing-period and trailing-space alias protection
Reparse-point / junction redirection protection
Protected AutoModSync identity/config files

PUBLIC SERVER / LARGE MOD SET SUPPORT

2.6 introduces a new transfer architecture intended to make large synchronized environments more practical.

IMMUTABLE CONTENT-ADDRESSED BUNDLE CACHE

Identical requests can reuse the same verified prepared artifact.

FRESH-CLIENT PREWARMING

The common nearly-bare-client package can be prepared during dedicated-server startup.

SINGLE-FLIGHT CONSTRUCTION

Overlapping identical requests share one bundle build.

BOUNDED SCHEDULER

Transfers are admitted through active and waiting limits.

AGGREGATE BANDWIDTH CONTROL

Active peers share one server-wide raw-payload transfer budget.

STEAM RELIABLE-QUEUE BACKPRESSURE

AutoModSync can defer transfer grants when Steam's reliable queue is already under pressure.

EXACT-ARTIFACT RESUME

Disconnected clients do not necessarily need to restart a large synchronized transfer from zero.

SERVER-BROWSER AMS BADGE

2.6 can advertise passive AutoModSync presence through Steam server rules:

automodsync=<version>
automodsync_protocol=<protocol>

An AutoModSync-aware client can display a small local AMS badge beside a positively identified server entry.

The advertised server name itself is not modified.

Server advertisement and client badge display can both be disabled.

ANTIVIRUS / SECURITY SCANNER NOTES

This CurseForge archive is the lightweight mod-site package and does not bundle BepInEx.

The standalone distribution available through GitHub and the developer website does include a pinned BepInEx package.

AutoModSync's own source code is public and unobfuscated.

Users should still evaluate security warnings rather than blindly ignoring them.

OFFICIAL BUILD VERIFICATION

Official AutoModSync 2.6 packages built through the project's GitHub Actions release workflows receive:

SHA-256 package checksums
GitHub/Sigstore artifact attestations

The CurseForge publishing workflow attests the exact CurseForge ZIP produced by the workflow before upload.

GitHub CLI verification:

gh attestation verify .\ValheimAutoModSync-2.6.0-CurseForge.zip -R GordonFreesay/ValheimAutoModSync

GitHub/Sigstore provenance is separate from Windows Authenticode.

AutoModSync's Windows executable files currently do not have a publicly trusted Authenticode publisher certificate.

Read the release verification documentation

WHAT AUTOMODSYNC DOES NOT DO

Open a separate synchronization port
Require users to manually compare synchronized file versions
Automatically mirror every server config file
Blindly delete unrelated client plugins
Delete locally modified synchronized files merely because the server removed them
Claim pre-existing matching files merely because they match
Bypass normal Jotunn/ServerSync compatibility decisions
Claim third-party plugins are malware-free
Replace Valheim's normal server-password handling
Require a separate mod-distribution web server
Treat GitHub/Sigstore provenance as Authenticode signing