Vintage Story server: setup, config and mods

A Vintage Story dedicated server is the same download as the game's server package - VintagestoryServer with a .NET runtime underneath - configured by a single serverconfig.json in its data folder. It listens on port 42420, holds the world in one .vcdbs file, keeps every player's character inside that world, and whitelists by default on a dedicated server, so nobody can join until you add them. Memory starts around 1 GB and grows by roughly 300 MB per active player, more with large view distances or heavy mods. Mods are zip files in a Mods folder, and players who are missing a server's mods are offered the download when they join. This guide covers the install, every setting in serverconfig.json that matters, the world generation choices you only get once, roles and permissions, mods and backups.

How Vintage Story hosting works#

The server is a separate executable from the game client and does not need a game account to run, but players need their own accounts to join: with VerifyPlayerAuth on, which is the default, the server checks with Anego Studios' authentication service that each player owns the game.

A few properties shape everything else:

• The world and the characters are server-side. Inventories, skills and positions live in the world save on the server. A player's progress on your server stays on your server.
• One process, one world. The config names a save file; a different world means a different file and a restart.
• The data folder holds everything you care about. Config, saves, mods, logs and backups all live under one path, set with --dataPath. Back up that folder and you can rebuild the rest by downloading the server again.
• The server and clients must run the same game version. Minor patches are frequent; major versions change mods and sometimes world generation.

Requirements and resource usage#

The official guidance is about 1 GB of memory as a base plus 300 MB per player, with a reasonably fast CPU. In practice the variable that matters most is how much of the world is loaded, which is set by players' view distance up to the server's MaxChunkRadius.

• CPU: the server ticks at about 30 times a second by default. World generation for newly explored chunks is the heaviest load, which is why the first weeks of a world cost more than later ones.
• Disk: the save grows with explored area. A server with a few players exploring widely can reach several gigabytes over months; keep room for backups.
• Network: modest, with spikes when players travel fast and pull new chunks.

The single most effective control is MaxChunkRadius, which caps how far any player can see. Lowering it from 12 to 8 cuts memory and CPU sharply at the price of shorter view distance. CPU vs RAM for game servers is worth reading before deciding which resource to pay for.

Installing the server#

The server is downloaded from your Vintage Story account page, not through Steam. The Linux package is a .tar.gz named for the platform and version; Windows has an installer and a server executable alongside the client.

Current versions need a .NET runtime on Linux: .NET 8 for the 1.21 series and .NET 10 for 1.22 and later, according to the official setup guide - older versions needed older runtimes, so match the runtime to the version you run.

$ mkdir -p /srv/vintagestory/server /srv/vintagestory/data$ tar -xzf vs_server_linux-x64_<version>.tar.gz -C /srv/vintagestory/server$ cd /srv/vintagestory/server$ ./VintagestoryServer --dataPath /srv/vintagestory/data

The package also contains server.sh, a helper script with start, stop and status actions that runs the server in the background as a named user; edit the user name and paths at the top before using it. On Windows, the equivalent is a shortcut to the server executable with --dataPath= added to its target, so the data does not end up mixed into your client's own folder.

The first start creates the data folder:

data/  serverconfig.json  Saves/  Mods/  Logs/  Backups/

Stop the server with /stop in its console. Editing serverconfig.json while the server runs is pointless at best: the server may write its own in-memory copy back over your edit.

serverconfig.json, the settings that matter#

The file is JSON, written in full on first start. These are the keys worth reading, with their defaults:

{  "ServerName": "Vintage Story Server",  "ServerDescription": null,  "WelcomeMessage": "Welcome {0}, may you survive well and prosper",  "Ip": null,  "Port": 42420,  "Upnp": false,  "CompressPackets": true,  "AdvertiseServer": false,  "MaxClients": 16,  "Password": null,  "WhitelistMode": 0,  "VerifyPlayerAuth": true,  "TickTime": 33.333332,  "MaxChunkRadius": 12,  "SpawnCapPlayerScaling": 0.5,  "PassTimeWhenEmpty": false,  "AntiAbuse": 0,  "CorruptionProtection": true,  "RegenerateCorruptChunks": false,  "DieBelowDiskSpaceMb": 400,  "StartupCommands": null,  "ModPaths": ["Mods"]}

Notes worth more than a table cell:

• `WhitelistMode` 0 means whitelist on for a dedicated server. This is the single most common "nobody can join" report. Either add players or set it to 1 on purpose.
• `PassTimeWhenEmpty` decides whether seasons move while nobody plays. For a group that plays twice a week, false keeps winter from arriving unseen; for a busy public server it does not matter.
• `DieBelowDiskSpaceMb` is a safety net, not a nuisance. A server that runs out of disk mid-save can corrupt the world; this stops it first. If it triggers, clear old backups and logs.
• `StartupCommands` is handy for things that must be true after every start, such as an announcement or a role setting.

Many of these can also be changed live with /serverconfig, for example /serverconfig maxclients 20 or /serverconfig password followed by a value, which saves the change to the file as well.

World generation: choose once#

The WorldConfig section decides the world, and most of it only matters when the world is created.

"WorldConfig": {  "Seed": null,  "SaveFileLocation": "/srv/vintagestory/data/Saves/default.vcdbs",  "WorldName": "A new world",  "AllowCreativeMode": true,  "PlayStyle": "surviveandbuild",  "WorldType": "standard",  "WorldConfiguration": null,  "MapSizeY": null}

SaveFileLocation names the world file; pointing it at a file that does not exist creates a new world there. Seed fixes generation, or leave it empty for random. PlayStyle picks a preset - the standard survival preset, exploration and wilderness survival variants, and creative building - and WorldConfiguration holds the detailed settings that preset fills in: world size, climate, temporal storms, creature hostility, player lives, spawn radius and dozens more.

