Panels and Eggs

Nimbus ships ready-made eggs for game panels in the repo's eggs/ directory. They are exported in the PTDL_v2 format, which Pelican and Pterodactyl both import unchanged, so one file covers both panels.

Three eggs are provided, all installing from the versioned GitHub release (v0.2.0 or newer) and tested end to end in Docker:

Egg	What it runs	Startup done-string
egg-vintage-story-nimbus-backend.json	A Vintage Story dedicated server with Nimbus.ServerMod preinstalled	Dedicated Server now running
egg-nimbus-proxy.json	The Nimbus proxy with its embedded registry	listening on
egg-nimbus-registry.json	The standalone registry, for multi-proxy deployments	registry listening on

Importing

1. Panel admin area, then Nests/Eggs (Pterodactyl) or Eggs (Pelican).
2. Import Egg and upload the JSON file.
3. Create a server from the egg; fill in the variables below.

All three run on the .NET 10 yolk (ghcr.io/parkervcp/yolks:dotnet_10), preselected in the egg.

A minimal network

For a small setup you need one proxy server (players connect here) and one or more backend servers (the worlds). The standalone registry egg is only for multi-proxy networks; skip it otherwise, the proxy hosts an embedded registry.

Every container of the same network must share the same NIMBUS_SHARED_SECRET. Replace the default with a long random string before first boot; the proxy refuses to start on a non-loopback registry bind while the secret is the default.

Backend egg variables

Variable	Default	Meaning
VS_VERSION	1.22.5	Vintage Story server version downloaded at install
NIMBUS_DOWNLOAD_URL	v0.2.0 release zip	Where the ServerMod comes from
NIMBUS_SERVER_ID	backend-1	Unique id of this backend on the network
NIMBUS_REGISTRY_URL	http://127.0.0.1:8765	The registry this backend heartbeats to (see networking below)
NIMBUS_SHARED_SECRET	change it	HMAC secret shared by the whole network
NIMBUS_PUBLIC_HOST	127.0.0.1	Address the network (the proxy) reaches this backend on
NIMBUS_RESERVATION_REQUIRED	true	Kick players who bypass the proxy (recommended)

Proxy egg variables

Variable	Default	Meaning
NIMBUS_DOWNLOAD_URL	v0.2.0 release zip	Release the proxy is installed from
NIMBUS_DEFAULT_BACKEND	127.0.0.1:42421	First [servers] entry; grow the pool in nimbus.proxy.toml
NIMBUS_EMBEDDED_REGISTRY_BIND	http://0.0.0.0:8765	HTTP bind backends heartbeat to
NIMBUS_SHARED_SECRET	change it	Same secret as the backends

Standalone registry egg variables

Variable	Default	Meaning
NIMBUS_DOWNLOAD_URL	v0.2.0 release zip	Release the registry is installed from (shipped in the bundle since v0.2.0)
NIMBUS_SHARED_SECRET	change it	Same secret as proxies and backends

Networking between containers

Backends heartbeat to NIMBUS_REGISTRY_URL, and under Wings every server lives in its own container, so 127.0.0.1 does not reach a sibling container. Two working patterns:

• Via the node's address (default Wings setup): point NIMBUS_REGISTRY_URL at the node's IP and allocate port 8765 to the proxy server in the panel. Without that allocation the embedded registry's port is not exposed outside the proxy container.
• Shared Docker network: if your node runs the servers on a user-defined Docker network, containers reach each other by name and no extra allocation is needed.

The standalone registry egg does not have this concern: its bind uses the panel's own allocated port.

Also note: the install writes the config files once; Wings re-stamps panel-managed values (like the port) on every boot, but changing other egg variables after install requires a reinstall or a manual edit of the written config file.

Panel widgets: the /status endpoint

The proxy exposes a read-only JSON status for panels and dashboards on its metrics host (default http://127.0.0.1:42500/status): configured pool, live registry snapshot (players, health, maintenance), drained backends. Protect it with metrics.status_api_token before exposing the bind beyond localhost, then send Authorization: Bearer <token> (a ?token= query fallback exists for panels that cannot set headers, but headers stay out of access logs).

Prometheus metrics live on the same host at /metrics.

Authoring your own egg

The egg JSONs are generated: the readable install scripts are the install-*.sh files next to them, and generate.py rebuilds the JSONs. If you want to adapt an egg (different mod set, different config layout), edit the script and regenerate rather than editing the JSON by hand. PRs welcome.