mini-server-manager/managed-valheim
1
1 Fork 0
Code Issues 5 Pull Requests Actions Packages Projects 1 Releases 1 Wiki Activity
Page: Modding Guide
Pages
Backup & Restore FAQ Home Installation Modding Guide Quick Start Troubleshooting Version History
Clone
1
Modding Guide
the_minisip edited this page 2026-10-16 13:19:34 -03:00
Unescape Escape
Table of Contents
This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Modding Guide

This guide explains how to install, manage, and troubleshoot mods for the Managed Valheim server. The container includes automatic BepInEx installation and a clean/modded directory separation, making modding safe and predictable across updates.

1. How Modding Works in Managed Valheim

The container uses a two‑directory architecture:

  • /opt/valheim_base — Clean SteamCMD installation
  • /opt/valheim — Modded runtime directory

SteamCMD updates the clean directory, and the container copies updated files into the modded directory before applying BepInEx. This ensures:

  • Mods never interfere with SteamCMD updates
  • No rollback errors (state 0x6)
  • Mods persist across updates
  • BepInEx is always correctly patched

2. Where to Install Mods

Mods should be placed in the BepInEx plugins directory: 

/opt/valheim/BepInEx/plugins

This directory persists across updates and is safe for:

  • DLL mods
  • Thunderstore modpacks (manual extraction)
  • Custom server-side plugins

Do not place mods in /opt/valheim_base. That directory must remain clean for SteamCMD.

3. Installing Mods

To install a mod:

  1. Download the mod (usually a ZIP file).
  2. Extract the contents.
  3. Copy the mod’s DLL files into:
    /opt/valheim/BepInEx/plugins
  4. Restart the TrueNAS SCALE app.

On restart, BepInEx will load all plugins automatically.

4. Installing Modpacks

Thunderstore modpacks can be installed manually:

  1. Download the modpack ZIP.
  2. Extract it locally.
  3. Copy all BepInEx/plugins contents into:
    /opt/valheim/BepInEx/plugins
  4. Copy any config files into:
    /opt/valheim/BepInEx/config
  5. Restart the server.

The container will not overwrite your modpack configuration.

5. Updating Mods

To update a mod:

  1. Download the new version.
  2. Replace the old DLL in:
    /opt/valheim/BepInEx/plugins
  3. Restart the server.

BepInEx will load the updated plugin automatically.

6. Removing Mods

To remove a mod:

  1. Delete the mod’s DLL from:
    /opt/valheim/BepInEx/plugins
  2. Remove any related config files from:
    /opt/valheim/BepInEx/config
  3. Restart the server.

7. Mod Configuration Files

Many mods generate configuration files under: 

/opt/valheim/BepInEx/config

These files are safe to edit and persist across updates. Restart the server after making changes.

8. Troubleshooting Mods

Mod Not Loading

  • Check /opt/valheim/BepInEx/plugins for the DLL.
  • Verify the mod is compatible with the current Valheim version.
  • Check BepInEx logs:
    /opt/valheim/BepInEx/LogOutput.log

Server Crashes on Startup

  • Remove the most recently added mod.
  • Check BepInEx crash logs.
  • Ensure no mods were placed in /opt/valheim_base.

Mod Conflicts

  • Disable mods one at a time to isolate the conflict.
  • Check mod documentation for known incompatibilities.

9. Safe Modding Practices

  • Always back up your world before installing new mods.
  • Use versioned modpacks for stability.
  • Keep BepInEx up to date (the container handles this automatically).
  • Never modify files inside /opt/valheim_base.

Next Steps

With this guide, you can safely install and manage mods on your Managed Valheim server while maintaining full update compatibility and stability.