Don't Starve Together server: cluster, caves and mods

A Don't Starve Together dedicated server is not one program. It is a cluster: a folder of shared configuration plus one server process per world. Almost everybody wants two - the Forest as the Master shard and the Caves as a secondary shard - and that is the single fact that makes DST hosting different from every other game on this blog. Two processes, two ports, two sets of mods, one save. Add a free Klei cluster token, which nobody can generate for you, and you have the whole shape of it. This guide goes through every file, every setting, and the mistakes that leave people staring at a server that starts and never appears.

What a cluster is: shards, Master and Caves#

A shard is one server process running one world. A cluster is a set of shards that share a name, a password, an admin list and a save. Exactly one shard is the Master; the rest connect to it. By convention the Master runs the Forest and one secondary shard runs the Caves, which is why the folders are usually called Master and Caves.

When a player climbs down a sinkhole, they are not loading a new area of the same world. They are disconnecting from one server process and connecting to another, with their character handed across the shard link. That explains a lot of DST's behaviour:

• Caves have their own day counter, their own season state and their own world settings.
• The Caves shard runs all the time, whether anybody is down there or not.
• If the Caves process is dead, the sinkholes say caves are unavailable and the Forest carries on perfectly happily.
• A rollback is per-shard unless you roll both back together, which is how people end up with a Forest on day 210 and Caves on day 195.

You can run a Forest-only cluster and it works fine; the Caves shard is optional. It is also where most of the late game is, so treat it as standard and size for two processes from the start.

Requirements and resource usage#

Each shard is a separate, largely single-threaded process. Two shards therefore want two cores rather than one fast one, which is the opposite of the advice for most survival games.

• Memory is split between the shards, roughly evenly on a mature world. A Forest shard alone is comfortable in 512-700 MB early on and climbs as the map is explored and built on.
• CPU is spent on entity simulation, and DST worlds accumulate entities relentlessly - every dropped item, every planted tree, every boat. A world in its third summer costs meaningfully more than a fresh one.
• Disk is small. The install is a few gigabytes, and the save data is megabytes, not gigabytes.
• Network is modest and scales with tick_rate and player count.

pause_when_empty = true is the setting that makes small plans viable: with nobody connected the simulation stops and both shards idle at almost nothing.

Installing, the Klei token and the folder layout#

The dedicated server is a free anonymous SteamCMD download, app id 343050. You do not need to own the game on the account you install it with.

$ steamcmd +force_install_dir /home/dst/server +login anonymous \    +app_update 343050 validate +quit

The binaries are bin64/dontstarve_dedicated_server_nullrenderer_x64 and the 32-bit bin/dontstarve_dedicated_server_nullrenderer. They expect to be run from their own directory.

Configuration does not live with the install. It lives in a cluster folder under the user's Klei directory:

~/.klei/DoNotStarveTogether/MyDediServer/  cluster.ini              settings shared by every shard  cluster_token.txt        your Klei token, nothing else in the file  adminlist.txt            one Klei user id per line  whitelist.txt  blocklist.txt  Master/    server.ini    worldgenoverride.lua    modoverrides.lua    save/  Caves/    server.ini    worldgenoverride.lua    modoverrides.lua    save/

The token is the part you cannot skip. Sign in at the Klei accounts site, open the Don't Starve Together server section, add a server, and copy the token it issues. Paste it into cluster_token.txt as the only content of the file - no quotes, no trailing text. It is free, it is tied to your Klei account, and Klei will reject any token it did not issue, which is why no host can create one for you. Running two live clusters on the same token will knock one of them offline, so generate one per server.

RE:NODE asks for this before the install runs: the Don't Starve Together line is one of the few that needs a credential of your own, the server itself is created as soon as payment clears, and the installation waits on the Setup tab until you paste the token in.

Then start both shards. On your own machine that is two commands, usually two services:

$ cd /home/dst/server/bin64$ ./dontstarve_dedicated_server_nullrenderer_x64 \    -console -cluster MyDediServer -shard Master$ ./dontstarve_dedicated_server_nullrenderer_x64 \    -console -cluster MyDediServer -shard Caves

Useful flags: -console enables console input, -cluster picks the cluster folder, -shard picks the shard folder inside it, -persistent_storage_root moves the whole Klei directory somewhere else, and -monitor_parent_process makes a shard exit when its supervisor does, which stops orphaned Caves processes.

The Caves shard needs to be told to generate a cave world rather than another forest. That is a worldgenoverride.lua in the Caves folder:

return {  override_enabled = true,  preset = "DST_CAVE",}

