Home

Nimbus is a proxy for Vintage Story that routes players across multiple backend game servers without requiring a custom server fork. It is conceptually modelled on Velocity for Minecraft.

The current release is v0.5.0, built and tested against Vintage Story 1.22.6. These pages describe that release.

What it does

• Accepts player connections on a single public address and routes them to one of many backend VS servers
• Transfers players between backends at runtime via redirect.
• Provides a plugin system, event bus, typed API, hot-reloadable plugins
• Hosts an embedded registry that tracks backend health, player counts, and routes transfer intents from backends to the proxy
• Forwards trusted player identity (real IP, UID) to backends via HMAC-signed reservations, no custom server required!
• Holds network-wide bans and whitelists in the registry, kept across a restart, and mints scoped API tokens so a bot can drive them without holding the network secret

Components

Component	What it is
Nimbus.Proxy	The edge process. Accepts TCP/UDP, routes sessions, hosts plugins, runs the admin socket.
Nimbus.Registry.Core	Registry library, backend tracking, reservations, transfer intents. Used in-process by Nimbus.Proxy or as a standalone service.
Nimbus.Registry	Thin standalone wrapper around the library. Use for multi-proxy or dedicated control-plane deployments.
Nimbus.ServerMod	Server-side VS mod. Sends heartbeats, posts transfer intents, tracks client capability, handles forwarding. Required on every backend.

Pages

• Getting Started - install, first run, basic configuration
• Configuration - full proxy TOML reference
• Server Mod - setting up Nimbus.ServerMod on each backend
• Transfers - redirects and how player moves work
• Forwarding - trusted player identity, real IP, reservation system
• Plugin Development - writing Nimbus plugins
• Plugin Examples - ready-to-use example plugins
• Panels and Eggs - deploying on Pelican/Pterodactyl with the ready-made eggs