The Vintage Story server config is one file, serverconfig.json, in the server’s data folder. It holds the server name, port, player cap, password, whitelist mode, roles and PvP rules, plus a WorldConfig block with the seed and world-generation settings for a new world. Change it by editing the file with the server stopped, or live with /serverconfig. World rules on an existing world change with /worldconfig instead. Here is where the file is, what each setting does and the defaults in 1.22.
Where is the Vintage Story server config file?
The serverconfig.json file sits in the server’s data folder, next to the Saves, Mods and Logs folders. If you started the server with --dataPath, it is in that folder. Otherwise it uses the game’s normal data folder, so the Vintage Story server config location depends on the OS. The server creates the file with default values the first time it starts.
| How the server runs | Config location |
|---|---|
| Windows, default | C:\Users\YourName\AppData\Roaming\VintagestoryData\serverconfig.json |
| Linux, default | ~/.config/VintagestoryData/serverconfig.json |
Linux with the bundled server.sh |
The script’s DATAPATH, /var/vintagestory/data unless you changed it |
Any server started with --dataPath |
Inside that folder |
| A hosted server | The data folder in your host’s file manager (on Vintage Story server hosting, the panel’s file manager) |
Looking for server.properties? That’s Minecraft. Vintage Story server properties all live in this JSON file. One warning from the file itself: it is also loaded when you start a singleplayer world from the same data folder. That’s why the Vintage Story dedicated server guide gives the server its own data folder.
How to change server settings safely
There are two safe ways to change Vintage Story server settings. Stop the server, edit serverconfig.json, and start it again. Or leave it running and use /serverconfig in the console, which writes the change into the file for you. Don’t edit the file while the server runs. A single JSON typo stops the server on the next boot.
- JSON rules: text in double quotes, a comma after every line except the last in a block,
true/falsewithout quotes,nullfor empty. - If it breaks: the console says “Failed to read serverconfig.json. Did you modify it? See server-main.log for the affected line. Will stop the server.” The log names the line to fix.
- Wrong value type with
/serverconfig: “Failed saving config, you are likely suppling an incorrect value type” means a number went where a true/false belongs, or the other way round. - From the command line:
--setconfig="{ MaxClients: 20 }"writes a value and exits,--withconfigoverrides values for one launch, and--genconfigwrites a fresh default file.--genconfigdeletes your existing config, so copy it first.
Server settings in serverconfig.json
These are the server settings most owners change in the Vintage Story server config JSON, with their defaults from a fresh 1.22 file. Names are case-sensitive and must stay exactly as written. Everything not listed can usually stay at its default. The list of matching live commands is in Vintage Story server commands.
| Key | Default | What it does |
|---|---|---|
ServerName |
“Vintage Story Server” | Name in the public list, 4 to 80 characters |
ServerDescription |
null | Longer text for the public list |
WelcomeMessage |
“Welcome {0}, may you survive well and prosper” | Join message; {0} is the player name. Use "" to turn it off, never null (clients crash) |
Port |
42420 | Port the server listens on |
Ip |
null | Network interface to bind; null means all |
MaxClients |
16 | Player cap. More players need more RAM and CPU |
MaxClientsInQueue |
0 | How many can wait in a queue when the server is full |
Password |
null | Join password, or null for none |
WhitelistMode |
0 | 0 = default (on for dedicated servers), 1 = off, 2 = on |
AdvertiseServer |
false | Show the server in the public list |
VerifyPlayerAuth |
true | Checks every player owns the game and is logged in |
AllowPvP |
true | Players can damage each other |
AllowFireSpread |
true | Fire spreads to flammable blocks |
AllowFallingBlocks |
true | Sand and gravel fall |
PassTimeWhenEmpty |
false | Keep the calendar running with nobody online |
MaxChunkRadius |
12 | Highest view distance a player may use, in chunks. Higher needs more RAM |
DefaultRoleCode |
“suplayer” | Role new players get |
StartupCommands |
null | Commands run on every start, one per line |
KickClientsAfterAfkSeconds |
0 | Kick idle players after this long; 0 is off |
ServerLanguage |
“en” | Language of server messages |
ModPaths |
“Mods” plus the data folder’s Mods | Where the server looks for mods |
ModIdBlackList |
null | Players running any of these mod IDs can’t join |
DieBelowDiskSpaceMb |
400 | Shuts the server down when free disk space drops this low |
A config for a small private group usually only touches a few lines:
"ServerName": "Riverbend",
"WelcomeMessage": "Welcome {0}. Winter is coming.",
"MaxClients": 8,
"Password": null,
"WhitelistMode": 0,
"AllowPvP": false,
"PassTimeWhenEmpty": false,
"StartupCommands": "/op YourName",If you change MaxClients and the server keeps another value, it was started with --maxclients, which overrides the file. Hosted servers in “hosted mode” lock MaxClients, MaxChunkRadius, Upnp and the tick settings, and the server answers “Can’t access this feature, this server is in hosted mode.”
Vintage Story server whitelist: on, off and adding players
A Vintage Story dedicated server has its whitelist on by default since 1.20, so only players you add can join. Add them with /whitelist add Name. To turn the whitelist off, set "WhitelistMode": 1 in the file, or run /serverconfig whitelistmode off on a running server. After that, anyone with the address (and the password, if you set one) can join.
| WhitelistMode | Command | Effect |
|---|---|---|
| 0 | /serverconfig whitelistmode default |
On for dedicated servers, off for a singleplayer world opened to LAN |
| 1 | /serverconfig whitelistmode off |
Disabled: anyone can join |
| 2 | /serverconfig whitelistmode on |
Always on |
You may still see "OnlyWhitelisted" in older guides and files. It is obsolete and no longer does anything; WhitelistMode is the setting that counts. If you want to disable the whitelist but keep strangers out, add a password, or set DefaultRoleCode to suvisitor so newcomers can only look and chat until you promote them.
Vintage Story server password: how to set one
To set a Vintage Story server password, put it in the Password key, for example "Password": "hearthfire", and restart. Or run /serverconfig password hearthfire on a live server. Passwords can’t contain spaces. Remove it with /serverconfig nopassword, or set the key back to null. Players type the password into the server’s entry in their Multiplayer list.
The wiki rates the whitelist as significantly more secure than a password. Many groups use both.
Roles and privileges
The Roles list in serverconfig.json defines what each kind of player may do. A fresh file has nine: suvisitor, crvisitor, limitedsuplayer, limitedcrplayer, suplayer, crplayer, sumod, crmod and admin. Each role has a privilege level, a list of privileges, a default game mode and land-claim limits.
- Land claims:
suplayermay claim up to 8 chunks’ worth (LandClaimAllowance262144) in at most 3 areas. Raise these for builders. - Spawn points:
DefaultSpawnorForcedSpawnper role, for example a visitor area. - Assigning roles: with commands,
/player Name role sumod, not by editing the file.
Vintage Story server world config
The WorldConfig block in serverconfig.json describes the world the server creates: Seed, WorldName, SaveFileLocation, PlayStyle, WorldType and a WorldConfiguration list of rules. It is only read when a new world is made. Once the save exists, changes here do nothing; use /worldconfig on the running world.
"WorldConfig": {
"Seed": "123456789",
"SaveFileLocation": "/home/vintagestory/data/Saves/default.vcdbs",
"WorldName": "Riverbend",
"PlayStyle": "surviveandbuild",
"WorldType": "standard",
"WorldConfiguration": {
"deathPunishment": "keep",
"temporalStorms": "rare",
"creatureHostility": "aggressive",
"daysPerMonth": "12",
"graceTimer": "3"
}
}PlayStyle:surviveandbuild(standard),exploration,wildernesssurvival,homosapiensorcreativebuilding.WorldType:standardorsuperflat.SaveFileLocation: which save to load. If the file doesn’t exist, the server creates a new world there.Seed: even the same seed doesn’t guarantee exactly the same world every time.
Common rules and their defaults: deathPunishment drop (or keep), playerlives -1 (unlimited), temporalStorms sometimes, creatureHostility aggressive, daysPerMonth 9, harshWinters true, caveIns off.
Vintage Story server world gen settings that only work at creation
Several world gen settings can only be set before the world exists: startingClimate, graceTimer, worldClimate, worldWidth and worldLength (default 1024000), polarEquatorDistance, landcover, oceanscale, upheavelCommonness and landformScale. Others, such as globalTemperature, globalPrecipitation and globalForestation, can change later but only affect chunks that haven’t been generated yet.
The wiki’s own advice for custom world generation on a server: create the world in singleplayer with the Customize screen, then copy the .vcdbs save into the server’s Saves folder and point SaveFileLocation at it. You get sliders instead of typing JSON keys.
Changing world config on an existing world
On a world that already exists, run /worldconfig <key> <value>, for example /worldconfig deathPunishment keep, then restart. If the key was never stored in that save, create it with /worldconfigcreate bool <key> true. Keys are case-sensitive.
Other config files: servermagicnumbers.json
Next to serverconfig.json sits servermagicnumbers.json, with engine tuning values. Most owners never open it. The ones worth knowing: ServerAutoSave (300 seconds between autosaves) and MaxWorldgenThreads / MaxPhysicsThreads (1 each by default). The autosave interval can also be changed live with /serverconfig autosaveintervall.
When server config changes don’t apply
When a Vintage Story server config change doesn’t seem to apply, check four things in order: was the world already created (then use /worldconfig), was the file edited while the server ran, is a launch option or hosted mode overriding the value, and did the server actually restart. The log usually shows which.
| Symptom | Cause and fix |
|---|---|
World rules in WorldConfiguration ignored |
The world exists already. Use /worldconfig. |
| Server stops on boot after an edit | JSON error. Fix the line named in server-main.log. |
| Edits don’t load | The server read the file before your edit. Stop it, edit, start it again, or use /serverconfig live. |
| MaxClients won’t change | --maxclients on the command line, or the host’s hosted mode. |
| Players crash on join after a welcome-message change | WelcomeMessage set to null. Use "". |
| Singleplayer settings changed too | The server and your game share a data folder. Give the server its own with --dataPath. |
Skip the setup: change settings by asking
If JSON commas aren’t how you want to spend a game night, GameTeam’s Vintage Story server hosting lets the built-in AI copilot handle the config. Tell it “set the password to hearthfire, turn PvP off, cap it at 8 players and make deaths keep inventory” and it edits serverconfig.json, runs /worldconfig deathPunishment keep, restarts the server and reads the values back to confirm. The file stays open to you in the file manager too. You pay per GB of RAM, from $0.49/GB a week (or $1.99/GB billed monthly), with unlimited slots.
FAQ
Where is serverconfig.json on a Vintage Story server?
In the server’s data folder: %AppData%\VintagestoryData on Windows, ~/.config/VintagestoryData on Linux, or whatever folder --dataPath points to.
How do I disable the whitelist on a Vintage Story server?
Run /serverconfig whitelistmode off, or set "WhitelistMode": 1 with the server stopped. Consider a password if the address is shared widely.
Why didn’t my WorldConfig changes do anything?
The WorldConfig block is only read when a world is created. For an existing world, use /worldconfig and restart.
Can I reset serverconfig.json to defaults?
Yes. Stop the server, move the file somewhere safe and start the server: it writes a fresh default file. --genconfig does the same and exits.
How do I change world gen settings on an existing server?
Most terrain settings are fixed at creation. Either start a new world with a new SaveFileLocation, or create the world in singleplayer with Customize and upload it.
Do mods add their own config files?
Many do, usually in a ModConfig folder in the data folder after the first start. Their keys depend on the mod; see how to add mods to a Vintage Story server.