CatosAntiCheat

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:

| Setting | Default | Purpose | |---|---:|---| | EnforcementMode | Enforce | Enforce kicks mismatches. AuditOnly logs them but allows connections. | | KickTimeoutSeconds | 15 | Time to wait for a mod-list reply. | | HandshakeRetries | 1 | Additional requests after a timeout. Set to 0 to disable retries. | | SendKickMessages | true | Sends a readable reason to the player's chat before disconnecting. | | KickMessagePrefix | CatosAntiCheat | Prefix for player-facing rejection messages. | | LogAcceptedConnections | false | Logs every successfully validated player when enabled. | | MaxDisplayedProblems | 6 | Maximum mismatch reasons shown in logs, Discord, and chat. |

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:

| Policy | Behavior | |---|---| | Exact | Client and server versions must be identical. | | ClientAtLeastServer | Client may be the same version or newer. | | Ignore | Compare plugin GUIDs but not versions. |

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.