The practical way to set those details is not to type them. Create a world in the game client with the settings your group wants, and use the same choices on the server, or start the server, then adjust rules with /worldconfig before anyone has played. Terrain and climate settings only affect chunks generated after the change, so a world whose generation settings change halfway has a visible seam. Gameplay rules such as temporal storm frequency or creature hostility can be changed later with /worldconfig and take effect from then on. Agree on the generation settings before the first player joins.

Roles, the whitelist and admins#

Vintage Story has a proper role system. Default roles range from visitor roles that cannot build, through suplayer (the default survival player) and crplayer (creative), to moderator roles and admin. Each role has privileges and a land claim allowance.

/op Steinar                      give the admin role/player Steinar role sumod       survival moderator/player Mira whitelist on        allow a player to join/player Mira whitelist           check their status/kick Mira reason here/ban Mira reason here/role suplayer landclaimallowance 262144/announce Server restart in 10 minutes/stop

/op and /deop are shortcuts for setting and removing the admin role. Command syntax changed in the 1.18 command system rewrite, and older guides show the previous forms; the in-game command help is the authority for your version. The console has full rights, so the first admin is always made from the console.

Land claims are Vintage Story's grief protection: players claim areas up to their role's allowance, and others cannot build there. Set allowances deliberately for a public server - generous enough for real bases, small enough that one player cannot claim a whole valley. Server rules, moderation and staff covers the human side of running moderators.

Mods on the server#

Vintage Story mods are zip files placed in the Mods folder. Each declares in its modinfo.json which side it runs on: client-only, server-only, or universal. Server-only mods change nothing for players. Universal mods - nearly all content mods, anything adding blocks, items or creatures - must be on both sides. When a player joins a server with universal mods they lack, the game offers to download them from the official mod database, which makes running a modded server far easier than in most games.

Rules that keep a modded world healthy:

• Match the game version. A mod built for one major version is often broken on the next. Check each mod's supported version before updating the server.
• Add mods before the world is generated where they add terrain or ores. Like world generation settings, they only affect new chunks.
• Removing a content mod from a world leaves its blocks and items missing. Back up before removing anything.
• Code mods using Harmony patching do not work on ARM64 servers, according to the official guide. Run on x64 if you plan to use them.

Update mods and the server together, on a test copy first if the world matters. Running a test server beside production explains how, and what to do when a mod update breaks is the recovery order when it goes wrong anyway.

Ports and connecting#

The official setup guide opens 42420 on both TCP and UDP. Players join by address in the multiplayer menu, or from the public list if AdvertiseServer is true. Upnp is for home routers only and should stay off on a hosted machine. Game server ports explained covers testing a port from outside, which is the only test that counts.

Saves, backups and updates#

The world is a single .vcdbs file in Saves, which is an SQLite database underneath. Copying it while the server writes to it can produce a damaged copy, so do not back it up with a plain file copy of a running server.

• `/genbackup` writes a consistent copy of the world into the Backups folder while the server runs. Use it before anything risky.
• `/autosavenow` forces a save immediately, useful before a planned stop.
• Off-server copies. The Backups folder sits on the same disk as the world. Copy backups elsewhere on a schedule; backups that actually restore explains why a copy you have never loaded is not yet a backup.
• Before every game update, make a backup and keep it until the new version has run for a week. Major updates can change world generation, and a few have needed mods to catch up.

To restore, stop the server, put the backup file in place of the world file with the same name, and start. Keep the damaged file aside until you are sure.

Hosting it#

Vintage Story is not in the RE:NODE game catalogue, so there is no Vintage Story plan or pre-built install. The server runs well on a general-purpose Linux machine, which is what a dedicated server is: root access to install the .NET runtime, run server.sh or a service unit, and open 42420. VDS plans are prepared by hand and delivered within 24 hours. Your first hour on a new VDS covers the basics, systemd services for your apps how to keep the server running across reboots, and firewall rules that matter how to open one port without opening everything. For games that do have catalogue lines, see game servers.

Troubleshooting#

Players get "not whitelisted". WhitelistMode 0 means on for dedicated servers. Add them with /player name whitelist on.

The server will not start on Linux. The .NET runtime is missing or the wrong version for this game version. The first lines of the log say which.

Players are told they lack mods and the download fails. The mod is not on the official mod database, or its version there differs. Give players a direct download.

Memory grows until the server is killed. View distance. Lower MaxChunkRadius, then look at mods.

A visible seam appears in the terrain. World generation settings or worldgen mods changed after part of the world was generated. Expected; new settings only apply to new chunks.

The server shut itself down. Check for the low disk space message from DieBelowDiskSpaceMb, then clear old backups and logs.

FAQ#

What port does a Vintage Story server use?

42420 by default, set with Port in serverconfig.json. The official guide opens it on both TCP and UDP.

Why can nobody join my new Vintage Story server?

The whitelist is on by default for dedicated servers. Add players with /player name whitelist on, or set WhitelistMode to 1 to turn it off.

Do players have to install the server's mods?

Universal mods must be on both sides, but the game offers to download missing mods from the official mod database when a player joins. Server-only mods need nothing from players.

Where is my character saved?

In the world save on the server. Characters do not travel between servers, and a character on one world is unaffected by another.

How do I back up a running server?

Use /genbackup, which writes a consistent copy into the Backups folder, then copy that file somewhere else. Avoid copying the live .vcdbs file while the server is running.

How much RAM does a Vintage Story server need?

About 1 GB plus 300 MB per player as a baseline. View distance and mods move it most; lowering MaxChunkRadius is the quickest way to cut it.