# How to Set Up Caves on Your Don't Starve Together Server (Master + Caves Shards) (/docs/dont-starve-together/caves-shard-setup)



import { Step, Steps } from 'fumadocs-ui/components/steps';
import { File, Folder, Files } from 'fumadocs-ui/components/files';

Don't Starve Together's signature feature is the **Caves shard** — a separate underground world connected to the surface via sinkholes. Most new server admins fail to set this up because it requires **two shards** (Master = surface, Caves = underground) and a precise mix of `cluster.ini`, per-shard `server.ini`, and `worldgenoverride.lua` files. This page walks through the entire workflow.

How DST Sharding Works [#how-dst-sharding-works]

DST runs caves as a **second server process** (called a shard) that the master server proxies players into when they enter a sinkhole. Both processes:

* Read the same `cluster.ini` (cluster-wide settings)
* Have their own `server.ini` (shard-specific port + role)
* Have their own `worldgenoverride.lua` (different presets — surface vs cave)
* Communicate over a `master_port` set in `cluster.ini`

If any of those four pieces is wrong, players get stuck at "Connecting to shard..." or sinkholes do nothing.

File Structure [#file-structure]

This is what a working two-shard cluster looks like:

<Files>
  <Folder name="DoNotStarveTogether" defaultOpen>
    <Folder name="Cluster_1" defaultOpen>
      <File name="cluster.ini" />

      <File name="cluster_token.txt" />

      <File name="adminlist.txt" />

      <Folder name="Master" defaultOpen>
        <File name="server.ini" />

        <File name="worldgenoverride.lua" />

        <File name="modoverrides.lua" />
      </Folder>

      <Folder name="Caves" defaultOpen>
        <File name="server.ini" />

        <File name="worldgenoverride.lua" />

        <File name="modoverrides.lua" />
      </Folder>
    </Folder>
  </Folder>
</Files>

Enable Caves [#enable-caves]

<Steps>
  <Step>
    Stop the server [#stop-the-server]

    Stop your DST server from **Console** in the [XGamingServer Panel](https://panel.xgamingserver.com).
  </Step>

  <Step>
    Edit cluster.ini [#edit-clusterini]

    Open `DoNotStarveTogether/Cluster_1/cluster.ini` in **Files**. Make sure the `[SHARD]` section is set up correctly:

    ```ini
    [SHARD]
    shard_enabled = true
    bind_ip = 127.0.0.1
    master_ip = 127.0.0.1
    master_port = 11001
    cluster_key = supersecretkey
    ```

    | Key             | Value        | Why                                             |
    | --------------- | ------------ | ----------------------------------------------- |
    | `shard_enabled` | `true`       | **Required** — without this, caves never load   |
    | `bind_ip`       | `127.0.0.1`  | Both shards on the same machine                 |
    | `master_ip`     | `127.0.0.1`  | Caves connects to Master at this IP             |
    | `master_port`   | `11001`      | Internal shard-to-shard channel (any free port) |
    | `cluster_key`   | (any string) | Both shards must use the same key               |
  </Step>

  <Step>
    Configure the Master shard [#configure-the-master-shard]

    Open `Cluster_1/Master/server.ini`. It should contain:

    ```ini
    [SHARD]
    is_master = true
    name = Master

    [NETWORK]
    server_port = 10999

    [STEAM]
    authentication_port = 8766
    master_server_port = 27018
    ```

    The Master shard is the surface world. `server_port` is what players connect to from the in-game browser.
  </Step>

  <Step>
    Create the Caves shard folder [#create-the-caves-shard-folder]

    If a `Cluster_1/Caves/` folder doesn't exist, create it. Inside it, create `server.ini`:

    ```ini
    [SHARD]
    is_master = false
    name = Caves

    [NETWORK]
    server_port = 11000

    [STEAM]
    authentication_port = 8768
    master_server_port = 27019
    ```

    Critical: every port in this file must be **different** from the Master shard's `server.ini`. Use the table below.
  </Step>

  <Step>
    Add Caves world generation [#add-caves-world-generation]

    Inside `Cluster_1/Caves/`, create `worldgenoverride.lua`:

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

    Available cave presets: `DST_CAVE` (standard), `DST_CAVE_PLUS` (more resources), `COMPLETE_DARKNESS` (extreme).
  </Step>

  <Step>
    Save and start [#save-and-start]

    Save all files and start the server from **Console**. Watch the console output for `Caves shard ready` — that confirms the second process started.
  </Step>
</Steps>

Port Reference [#port-reference]

To prevent collisions, use this layout for any DST cluster:

| Setting                       | Master  | Caves   |
| ----------------------------- | ------- | ------- |
| `[NETWORK] server_port`       | `10999` | `11000` |
| `[STEAM] authentication_port` | `8766`  | `8768`  |
| `[STEAM] master_server_port`  | `27018` | `27019` |

`master_port` in `cluster.ini` (e.g. `11001`) is separate — it's the internal channel between Master and Caves processes.

Verifying Caves Work [#verifying-caves-work]

After the server starts:

1. Connect from the in-game browser
2. Find a **sinkhole** in the world (round dark hole, usually near rocky biomes)
3. Right-click the sinkhole — your character should rappel down with a transition screen
4. You spawn in the caves with the lighting system active

If you fall in and immediately come back out: the Caves shard isn't running. Check the server console for cave shard errors.

Common Issues [#common-issues]

| Problem                                | Cause                                                                                                       | Fix                                                                          |
| -------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| Sinkholes do nothing                   | `shard_enabled = false` in cluster.ini                                                                      | Set `true`, restart                                                          |
| "Connecting to shard..." hangs forever | Port collision between Master and Caves `server.ini`                                                        | Use the port table above                                                     |
| Caves loads but Master doesn't         | `cluster_key` mismatch between cluster.ini and server.ini files, or `is_master` set wrong                   | Both shards need matching `cluster_key`; only Master gets `is_master = true` |
| Caves regenerates every restart        | The Caves shard has no save folder yet — first boot creates it. Don't delete `save/` after first generation | —                                                                            |
| Mods only work on surface              | Mods must be enabled in **both** `Master/modoverrides.lua` AND `Caves/modoverrides.lua`                     | Copy modoverrides to Caves folder                                            |

Disabling Caves [#disabling-caves]

If you want a surface-only server:

1. In `cluster.ini`, set `shard_enabled = false`
2. Restart

The Caves shard process won't start, and sinkholes become decorative.

Related Guides [#related-guides]

* [Configure Your Server](/docs/dont-starve-together/configure-your-server)
* [World Generation](/docs/dont-starve-together/world-generation)
* [Install Mods](/docs/dont-starve-together/install-mods)
* [Mod Configuration](/docs/dont-starve-together/mod-configuration)