Vintage Story Server Config: serverconfig.json Explained

The Vintage Story server config, data/serverconfig.json, controls a dedicated server’s name, access, common gameplay rules and other server behavior. The file also contains a WorldConfig section, but world-generation choices have a different lifecycle from everyday server settings. This reference uses a freshly generated stable 1.22.7 config because the official wiki’s defaults section is labeled 1.20.0.

Find the settings that belong in serverconfig.json#

The dedicated server reads its main settings from serverconfig.json in the data directory. With the default layout, that is data/serverconfig.json; a custom --dataPath changes where the data folder lives. The UI for a hosted server may show a different file-manager root, so follow that panel’s path label instead of assuming it matches a self-hosted folder.

The file groups server-wide options with related sections such as Roles and WorldConfig. It is not a list of 77 values that all need attention: many entries identify generated server state, installation paths or values that belong to another task. The new 1.22.7 file used here reported ConfigVersion 1.10. The official server config reference still marks its defaults as last verified for 1.20.0 and shows an older ConfigVersion example, so use it for field explanations, not as a current default dump.

File area	What it controls	Where to look next
Top-level settings	Name, access, gameplay, player count and server behavior	This guide
Roles	Player roles and privileges	The dedicated roles guide when available
WorldConfig	The selected save and world-generation options	World configuration reference
Startup arguments	Values passed when the server process launches	The dedicated-server guide
servermagicnumbers.json	Advanced game constants	Leave it alone unless a specific guide tells you why to change one

World generation deserves special care. Options used to create a world may not change an already generated save just because you edit the JSON. A world is stored separately as a .vcdbs database; the game uses SQLite for that file. Treat the world and its config as separate pieces when you plan a migration or update, and make a recoverable copy before you change either.

Set a name, description, welcome message and password#

The fields below shape how the server appears and how players connect. These are the values from a fresh 1.22.7 server config, not a recommendation for every group.

Key	Fresh default	What it does
ServerName	Vintage Story Server	Name shown for the server
ServerDescription	null	Optional description
WelcomeMessage	Welcome {0}, may you survive well and prosper	Message shown when a player joins; {0} is the player name
Password	null	Optional additional join password
AdvertiseServer	false	Whether the server is advertised in the public server list

An empty password does not mean a server is open to everyone. Dedicated servers use a whitelist by default, and the account-authentication setting should remain on. Think of the password and whitelist as different controls: one is a shared secret, while the other limits access by player account. For the exact current allow-list procedure, verify the server’s own help output; the older wiki command example and 1.22.7 /help output disagree. Do not paste a stale command into a live server because it appears in an old article.

Keep the description and welcome message useful to players: name the group or explain a simple joining rule. If you want a public listing, switch AdvertiseServer only after checking the other access controls and deciding that strangers may discover it. The separate dedicated-server guide covers server setup and connectivity; this page focuses on the settings inside the file.

Keep player access and authentication intentional#

WhitelistMode decides how the server treats its allow-list. A freshly generated 1.22.7 config uses 0, which means the game’s default mode; on a dedicated server that default keeps the whitelist enabled. The explicit values are 1 for off and 2 for on. Do not infer the effective access state from an older Boolean field such as OnlyWhitelisted; use the current WhitelistMode behavior and the server’s own help output.

VerifyPlayerAuth is true in the generated file. Keep it true. Every player needs their own Vintage Story game account, and the server checks that account when they join. Vintage Story is listed for PC on Windows, macOS and Linux; no console version is listed on the official requirements and downloads pages checked October 8, 2026. Turning off authentication is not a safe substitute for helping a real account onto the whitelist.

MaxClients is 16 by default. It is the game server’s configured limit, not a promise that 16 players fit every world or a hosting plan’s recommended player count. Mods, exploration and the group’s memory needs affect what works in practice. If the actual problem is who can join, use the server’s /help output for the installed release and the dedicated whitelist guide when it is published; this settings overview does not claim a successful authenticated join test.

Choose the default role and basic gameplay rules#

The default role for a new player is suplayer. It selects the starting role; it does not explain all role privileges, admin access or land-claim rules. Those are a separate job, and this overview will not tell you to promote every player or grant broad permissions just to get past a whitelist problem.

The main gameplay switches below start enabled in the tested file:

Key	Fresh default	Practical effect
DefaultRoleCode	suplayer	Role assigned to a player who has no role yet
AllowPvP	true	Allows player-versus-player damage
AllowFireSpread	true	Allows fire to spread
AllowFallingBlocks	true	Allows falling-block behavior

Decide these rules with the whole group before the world becomes busy. Disabling PvP will not settle every land-claim dispute, and turning off fire spread does not make a world invulnerable to every kind of loss. If you need role permissions or a server-specific rule set, change one setting at a time, explain it to players and keep a copy of the previous file.

Understand empty-world time and view distance#

