Server configuration

Overview

Every Vital.server ships with a config.yaml in its root directory, pre-populated with sensible defaults. It is the single source of truth for runtime behaviour — modify the values, restart the server, and changes take effect immediately.

If the config file is absent or malformed, the server falls back to built-in defaults and emits a diagnostic to the console. A missing file is non-fatal.

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.

Example server layout

Vital.server/
├── config.yaml
└── resources/
    └── ...

Configuration

Default configuration as shipped with every Vital.server.

Vital.server/config.yaml

# =============================================================================
# Vital Sandbox — Server Configuration
# =============================================================================

server:
  name: "Vital.sandbox Server"
  version: "1.0.0"
  description: "A Vital.sandbox server"

network:
  port: 7777
  max_peers: 32
  physics_tick_rate: 60

http:
  port: 7778

sync:
  #rate: 60
  buffer_delay_max: 0.30
  jitter_margin: 1.5
  snap_threshold: 5.0

bootstrap:
  #- "runcode"

social:
  discord: ""
  website: ""

masterlist:
  enabled: false
  token: ""
  url: "https://api.vital-sandbox.com/masterlist"

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.

Server

Controls the display name, version string, and description exposed to clients and integrations.

server:
  name: "Vital.sandbox Server"
  version: "1.0.0"
  description: "A Vital.sandbox server"

Key	Type	Default	Description
`name`	`string`	`"Vital.sandbox Server"`	Display name shown in the master-list
`version`	`string`	`"1.0.0"`	Free-text version identifier — not validated or compared
`description`	`string`	`""`	Optional description shown in the master-list

Network

Controls the ENet multiplayer transport layer and physics simulation rate.

network:
  port: 7777
  max_peers: 32
  physics_tick_rate: 60

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.

Key	Type	Default	Description
`port`	`integer`	`7777`	UDP port the ENet multiplayer server listens on
`max_peers`	`integer`	`32`	Maximum number of concurrent client connections
`physics_tick_rate`	`integer`	`60`	Physics simulation steps per second (1–120). Sets the ceiling for `sync.rate`

HTTP

Controls the asset delivery server. Clients fetch assets such as models and textures from this port at runtime.

http:
  port: 7778

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.

Key	Type	Default	Description
`port`	`integer`	`7778`	Port the HTTP asset delivery server listens on

Sync

Controls entity interpolation behaviour on connected clients. All values are transmitted to clients on connect — no client recompile needed.

sync:
  #rate: 60
  buffer_delay_max: 0.30
  jitter_margin: 1.5
  snap_threshold: 5.0

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.

Key	Type	Default	Description
`rate`	`integer`	tracks `physics_tick_rate`	Entity transform broadcast rate in Hz (1–128). Capped to `physics_tick_rate`
`buffer_delay_max`	`float`	`0.30`	Adaptive jitter buffer ceiling in seconds (0.05–1.0)
`jitter_margin`	`float`	`1.5`	Stddev multiplier for adaptive buffer growth (0.5–5.0)
`snap_threshold`	`float`	`5.0`	Distance in world units beyond which the client teleports instead of interpolating (0.5–100.0)

Bootstrap

Defines resources that are automatically started after the initial resource scan on server boot. Entries are processed in order and respect full dependency resolution.

bootstrap:
  - "runcode"
  - "gamemode"

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.

Value	Type	Description
entry	`string`	Name of a resource folder under `resources/` to start at boot

Defines community links surfaced in the master-list.

social:
  discord: ""
  website: ""

Key	Type	Default	Description
`discord`	`string`	`""`	Discord server invite URL shown in the master-list
`website`	`string`	`""`	Community or project website URL shown in the master-list

Masterlist

Controls whether this server is listed on the public Vital.sandbox master-list.

masterlist:
  enabled: false
  token: "your-token-here"
  url: "https://api.vital-sandbox.com/masterlist"

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).

Key	Type	Default	Description
`enabled`	`boolean`	`false`	When `true`, the server reports itself to the public master-list
`token`	`string`	`""`	API token obtained from a staff member
`url`	`string`	`"https://api.vital-sandbox.com/masterlist"`	Base URL of the master-list API

On this page