The Master equivalent uses preset = "SURVIVAL_TOGETHER". Get this wrong and you will have a cluster with two forests and no caves, which cannot be fixed without regenerating the Caves world.

cluster.ini, setting by setting#

One file, four or five sections, shared by every shard in the cluster.

[GAMEPLAY]game_mode = survivalmax_players = 6pvp = falsepause_when_empty = truevote_enabled = true[NETWORK]cluster_name = The Long Wintercluster_description = Cooperative, mods on, no griefingcluster_password = hollow-stalagmitecluster_intention = cooperativelan_only_cluster = falseoffline_cluster = falsetick_rate = 15whitelist_slots = 0autosaver_enabled = true[MISC]console_enabled = truemax_snapshots = 6[SHARD]shard_enabled = truebind_ip = 127.0.0.1master_ip = 127.0.0.1master_port = 10889cluster_key = a-long-random-string[STEAM]steam_group_only = falsesteam_group_id = 0steam_group_admins = false

Four of these are worth a sentence each.

`shard_enabled`. If this is false, the Caves shard will start, fail to find a Master and sit there. It is the most common reason a Caves process runs and the sinkholes still say caves are unavailable.

`cluster_key` and `master_port`. The shards authenticate to each other with the key and talk over master_port on master_ip. When both shards are on the same machine, leave those at 127.0.0.1 and 10889; that traffic never needs to leave the box and should not be exposed.

`tick_rate`. Fifteen is the default and is fine for a cooperative group. Raising it to 30 makes combat feel crisper and roughly doubles both the CPU cost per player and the bandwidth. On a small plan that trade usually is not worth it.

`offline_cluster`. Setting this to true disconnects the cluster from Klei entirely - no token needed, no server browser entry, and no workshop mods. It is for a LAN party, not for a server you want people to find.

server.ini and the ports each shard needs#

Each shard folder has its own server.ini, and the values must differ between shards:

[NETWORK]server_port = 10999[SHARD]is_master = true[STEAM]master_server_port = 27018authentication_port = 8768[ACCOUNT]encode_user_path = true

[NETWORK]server_port = 10998[SHARD]is_master = falsename = Cavesid = 2[STEAM]master_server_port = 27019authentication_port = 8769[ACCOUNT]encode_user_path = true

Everything DST uses is UDP. A shard needs its own server_port, its own master_server_port and its own authentication_port, all distinct from every other shard's - sharing any of the three is why one shard starts and the other quietly does not. If you want LAN discovery to work, keep server_port in the 10998-11018 range; for internet play any free port is fine. The reasons query-style ports exist at all are in game server ports explained.

is_master is what makes a shard the Master. Two shards with is_master = true in the same cluster is a cluster that will not link. id must be unique per shard, and name is the label the game shows for that world.

On a panel you do not edit these by hand as often as you think - the ports are allocated for you. RE:NODE's Don't Starve Together plans come with two allocations, and further ports are added and removed on the Network tab if you want a third shard.

Players find the server through the in-game browser, filtered by name. Direct connection also works: open the console in game with the backtick key and run c_connect("203.0.113.10", 10999, "hollow-stalagmite"). That is the reliable route when the browser is slow, and the only route if the listing has not refreshed yet.

Admins, whitelist and the block list#

Three plain text files in the cluster folder, one Klei user id per line. Klei ids look like KU_aB3dEf7h and are stable per account.

KU_aB3dEf7hKU_9zQ2mNp1

whitelist.txt works with whitelist_slots: if you set whitelist_slots = 2 on a six-player server, four slots are open to anyone and two are held for the listed players even when the server looks full. blocklist.txt is the ban list and is written by the server when you ban someone in game.

The reliable way to get a player's id is to have them join once and run c_listallplayers() in the console, which prints every connected player with their id. Players can also read their own from the Klei account page. The files are read at shard start, so add ids and restart, or promote in game and let the server write the file itself.

Console commands, rollbacks and snapshots#

DST's console is Lua. Commands are typed into the shard's console - the panel console box, or the in-game console opened with the backtick key if you are an admin. In game, the console has a local and a remote mode; the remote one sends the command to the server, and you toggle between them with control and backtick. Running a server command in local mode is the reason nothing appeared to happen.

Snapshots are DST's own rollback points, capped by max_snapshots and kept in the shard's save folder. c_rollback(2) goes back two of them. Two things about this catch people out. Snapshots are per shard, so rolling the Forest back without the Caves leaves the two worlds on different days - roll both, in quick succession. And snapshots live on the same disk as the save, so they are protection against a bad decision, not against a lost server.

