CatosAntiCheat

Strict mod-list enforcement for Valheim servers.

CatosAntiCheat checks every connecting player against the server's installed BepInEx plugins. Players with missing server mods, unauthorized extra mods, or incompatible versions are rejected before they can join.

This is mod-profile enforcement, not undefeatable anti-cheat. A modified client can potentially fake its reported plugin list; CatosAntiCheat is intended to keep honest clients on the same approved profile.

Features

• Requires players to have the server's required mods.
• Lets administrators mark server-side plugins that clients do not need.
• Rejects unauthorized client-side mods.
• Supports a shared whitelist for approved client-only quality-of-life mods.
• Supports an admin-only whitelist for staff tools.
• Allows server owners to choose exact, minimum-version, or GUID-only version checks.
• Optionally posts kick notifications to Discord.
• Reloads whitelist files automatically when they are edited.
• Shows the player a readable rejection reason in chat when the connection supports it.
• Includes an AuditOnly mode for safely testing a server profile before enforcing kicks.
• Retries a timed-out handshake once by default for slow-loading clients.

Installation

Install CatosAntiCheat through Thunderstore Mod Manager or r2modman.

Dedicated server administrators

1. Install CatosAntiCheat on the dedicated server profile.
2. Install the same profile and CatosAntiCheat on every player's client.
3. Start the server once to generate its configuration and whitelist files.
4. Make sure the server's required mods are also installed on every player's client.

CatosAntiCheat is a server-and-client mod. Players who do not have it installed cannot complete the mod-list handshake and will be kicked after the configured timeout.

The client and server must use the exact same CatosAntiCheat version. Updating only one side will cause the connection to be rejected, even if the general mod VersionPolicy allows newer client versions.

Players

Install the server's complete Thunderstore mod profile, including CatosAntiCheat. Do not add extra mods unless the server administrator has approved them in the server's whitelist.

Configuration files

After the first launch, files are created in BepInEx/config/:

• com.catosvalheim.anticheat.cfg — main settings.
• CatosAntiCheat_ExtraWhitelist.txt — extra mods allowed for all players.
• CatosAntiCheat_AdminWhitelist.txt — extra mods allowed only for Valheim admins.
• CatosAntiCheat_ServerOnly.txt — server plugins that clients do not need to install.

Important settings in com.catosvalheim.anticheat.cfg include:

The settings are grouped in the generated config under 1 - General, 2 - Strictness, 3 - Feedback, and the existing 3 - Discord section.

AuditOnly mode

Set EnforcementMode = AuditOnly while building or debugging a server mod profile. CatosAntiCheat will still perform the complete validation and log what it would reject, but it will not disconnect players, send kick chat messages, or post kick webhooks. Return it to Enforce when the profile is ready.

Version policy

The default ClientAtLeastServer policy allows a client version equal to or newer than the server version. Available policies are:

Keep RequireClientHasAllServerMods = true unless you understand the security trade-off. Disabling it allows clients to join without mods installed on the server.

Regardless of that setting, CatosAntiCheat itself is always required and must match the server's exact version.

Whitelisting extra mods

Add one BepInEx plugin GUID per line to CatosAntiCheat_ExtraWhitelist.txt:

# Allow any version
com.example.clientmod

# Allow only this exact version
com.example.clientmod=1.2.3

Use the plugin GUID, not the Thunderstore package name. It is usually visible in the mod's config filename, BepInEx startup log, or package documentation.

Use CatosAntiCheat_AdminWhitelist.txt for mods that should be available only to trusted server admins. Admins must still have every required server mod; this list only permits additional admin tools.

Whitelist changes are detected automatically and apply to new connection attempts.

Server-only mods

Add a server plugin's BepInEx GUID to CatosAntiCheat_ServerOnly.txt when it runs on the server but players do not need it on their clients. For example, a server administrator may add the GUID for a server-side command or administration mod such as ServerDevcommands.

# Clients do not need this server-side plugin
serverdevcommands.example.guid

This list removes the mod from the server's required-client check, including its version check. It does not remove the mod from the server's detected set, and a client that happens to have the same server-installed mod is still accepted. It does not make unrelated client-only mods valid; use the extra or admin whitelist for those.

Only configure this list for plugins that are genuinely safe to run without a client installation. If a mod changes gameplay or requires a matching client component, leave it out.

Discord notifications

To receive kick notifications, set WebhookUrl in the [3 - Discord] section of com.catosvalheim.anticheat.cfg and enable the desired notification settings. AuditOnly mode suppresses kick webhooks because no kick occurs.

Never share a Discord webhook URL publicly. Leave it empty to disable Discord notifications.

Troubleshooting

I am kicked immediately

Check the server log for the exact reason. Common causes are:

• A required server mod is missing from the client.
• The client has an unapproved extra mod.
• A client mod is older than the server version.
• The client and server use different whitelist entries.

I am kicked after about 15 seconds

The client probably does not have CatosAntiCheat installed, or the mod failed to load. CatosAntiCheat retries the handshake once by default, so the final rejection normally occurs after roughly 30 seconds. Confirm that both sides use BepInEx and that the plugin appears in the BepInEx log.

The chat says the CatosAntiCheat version is incompatible

Update both the server and client to the same Thunderstore version. CatosAntiCheat uses a versioned handshake so incompatible protocol changes fail clearly instead of being treated as a normal mod mismatch.

My client-only mod is safe, but I still cannot join

Ask the server administrator to add its BepInEx GUID to CatosAntiCheat_ExtraWhitelist.txt. Players cannot whitelist their own mods.

Admin tools are rejected

The server administrator must add the mod GUID to CatosAntiCheat_AdminWhitelist.txt, and the player's Steam ID must be present in the server's Valheim admin list. Admin status does not bypass required server-mod or version checks.

The server log reports a malformed whitelist entry

Each entry must contain one plugin GUID, optionally followed by =exact.version. Blank versions, whitespace inside GUIDs, and malformed handshake data are rejected safely and explained in the BepInEx log.

Compatibility

CatosAntiCheat should be installed on both dedicated servers and clients in the same mod profile. It is intended to work alongside normal BepInEx/Thunderstore mods, but server owners should avoid running multiple anti-cheat or mod-enforcement systems that may issue conflicting decisions.

Thunderstore package information

The repository includes the Thunderstore manifest.json, this README, icon.png, CHANGELOG.md, and LICENSE. Build output and local server files are intentionally excluded from the repository. The package must contain the compiled CatosAntiCheat.dll under the normal BepInEx plugin layout when it is uploaded to Thunderstore.

Changelog

1.0.4

• Added Enforce and AuditOnly enforcement modes.
• Added one configurable handshake retry by default.
• Added configurable player-facing kick messages and message prefix.
• Added optional accepted-connection logging and configurable displayed-problem limits.
• Added a startup configuration summary.

1.0.3

• Added a protocol-versioned handshake.
• Requires the client and server to use the exact same CatosAntiCheat version.
• Sends a readable rejection reason to the player's in-game chat before disconnecting when possible.
• Added safer validation for malformed handshakes, timeout values, version policies, and whitelist entries.
• Added Thunderstore package metadata.

1.0.2

• Added the server-only mod allowlist: CatosAntiCheat_ServerOnly.txt.