Server configuration

Where the config lives

• Fixed location — config.yaml must sit at the root of your Vital.server/ directory.
• Single file — all sections (server, network, http, sync, bootstrap, social, masterlist) live in this one file.
• Restart to apply — changes are not hot-reloaded; a server restart is required for any edit to take effect.

All keys are optional.

• Every key has a built-in default and can be omitted without error.
• An absent or malformed config.yaml is non-fatal — the server starts with defaults and logs a warning.

Tags are picked from a fixed list.

• Up to 5 tags — extras are dropped.
• Valid values only — choose from the list in the table below; anything else is ignored and the server logs a warning on its next master-list heartbeat.
• Used for filtering — players filter the in-game server browser by these tags, so pick the ones that describe your server best.

port and max_peers directly affect client connectivity — change them with care.

• port — clients and any firewall or port-forwarding rules must be updated to match.
• max_peers — once the limit is reached, incoming connections are refused until a slot becomes available.

Join rate limit protects against reconnect spam.

• Counted per IP — at most auth_rate_max connections from the same address may authenticate within auth_rate_window seconds; extra attempts are rejected.
• Why it exists — every successful join makes the server send the full world state, so rapid reconnects would otherwise be expensive.
• Shared addresses — raise auth_rate_max if many players join from one IP (LAN parties, NAT, cafés).
• Window length — a short auth_rate_window is forgiving, a long one is stricter.
• Disabling — set auth_rate_max: 0 to turn the limit off; auth_rate_window is then ignored.

The HTTP server operates independently of the ENet transport layer.

• Both ports must be reachable — blocking either one will result in a failed or degraded session.
• Separate firewall rules — ensure both ports are open and forwarded correctly in your network configuration.

Tuning sync for your server type.

• LAN / relay-only — buffer_delay_max: 0.10, jitter_margin: 1.0 for the tightest possible latency.
• Mixed or global — leave defaults (0.30 / 1.5), which handle typical internet jitter comfortably.
• Lossy / satellite links — raise buffer_delay_max to 0.50+ and jitter_margin to 2.0–3.0.
• Large open worlds — raise snap_threshold so fast-moving entities don't teleport on authority transfer.

Bootstrap runs once at startup, after the resource scan completes.

• Order is preserved — resources start top-to-bottom as listed.
• Dependencies are resolved automatically — a resource's deps start before it, even if not listed here.
• Each entry must be a valid resource name — must match a folder under resources/ (a-z, 0-9, _ only).
• Already-running resources are skipped — no error is raised if a resource is already running.

Treat token like an API key.

• Do not commit a real token to a public repository — anyone with it can impersonate your server on the master-list.
• Contact a staff member on our Discord to obtain a token.
• Set enabled: false to keep your server off the public listing entirely (e.g. private or LAN servers).