---
title: "Configuring your Windrose server"
description: "Manage identity, passwords, and invite codes across your Windrose configuration files, and learn the formatting rules that prevent errors."
url: "https://www.gameserverkings.com/knowledge-base/windrose/configuration-overview/"
category: "Windrose"
category_url: "https://www.gameserverkings.com/knowledge-base/windrose/"
published: "2026-07-03T22:55:16.074Z"
updated: "2026-08-07T20:33:29.249Z"
source_format: "markdown"
site: "GameServerKings"
---

# Configuring your Windrose server

This guide covers `ServerDescription.json`, the main config file that controls how players find and connect to your Windrose server: server name, invite code, password, max players, and the choice between invite code or direct IP connection.

For world-specific settings (difficulty, multipliers, gameplay rules), see [World Settings](/knowledge-base/windrose/world-settings/).

## The Two-File System

Windrose splits its settings across two JSON files:

- **`ServerDescription.json`** lives in the server root at `R5/ServerDescription.json` and controls common server settings: name, invite code, password, max players, which world to load.
- **`WorldDescription.json`** lives inside each world's save folder and controls world-specific settings.

You can have multiple worlds, each with its own `WorldDescription.json`. `ServerDescription.json` selects which one is active. See [Managing Worlds](/knowledge-base/windrose/managing-worlds/) for that workflow.

## Critical Editing Rule

> [!WARNING] Always stop the server before editing either file
> Windrose rewrites these files on shutdown. If you edit while the server is running, your changes are overwritten the moment the server stops.

Procedure:

1. Stop the server (Console > **Stop**, wait for "Offline").

2. Edit the file in the File Manager on your [hosted Windrose server](/games/windrose/).

3. Save.

4. Start the server.

A missing comma or stray quote will prevent startup, so save carefully and consider using the panel's JSON syntax check (right-click > Edit usually highlights syntax errors). If your server fails to start after a config change, that's almost always the cause.

## ServerDescription.json Reference

Located at `R5/ServerDescription.json`. The most important fields are nested under `ServerDescription_Persistent`. A trimmed example:

```json title="R5/ServerDescription.json"
{
  "ServerDescription_Persistent": {
    "ServerName": "My GSK Windrose Server",
    "InviteCode": "PIRATES123",
    "IsPasswordProtected": false,
    "Password": "",
    "MaxPlayerCount": 4,
    "WorldIslandId": "0123456789ABCDEF",
    "AllowDirectConnection": false,
    "DirectConnectionPort": 7777,
    "DirectConnectionAddress": "0.0.0.0",
    "PersistentServerId": "DO_NOT_EDIT_THIS_VALUE"
  }
}
```

| Field | Notes |
|-------|-------|
| ServerName | Display name shown to connecting players |
| InviteCode | 6 or more characters, allowed: 0-9, a-z, A-Z (case-sensitive). If left blank, one is auto-generated on first boot |
| IsPasswordProtected | True to require a password in addition to the invite code |
| Password | The password itself when IsPasswordProtected is true |
| MaxPlayerCount | Cap of 8. Devs recommend 4 for best performance |
| WorldIslandId | Must match the `IslandId` in the active world's `WorldDescription.json` |
| AllowDirectConnection | True to expose the server via IP and port instead of (or in addition to) invite code |
| DirectConnectionPort | Default 7777 when direct connection is on |
| DirectConnectionAddress | Bind address; leave at `0.0.0.0` to listen on all interfaces |
| PersistentServerId | Auto-generated unique ID. **Never edit this**. Changing it can disconnect your server from its world data |

After editing, save and restart.

## Setting a Server Password

The invite code is its own access barrier, but for tighter control (paid Patreon-only servers, private friend groups), add a second password layer:

1. Stop the server.

2. Open `R5/ServerDescription.json`.

3. Set:

   ```json
   "IsPasswordProtected": true,
   "Password": "your_password_here",
   ```

4. Save and start.

Players will be prompted for the password in-game after the invite code resolves. The password is not case-sensitive but does require the exact string match.

## Changing the Invite Code

Two common reasons to rotate:

- Someone leaked the code to people you do not want
- You ran a temporary event and want to revert to your standard code

Procedure:

1. Stop the server.

2. Edit `InviteCode` in `R5/ServerDescription.json`. Must be at least 6 characters, only `0-9`, `a-z`, `A-Z`, case-sensitive.

3. Save and start.

4. Share the new code with your crew. Anyone holding the old code can no longer join.

> [!IMPORTANT] A reload is not enough for a new invite code
> A full restart (not just a reload) is required for invite code changes to apply cleanly.

## Direct Connection (IP and Port)

If your community is more comfortable with traditional server browsers and IP joins, enable direct connection:

1. Stop the server.

2. In `R5/ServerDescription.json`:

   ```json
   "AllowDirectConnection": true,
   "DirectConnectionPort": 7777,
   "DirectConnectionAddress": "0.0.0.0",
   ```

3. Save and start.

4. Confirm the panel's **Network** tab shows port 7777 (or whatever you chose) is allocated.

> [!IMPORTANT] Invite code or direct connection, not both
> You can use invite code OR direct connection, but not both simultaneously. Most users stick with the invite code since the Epic Online Services relay handles NAT traversal automatically without any player-side port forwarding.

## Changing Max Players

The server supports up to 8 slots, but the developers recommend 4 for the best performance. The cap of 8 is enforced at the engine level; you cannot set it higher.

1. Stop the server.

2. Set `MaxPlayerCount` in `R5/ServerDescription.json` to your target (1 through 8).

3. Save and start.

Reducing the player count does not kick anyone already connected; it just prevents new connections beyond the new limit.

## The PersistentServerId Field

You will see `PersistentServerId` near the bottom of `ServerDescription_Persistent`. **Do not edit this**. It is auto-generated on first boot and links your server to its world data and any registration on Kraken Express's backend services. Changing it can:

- Disconnect your server from its existing world
- Cause player profile or progression issues
- Require support intervention to recover

If you somehow lose the value or it appears blank, restore the most recent backup that has it intact rather than guessing.

## Common Issues

- **Server will not start after editing the config**: Almost always a JSON syntax error. Open the file, scan for missing commas, extra commas after the last entry in an object, or mismatched braces. The panel Console will show the line where parsing failed.
- **Invite code changes do not take effect**: A full restart is required, not just a reload. Stop, wait for "Offline," then start.
- **Players can connect with the old invite code even after rotating**: They are using cached connection info from their game client. Have them close and reopen Windrose.
- **Direct connection works locally but not from outside**: Confirm the port shown in the panel's Network tab matches `DirectConnectionPort` in the config.
- **"PersistentServerId looks wrong or empty"**: Do not edit it manually. Restore from a backup that has the correct value.

## What to Read Next

- [World Settings](/knowledge-base/windrose/world-settings/) for gameplay difficulty and multipliers
- [Managing Worlds](/knowledge-base/windrose/managing-worlds/) for running and switching between multiple worlds
- [Updates and Maintenance](/knowledge-base/windrose/updates-and-maintenance/) for backup workflows that protect this config from accidental corruption

---

Made with 💜 by GameServerKings