Skip to content

Getting Started

Jump to bottom
Tsu edited this page Jun 10, 2026 · 2 revisions

Prerequisites

  • .NET 10 runtime (or SDK if building from source)
  • One or more Vintage Story dedicated servers you control
  • Nimbus.ServerMod installed on each backend server (see Server Mod)
  • RedirectFix mod installed on server so clients will be required to install (required for redirect transfers until next Vintagestory Update!)

Download

Download it here:

OR

Build from source:

bash
git clone https://github.com/your-org/nimbus
cd nimbus
dotnet build -c Release

First run

./Nimbus.Proxy.exe On first run Nimbus writes nimbus.proxy.toml with defaults and exits. Edit it before running again.

Minimal configuration Open nimbus.proxy.toml. At minimum set your backends:

bind = "127.0.0.1:42420"

[servers]
hub     = "127.0.0.1:42421" 
factions = "127.0.0.1:42422"

try = ["hub"]
  • bind - the address players connect to. This replaces your individual server addresses publicly.
  • [servers] - named backends. Keys are the server IDs used everywhere in the system.
  • try - ordered list of backends to attempt on initial connect. First healthy one wins.

Run again:

./Nimbus.Proxy.exe

You should see:

HH:mm:ss [nimbus] Nimbus 0.1.0 starting
HH:mm:ss [nimbus] registry: disabled
HH:mm:ss [nimbus] backends: hub, factions
HH:mm:ss [nimbus] listening on 127.0.0.1:42420 -> pool of 2 backend(s)

Players now connect to port 42420 and are routed to hub. Each backend should have Server Mod installed and configured.

Enabling the registry For transfers between backends and real-IP forwarding you need the registry. The simplest setup is embedded mode - the registry runs inside the proxy process:

[registry]
mode = "embedded"
embedded_shared_secret = "change-this-to-something-secret"

Set the same secret in each backend's ModConfig/nimbus-server.json under SharedSecret.

The embedded_bind setting controls whether external backends can reach the registry over HTTP. If all your backends are on the same machine, leave embedded_bind = "" to keep it purely in-process and skip the HTTP listener entirely. If you wish to use it, it would look as follows, and in each backend's config you'd set RegistryUrl to the embedded_bind.

Example of ModConfig/nimbus-server.json

{
  "Enabled": true,
  "ServerId": "vanilla1",
  "DisplayName": "Vanilla Server 1",
  "PublicHost": "127.0.0.1",
  "PublicPort": 42421,
  "Tags": [],
  "RegistryUrl": "http://127.0.0.1:8765",
  "SharedSecret": "change-this-to-something-secret",
  "HeartbeatIntervalSeconds": 5,
  "RegistryHttpTimeoutSeconds": 5,
  "Maintenance": false,
  "ReservationRequired": true,
  "AllowPlayerServerCommand": true,
  "TransferMode": "redirect",
  "SeamlessPrepareAckTimeoutSeconds": 8
}

Example of registry section of nimbus.proxy.toml

[registry]
mode = "embedded"
proxy_id = "nimbus-proxy"
reservation_ttl_seconds = 60
fail_on_error = true
transfer_intent_poll_ms = 1000
url = ""
shared_secret = ""
http_timeout_seconds = 5
embedded_bind = "http://127.0.0.1:8765"
embedded_shared_secret = "change-this-to-something-secret"
backend_stale_seconds = 20
backend_drop_seconds = 120
nonce_window_seconds = 90
max_reservation_ttl_seconds = 300
advertise_on_master_server = false

Pointing players to Nimbus Change your public server address (in game listings, your community, etc.) to the address Nimbus binds on. The individual backend servers should not be publicly advertised, players always connect through the proxy.

Next steps Configuration - every config knob explained Server Mod - set up Nimbus.ServerMod on backends Transfers - how to move players between servers

Clone this wiki locally