Table of Contents
Running on a Bare-Metal Linux Server
From Release
- Navigate to the latest release
- Download the archive for your platform (
odin+huginn-<version>-x86_64-unknown-linux-gnu.zip) to your server
- Extract it
- Make the files executable
chmod +x {odin,huginn}
- Optional: Add the files to your PATH.
- Navigate to the folder where you want your server installed.
- Run
odin configure --password "Your Super Strong Password" (you can also supply --name "Server Name", --port "Server Port", or other arguments available).
- Finally, run
odin start.
More in-depth How-to Article: Running Valheim on a Linux Server
From Source
This repo bundles its tools in a way that you can run them without having to install Docker!
If you purely want to run this on a Linux-based system, without Docker, take a look at the links below:
- Installing & Using Odin: Odin runs the show and does almost all the heavy lifting in this repo. It starts, stops, and manages your Valheim server instance.
- Installing & Using Huginn: Huginn is an HTTP server built on the same source as Odin and uses these capabilities to expose a few HTTP endpoints.
Using the binaries to run on an Ubuntu Server, you will have to be more involved and configure a few things manually.
If you want a managed, easy one-two punch to manage your server, then look at the Docker section.
Running with Docker
Mods Quick Start
Want to run Valheim with mods? Here's the shortest path:
- Set
TYPE=BepInEx (installs the BepInEx framework automatically)
- Provide mods via
MODS as a newline-separated list of dependency strings or direct URLs
Example (compose):
services:
valheim:
image: mbround18/valheim:3
user: "1000:1000"
environment:
- TYPE=BepInEx
- |
MODS=ValheimModding-Jotunn-*
OdinPlus-OdinHorse-1.4.12
https://cdn.thunderstore.io/live/repository/packages/abearcodes-SimpleRecycling-0.0.10.zip
Notes:
- Wildcards are supported and resolve to the latest version at startup:
Author-Package-* (latest)Author-Package-1.* (latest matching major)Author-Package-1.2.* (latest matching major/minor)
- Prefer pinning exact versions for stability in production
- With many mods, consider disabling automatic updates to avoid mismatch issues
- Mods come from Thunderstore by default. Set
MODS_REPOSITORY=hexium to use Hexium, or prefix single entries with hex: / ts: to mix them. See Mod Repositories
See the full guide: docs/tutorials/getting_started_with_mods.md
This image uses version 3+ for all of its compose examples.
Please use Docker engine >=20 or make adjustments accordingly.
For production, pin to a major/minor tag (for example :3) and avoid :latest.
Guide to get started
Mod support is available through BepInEx. You are responsible for debugging mod-related startup issues. Modding is not officially supported by the Valheim developers, so incompatibilities can happen.
See Getting started with mods
Download Locations
DockerHub
GitHub Container Registry
Environment Variables
See further down for advanced environment variables.
| Variable | Default | Required | Description |
|---|
| PORT | 2456 | TRUE | Sets the port your server will listen on. Take note it will also listen on +2 (e.g., 2456, 2457, 2458) |
| APPID | 896660 | FALSE | Steam App ID exported for server startup compatibility. Override only if you know exactly why you need to. |
| NAME | Valheim Docker | TRUE | The name of your server! Make it fun and unique! |
| WORLD | Dedicated | TRUE | This is used to generate the name of your world. |
| PUBLIC | 1 | FALSE | Sets whether or not your server is public on the server list. |
| PASSWORD | <please set me> | TRUE | Set this to something unique! |
| ENABLE_CROSSPLAY | 0 | FALSE | Enable crossplay support as of Valheim Version >0.211.8 |
| TYPE | Vanilla | FALSE | This can be set to Vanilla, BepInEx, or ValheimPlus |
| PRESET | `` | FALSE | Normal, Casual, Easy, Hard, Hardcore, Immersive, Hammer |
| MODIFIERS | `` | FALSE | Comma-separated array of modifiers. EX: combat=easy,raids=muchmore |
| SET_KEY | `` | FALSE | Can be any of the following: nobuildcost, playerevents, passivemobs, nomap |
| MODS | <nothing> | FALSE | This is an array of mods separated by comma and a new line. Examples. Supported files are zip, dll, and cfg. |
| MODS_CONTINUE_ON_FAILURE | false | FALSE | Set to true to install every mod that downloads successfully and only warn about the rest, instead of failing the whole run (and restarting the container) on the first error. |
Container Env Variables
| Variable | Default | Required | Description |
|---|
| TZ | America/Los_Angeles | FALSE | Sets the timezone your container uses for timestamps and scheduled jobs. Valid timezone list. |
Auto Update
| Variable | Default | Required | Description |
|---|
| AUTO_UPDATE | 0 | FALSE | Set to 1 if you want your container to auto update! This means at the times indicated by AUTO_UPDATE_SCHEDULE it will check for server updates. If there is an update then the server will be shut down, updated, and brought back online if the server was running before. |
| AUTO_UPDATE_SCHEDULE | 0 1 * * * | FALSE | This works in conjunction with AUTO_UPDATE and sets the schedule for Odin's built-in auto-update job. Cron expression helper |
| AUTO_UPDATE_PAUSE_WITH_PLAYERS | 0 | FALSE | Does not process an update for the server if there are players online. |
Auto Backup
| Variable | Default | Required | Description |
|---|
| AUTO_BACKUP | 0 | FALSE | Set to 1 to enable auto backups. Backups are stored under /home/steam/backups which means you will have to add a volume mount for this directory. |
| AUTO_BACKUP_SCHEDULE | */15 * * * * | FALSE | Sets how frequently backups run via Odin's built-in scheduler. Cron expression helper. |
| AUTO_BACKUP_NICE_LEVEL | NOT SET | FALSE | Do NOT set this variable unless you are following this guide here |
| AUTO_BACKUP_REMOVE_OLD | 1 | FALSE | Set to 0 to keep all backups or manually manage them. |
| AUTO_BACKUP_DAYS_TO_LIVE | 3 | FALSE | Number of days to keep backups. Backups are compressed and generally small, but adjust this value to fit your storage limits. |
| AUTO_BACKUP_ON_UPDATE | 0 | FALSE | Create a backup on right before updating and starting your server. |
| AUTO_BACKUP_ON_SHUTDOWN | 0 | FALSE | Create a backup on shutdown. |
| AUTO_BACKUP_PAUSE_WITH_NO_PLAYERS | 0 | FALSE | Will skip creating a backup if there are no players. PUBLIC must be set to 1 for this to work! |
Scheduled Restarts
Scheduled restarts allow the operator to trigger restarts using Odin's built-in scheduler
| Variable | Default | Required | Description |
|---|
| SCHEDULED_RESTART | 0 | FALSE | Allows you to enable scheduled restarts |
| SCHEDULED_RESTART_SCHEDULE | 0 2 * * * | FALSE | Defaults to everyday at 2 am but can be configured with a valid cron expression |
Scheduler State
odin jobs persists runtime state at ODIN_SCHEDULER_STATE_FILE if set, otherwise ${GAME_LOCATION}/logs/jobs_state.json.
This state is included in odin status --json and Huginn /status as scheduler_state.
Migration Note (Cron Removed)
System cron is no longer used inside the container.
If you previously relied on container cron files, keep using the same AUTO_*_SCHEDULE and SCHEDULED_RESTART_SCHEDULE variables; they now run through Odin's built-in scheduler.
🛡️ Security: Migration to Rootless Design
To follow security best practices, this image has been moved to a rootless design. This means the container no longer runs as root by default. While this is a big win for security, it might require a quick tweak to your configuration to handle volume permissions correctly.
For the most reliable experience, we recommend explicitly setting the user directive to match your host user (usually 1000:1000). Here is how to implement that across different platforms:
| Platform | Implementation |
|---|
| Docker Compose | Add user: "1000:1000" to your service |
| Docker Run | Use the --user 1000:1000 flag |
| Kubernetes | Define runAsUser: 1000 in your securityContext |
Quick Tip: If you aren't sure what your IDs are, run id -u and id -g on your host machine to find the correct numbers to use!
For a complete walkthrough, see Rootless Design Guide.
Docker Compose
This image uses version 3+ for all of its compose examples.
Please use Docker engine >=20 or make adjustments accordingly.
Simple
This is a basic example of a Docker Compose file. You can apply any of the variables above to the environment section below but be sure to follow each variable's description notes!
services:
valheim:
image: mbround18/valheim:3
user: "1000:1000"
stop_signal: SIGINT
ports:
- "2456:2456/udp"
- "2457:2457/udp"
- "2458:2458/udp"
environment:
PORT: 2456
NAME: "Created With Valheim Docker"
WORLD: "Dedicated"
PASSWORD: "Banana Phone"
TZ: "America/Chicago"
PUBLIC: 1
volumes:
- ./valheim/saves:/home/steam/.config/unity3d/IronGate/Valheim
- ./valheim/server:/home/steam/valheim
Everything but the Kitchen Sink
services:
valheim:
image: mbround18/valheim:3
user: "1000:1000"
stop_signal: SIGINT
ports:
- "2456:2456/udp"
- "2457:2457/udp"
- "2458:2458/udp"
environment:
PORT: 2456
NAME: "Created With Valheim Docker"
WORLD: "Dedicated"
PASSWORD: "Strong! Password @ Here"
TZ: "America/Chicago"
PUBLIC: 1
AUTO_UPDATE: 1
AUTO_UPDATE_SCHEDULE: "0 1 * * *"
AUTO_BACKUP: 1
AUTO_BACKUP_SCHEDULE: "*/15 * * * *"
AUTO_BACKUP_REMOVE_OLD: 1
AUTO_BACKUP_DAYS_TO_LIVE: 3
AUTO_BACKUP_ON_UPDATE: 1
AUTO_BACKUP_ON_SHUTDOWN: 1
WEBHOOK_URL: "https://discord.com/api/webhooks/IM_A_SNOWFLAKE/AND_I_AM_A_SECRET"
WEBHOOK_INCLUDE_PUBLIC_IP: 1
UPDATE_ON_STARTUP: 0
volumes:
- ./valheim/saves:/home/steam/.config/unity3d/IronGate/Valheim
- ./valheim/server:/home/steam/valheim
- ./valheim/backups:/home/steam/backups
Bundled Tools
This repo includes a CLI tool called Odin for managing the server inside the container.
View advanced Odin environment variables
| Variable | Default | Required | Description |
|---|
| ADDRESS | 127.0.0.1:(PORT+1) | FALSE | Query address Huginn uses for server info. If unset, it defaults to loopback query port (PORT+1, usually 2457). Set this if Huginn should query a different interface or host. |
| HTTP_PORT | 3000 | FALSE | HTTP port Huginn listens on. Huginn binds to 0.0.0.0 and logs 127.0.0.1 links for local convenience. |
| HUGINN_INFO_CACHE_TTL_SECS | 2 | FALSE | Status cache TTL in seconds for A2S-backed responses (/status, /health, /readiness, /players). Lower values increase freshness but also query load. |
| CONNECT_REMOTE_HOST | <unset> | FALSE | Optional host/IP override for /connect/remote. If unset, Huginn falls back to PUBLIC_ADDRESS, then ADDRESS, then Odin public IP resolution. |
| CONNECT_STEAM_APP_ID | 892970 | FALSE | Steam app id used for connect deeplink generation (steam://run/<APP_ID>//+connect%20HOST:PORT). |
/metrics provides Prometheus metrics, listed in metrics.md./status provides a more traditional status page./connect/local redirects to steam://run/892970//+connect%20127.0.0.1:PORT (or returns JSON for browser CORS fetch clients)./connect/remote redirects to steam://run/892970//+connect%20<public host>:PORT (or returns JSON for browser CORS fetch clients)./health provides health status (200 when online, 503 when offline)./readiness provides Kubernetes-style readiness./liveness provides Kubernetes-style liveness./mods provides installed mod metadata./players provides player counts and names when available./metadata provides safe Odin/Huginn runtime metadata./openapi.json provides API spec./docs provides Swagger UI.
Note on ADDRESS: This can be set to 127.0.0.1:<your query port> or <your public IP>:<your query port> but does not have to be set. If it is set, it will prevent Odin from reaching out to AWS IP service to ask for your public IP address. Keep in mind, your query port is +1 of what you set in the PORT env variable for your Valheim server.
Another note: Your server must be public (e.g., PUBLIC=1) for Odin+Huginn to collect and report statistics.
Feature Information
As of March 2021, the TYPE variable can be used to automatically install BepInEx. For details, see Getting started with mods.
Huginn exposes Prometheus metrics for the server, the players online and the host: metrics reference.
This repo can automatically send notifications to Discord via the WEBHOOK_URL variable.
Only use the documentation link below if you want advanced settings!
View webhook support documentation
Guides
This guide covers the rootless model, host permission expectations, and migration steps from older setups.
View the rootless design guide
This guide covers a recommended path for transferring files between hosts, including world data, BepInEx configs, and backups.
View the file transfer tutorial
How to Access Your Container in Docker
docker exec -it $CONTAINER_NAME gosu steam bash
How to Restore a Backup
See the guide for restoring a backup
Additional Information
Discord Release Notifications
If you want release notifications in your Discord server:
Note: This Discord is only for release notifications; chat permissions are disabled.
Any support for this repository must take place on the Discussions.
Versions
- 3.x.x (Stable): LTS, minor fixes
- 2.x.x (Stable): Mod support and cleaned up the code base.
- 1.4.x (Stable): Webhook for Discord upgrade.
- 1.3.x (Stable): Health of codebase improvements.
- 1.2.0 (Stable): Added additional stop features and SIG for stopping.
- 1.1.1 (Stable): Patch to fix arguments.
- 1.1.0 (Unstable): Cleaned up image and made it faster.
- 1.0.0 (Stable): It works!
External Guides