PassTimeWhenEmpty is false by default. It controls whether the world clock advances when no players are online; it does not put the operating system or server process to sleep. If you change it, check how your group expects crops, animals and other time-dependent systems to behave while everyone is away.

MaxChunkRadius starts at 12. It is related to how much of the world the server sends around players. Raising it can make more terrain available at once, but also asks the server to handle more world data. There is no one value that fixes lag for every map, mod set and group. Keep the default unless you have a specific reason to change it and can observe the result with your own players.

AFK timers and AntiAbuse are separate behavior controls. The panel exposes common AFK and anti-abuse settings, but a setting’s presence does not make one threshold right for every community. The dedicated server log and /stats help you understand what the server reports; do not diagnose an overloaded world from a single config value. If you need to estimate resources, start with the group’s actual player count, mods and exploration pattern rather than treating MaxClients as a memory estimate. Our Vintage Story server RAM guide explains the rough formula and why it cannot predict every world.

Separate mod filters and startup behavior from installing mods#

ModIdBlackList and ModIdWhiteList let an owner filter mod IDs. They do not install a mod, check that its release supports the current game version, resolve a dependency or tell every player what to download. StartupCommands is also a separate field: it runs startup commands, so do not add a command there simply because it works once in the interactive console.

Vintage Story’s official mod catalog is the ModDB, not Steam Workshop. Server-side and universal mods distributed through ModDB can be offered to a player when they join; client-only mods need to be installed on each client. Check a mod’s current release, game-version tag, side and dependencies before adding it. The Vintage Story ModDB guide covers that workflow; this page only identifies the related config fields. If you name a mod in a guide, credit its author and link to its ModDB page.

Edit the JSON without racing the running server#

For a direct file change, stop the server first. The official server configuration page and dedicated-server guide describe applying file changes after a restart; the supported /serverconfig command can change supported settings while the server is running. The exact live command set is version-specific, so check /help before relying on a key or subcommand.

1. Stop the server and copy its config

   Stop the dedicated server cleanly. Save a separate copy of the current serverconfig.json before changing it so you can compare the file you started with and the one you edited.

2. Change one documented key

   Edit the existing JSON value instead of replacing the whole file with an old wiki sample. Keep quotes, commas and value types valid: true is a Boolean, while a name is a quoted string.

3. Validate the JSON and start the server

   Use a JSON parser or editor check before starting. Then read the console for parse errors and confirm the resulting value in the file or the game’s reported status where available.

4. Use a supported live command when appropriate

   If the server is already running, consult its /help output and use /serverconfig only for a supported setting. Do not edit the file concurrently and assume the running server will preserve that change.

If a setting seems to revert, do not immediately overwrite the current file again. Stop the server, save the file and startup log as they are, compare your copy against the saved version, and check whether the panel or a launch argument controls the same setting. That sequence narrows the cause without risking the only copy of the group’s current setup.

Use a panel form when you only need common fields#

You do not need to edit every key to change a server name, join password, player count or common gameplay rule. Game Hosting’s Vintage Story settings page writes its common form values to data/serverconfig.json when the server starts and preserves other keys; its page also points world options and new-world creation to the World tab. The dashboard exposes a subset of the file, not a complete JSON editor. It also has an owner access control so the owner can be added to the whitelist and made an admin, plus separate players, ModDB, version and backup areas.

For groups that want these common controls in a web form, Game Hosting’s Vintage Story plans are a fit to compare: the service documents three free backup slots, and the panel keeps the common settings with the rest of the server controls. Make and verify a copy before a risky change rather than treating a slot as a tested undo button. Anego’s official hosting is another route for players who prefer its in-game controls. These are different workflows, so choose the one that fits how your group wants to manage the world.

For the world-side options, see Vintage Story world settings for a multiplayer server. For more detail on choosing between a home server and a host, read how to choose a Vintage Story host. The important split is simple: use serverconfig.json for server-wide behavior, handle world-generation choices in WorldConfig, and stop the server before editing its file directly.

Sources checked October 8, 2026

• Official wiki: server config, dedicated server, world configuration, chunk data storage, adding mods, server commands
• Stable version API, system requirements, account portal, official ModDB
• Current Game Hosting settings and backup features were checked against the dashboard source and approved product facts. Defaults were checked against a locally generated stable 1.22.7 config and the dated field schema; the live whitelist command differs from the older wiki example, so exact whitelist instructions are deferred.

Quick answers

Where is Vintage Story serverconfig.json?

It is in the server data folder. In Game Hosting’s panel, the settings page identifies it as data/serverconfig.json.

What does MaxClients mean in Vintage Story?

MaxClients is the game server’s configured player limit, not the player recommendation printed on a hosting plan.

Why did my serverconfig.json edit disappear?

Stop the server before editing the file, or change supported values with /serverconfig while it is running. Then check the saved file and startup log.

Can I change Vintage Story settings without editing JSON?

A hosting panel may expose common settings in a form, but that does not make every serverconfig.json key editable there.