Configuration

Configuration Reference

Nimbus.Proxy reads nimbus.proxy.toml from the same directory as the executable. If the file is missing it is written with defaults on startup.

Hot reload

Most sections reload at runtime without restarting:

nimctl reload

or from a backend server:

/nimbus reload

Reloadable at runtime	Requires restart
[servers], try, [transfers], [logging], [status], [plugins], [advanced]	bind, [admin], [registry], [metrics], [persistence]

---

Top-level

bind = "0.0.0.0:42420"

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

try = ["hub", "survival"]

proxy_protocol_servers = []

Key	Default	Description
bind	0.0.0.0:42420	TCP and UDP address players connect to.
[servers]	-	Named backend map. Key = server ID used everywhere. Value = "host:port".
try	[]	Ordered list of server IDs to attempt on initial connect. First healthy one wins. Empty means all servers in definition order.
proxy_protocol_servers	[]	Server IDs that receive a PROXY Protocol v2 header before the first upstream byte. The backend must support PROXY v2 to use this. See Forwarding.

---

[transfers]

Do not edit these, only redirect is currently supported

[transfers]
default_mode = "redirect"
allow_seamless = false
require_seamless_capability = true
fallback_to_redirect_when_seamless_unavailable = true
enable_unsafe_seamless_splice = false

Key	Default	Description
default_mode	redirect	Default transfer mode when not specified. redirect or seamless.
allow_seamless	false	Master switch for seamless transfers. Must be true to use the visual seamless path.
require_seamless_capability	true	When true, seamless is only used for sessions where the player has Nimbus.Client installed.
fallback_to_redirect_when_seamless_unavailable	true	When seamless is requested but the client lacks the mod, fall back to redirect instead of failing.
enable_unsafe_seamless_splice	false	Enables raw TCP upstream splice. Experimental - has caused atlas and tessellation crashes in VS. Do not enable on production servers.

---

[admin]

[admin]
bind = "127.0.0.1:42499"
secret = ""
enabled = true
granted_permissions = ["*"]

Key	Default	Description
bind	127.0.0.1:42499	Address the admin socket listens on. Keep on localhost unless you have an authenticated reverse proxy in front.
secret	""	Optional shared secret. If non-empty, the admin client must provide it. Empty means no auth (rely on the localhost binding).
enabled	true	Set false to disable the admin socket entirely.
granted_permissions	["*"]	Permission nodes granted after auth. "*" grants all commands.

---

[registry]

[registry]
mode = "embedded"
proxy_id = "nimbus-proxy"

# embedded mode
embedded_bind = "http://0.0.0.0:8765"
embedded_shared_secret = "change-me-and-keep-secret"

# remote mode
url = ""
shared_secret = ""

# tuning (applies to both modes)
backend_stale_seconds = 20
backend_drop_seconds = 120
max_reservation_ttl_seconds = 300
fail_on_registry_error = true
transfer_intent_poll_ms = 1000

Key	Default	Description
mode	embedded	embedded - registry runs in-process. remote - connect to a standalone Nimbus.Registry. disabled - no registry; single-backend setups only.
proxy_id	nimbus-proxy	Identifier for this proxy instance, used in transfer intent routing.
embedded_bind	http://0.0.0.0:8765	Kestrel bind URL for the embedded registry HTTP API. Set to "" to disable the HTTP listener entirely - backends on the same host can reach the registry in-process; external backends have nowhere to heartbeat.
embedded_shared_secret	change-me-and-keep-secret	HMAC secret. Must match SharedSecret in every backend's nimbus-server.json. Change this before running in production.
url	-	Remote registry URL. Only used when mode = "remote".
shared_secret	-	HMAC secret for remote registry.
fail_on_registry_error	true	When true, a reservation mint failure aborts the transfer rather than proceeding without one.
transfer_intent_poll_ms	1000	How often the proxy polls the registry for pending transfer intents.

Three registry modes

embedded (default) - the proxy hosts the registry in-process. No extra process to run. External backends heartbeat over HTTP to embedded_bind. The proxy itself talks to the registry directly (no HTTP round-trip, no HMAC overhead).

remote - the proxy connects to a standalone Nimbus.Registry process. Use this when running multiple proxy instances that need to share state, or when you want the control plane on a separate host.

disabled - no registry. Transfers, reservations, and forwarding are unavailable. Only makes sense for single-backend setups.

---

[logging]

[logging]
verbose = false
sniff_frames = false

Key	Default	Description
verbose	false	Enables debug output (pump exits, frame sniffer detail, internal state transitions). Very noisy - for troubleshooting only.
sniff_frames	false	Logs every VS frame header passing through the sniffer. Only has output when verbose = true.

---

[metrics]

[metrics]
enabled = true
bind = "http://127.0.0.1:42500"
path = "/metrics"

Exposes a Prometheus text endpoint. Counters include: sessions accepted/closed, backend connect attempts/successes/failures, redirect and seamless counts, bytes proxied, transfer intents dispatched, drained backends.

---

[status]

[status]
enabled = true
name = "Nimbus"
motd = "Vintage Story proxy"
game_mode = "survival"
password = false
server_version = ""
max_players = 100
query_timeout_ms = 1500

Controls what players see when their VS client sends a server-list ping to the proxy address. When the registry is running, live player counts come from the backend snapshot. server_version left empty means Nimbus forwards the version reported by the first backend to respond.

---

[plugins]

[plugins]
enabled = true
directory = "plugins"
disabled = []

Key	Default	Description
enabled	true	Set false to skip all plugin loading.
directory	plugins	Path to the plugins folder. Relative paths resolve from the executable directory.
disabled	[]	Plugin IDs to skip on load. Useful for temporarily disabling one plugin without removing it.

---

[persistence]

[persistence]
persist_drain_flags = true
drain_flags_file = "nimbus.drain-state.json"

Drain flags (which backends are out of rotation) survive a proxy restart when persist_drain_flags = true. The state file is written next to the executable by default.

---

[advanced]

[advanced]
connect_timeout_ms = 5000
buffer_size = 16384

Key	Default	Description
connect_timeout_ms	5000	Milliseconds before an upstream TCP connect attempt is abandoned and the next failover candidate is tried.
buffer_size	16384	Per-pump byte buffer size. Changing this rarely helps.