Real backups belong somewhere else. On RE:NODE every Don't Starve Together plan includes backup slots, stored off the machine they protect and restored with a button, and the Schedules tab will take one on a cron expression - a nightly copy plus one before you install a mod is the sensible pattern. Backups that actually restore explains why the restore half is the half that matters, and scheduled tasks worth having has more patterns worth copying.

Mods on a dedicated cluster#

Workshop mods on a dedicated server are a two-step job, and skipping either step is the reason most people's mods do not load.

Step one: tell the server to download them. In the game install directory, mods/dedicated_server_mods_setup.lua lists what SteamCMD should fetch on start:

ServerModSetup("1595631294")ServerModSetup("375850593")ServerModCollectionSetup("1234567890")

The numbers are workshop file ids, taken from the end of the mod's workshop URL. ServerModCollectionSetup takes a collection id and pulls everything in it, which is much easier to maintain for a large list.

Step two: enable them per shard. modoverrides.lua in each shard folder decides which downloaded mods are actually on, and carries their configuration:

return {  ["workshop-1595631294"] = {    enabled = true,    configuration_options = {      ["language"] = "en",    },  },  ["workshop-375850593"] = {    enabled = true,  },}

The key is the literal string workshop- followed by the id. Anything that changes the world needs the same entry in both Master/modoverrides.lua and Caves/modoverrides.lua, with identical settings - a mod enabled on one shard and not the other produces missing prefabs and crashes when a player moves between them. The simplest discipline is to keep one file and copy it to both folders.

Clients are made to download matching mods automatically when they join, which is why a modded cluster needs offline_cluster = false. Mods update on the workshop whenever their authors publish, and a DST update will break a proportion of them, so back the cluster up before a game patch and do not be surprised when the first start after one fails. The general mechanics of workshop content on servers are in Steam Workshop mods on dedicated servers, and the recovery drill is in what to do when a mod update breaks.

Troubleshooting#

"Your server will not start without a token." cluster_token.txt is missing, empty, in the wrong folder, or contains something besides the token. It belongs in the cluster folder, not in a shard folder.

The server runs but is not in the browser. Check offline_cluster and lan_only_cluster are both false, that the token is valid, and that no other live cluster is using the same token. Test with c_connect from the in-game console: if a direct connection works, the server is fine and only the listing is missing.

Caves are unavailable in game. Either the Caves process is not running, or the link is broken. Check shard_enabled = true in cluster.ini, is_master = false in Caves/server.ini, that both shards have the same cluster_key, and that the two shards have different server_port, master_server_port and authentication_port values.

One shard starts and the other exits immediately. Almost always a port collision between the two server.ini files, or two shards with the same id.

Mods do not load. Confirm the id appears in both dedicated_server_mods_setup.lua and each modoverrides.lua, that the workshop- prefix is present in the overrides, and that the cluster is not offline. The shard log prints each mod it loads by name.

The world is on the wrong day after a rollback. You rolled one shard. Roll the other back the same number of snapshots, then restart both.

Both shards restart repeatedly. Look for the memory limit first. A cluster sized for one shard will be stopped at its limit once Caves are generated, and a crash loop is usually resource exhaustion rather than a config error - why your game server keeps restarting walks through telling them apart.

FAQ#

Do I need my own Klei token?

Yes, and it has to be yours. It is free from your Klei account page and takes a minute, but Klei rejects any token it did not issue to that account, so no host can supply one. Generate a separate token for each cluster you run.

Can I run Don't Starve Together without caves?

Yes. A Forest-only cluster is one shard and one port, and it works completely. You lose the caves content, which is most of the mid and late game, and adding caves later means generating a new cave world rather than revealing one.

How many players can a DST server hold?

max_players defaults to 6 and can be raised. The practical ceiling is the CPU cost of a mature world and the amount of griefing you are prepared to police; most groups settle between 6 and 10. The limit counts the whole cluster, not each shard.

Where does the save actually live?

In save inside each shard folder, under the cluster directory. The Forest and the Caves keep separate save data, which is why rollbacks are per shard. Back up the whole cluster folder, not one shard.

Why do my mods work on the Forest but crash the Caves?

Because modoverrides.lua is per shard and the two files have drifted apart. Any mod that affects the world must be enabled with identical configuration in both, or a player moving between shards hits prefabs that only exist on one side.

Is it safe to raise the tick rate?

It is safe, but it costs. Going from 15 to 30 roughly doubles the per-player CPU and bandwidth, and on a small plan that shows up as lag with a full server rather than smoother combat. Try it with your usual group and change it back if the server graph climbs.