18-LAB / Documentation

Configuration

Use the dashboard's Settings page or edit vosu.toml. It is flat, typed TOML with uppercase binding names, not a collection of TOML sections.

File locations

<program> means the directory containing vosu.exe. Default static paths ./static and .\static map to the platform data root, not necessarily the shell's working directory. A custom relative static path resolves from the launch directory; an absolute one is used as written.

Complete binding reference

These are all 19 bindings in the configuration schema. Numeric intervals are milliseconds; fractional intervals are supported.

Listener port validation differs from the dashboard: the listener accepts the full integral u16 range, while Settings requires 1–65535. Do not run the daemon as root to bind a privileged port.

Example

ENABLE_AUTOUPDATE = true
OPEN_DASHBOARD_ON_STARTUP = false
START_AT_LOGIN = false
POLL_RATE = 150.0
PRECISE_DATA_POLL_RATE = 10.0
V2_SUBSCRIPTION_DEBOUNCE = 1.0
SERVER_IP = "127.0.0.1"
SERVER_PORT = 24050.0
DASHBOARD_IP = "127.0.0.1"
DASHBOARD_PORT = 24051.0
STATIC_FOLDER_PATH = "./static"
ALLOWED_IPS = "127.0.0.1,localhost,absolute"

Omitted keys take their schema defaults at startup. Unknown keys are ignored. A known key with the wrong TOML type, including a nonfinite numeric TOML value, falls back to that key's default. File intervals below the minimum or above 60000 are clamped with a warning. Dashboard saves reject invalid intervals or ports as a whole without saving part of the update.

Network fields (SERVER_IP, SERVER_PORT, DASHBOARD_IP, DASHBOARD_PORT, ALLOWED_IPS) do not autosave in the dashboard. Choose Apply network settings, then Keep network settings from the new dashboard origin within 30 seconds. Only one change may be pending. The server rolls back only the previous network fields and listeners without confirmation, even if the browser closes; other settings continue autosaving. Keep requires both listeners to match the requested targets. A config-adjacent vosu.network.json journal allows the owning runtime to recover unconfirmed changes after a crash; orderly owner shutdown also rolls them back. File edits remain live-rebindable without this dashboard confirmation workflow.

Reload and migration

vosu watches the configuration's parent directory and applies supported changes without restarting. Writes use atomic same-directory replacement. Malformed TOML during reload leaves the last-good configuration and dependent resources active; malformed canonical TOML at startup leaves all source files untouched.

Startup migration precedence is vosu.toml > vosu.env > tosu.env > defaults. The .env files are legacy migration inputs, not the current configuration format. vosu writes canonical TOML before removing readable legacy files. On Linux, legacy tosu XDG data moves to vosu roots without overwriting existing files.

Environment controls

The TOML binding names above are file keys; do not assume setting POLL_RATE or SERVER_IP in your shell overrides the file. The documented runtime environment controls are separate:

Example for experimental Linux osu!stable through Wine:

VOSU_OSU_PATH=/absolute/path/to/osu\! VOSU_PROCESS_EVENTS=auto vosu

Linux can also read the game path from ${XDG_DATA_HOME:-$HOME/.local/share}/osuconfig/osupath. See Linux setup for permissions and backend behavior.

Listener and remote access

Keep both SERVER_IP and DASHBOARD_IP at "127.0.0.1" unless remote access is deliberate and protected. Sharing overlays does not implicitly expose the independent dashboard. 0.0.0.0 is a wildcard bind, not a security setting; local dashboard discovery maps wildcard binds to loopback. A network client must match an allowed peer IP/CIDR/pattern and, when supplied, an allowed Origin/Referer token. Hostname tokens alone do not authorize arbitrary remote peers.

Use ALLOWED_IPS CIDRs for precise networks: Tailscale is 100.64.0.0/10, not 100.*.*.*, which covers public address space too. IPv6 CIDRs such as fd00::/8 and legacy IPv4 wildcard octets such as 192.168.*.* are supported. Dashboard allowlist entries appear one per line, with warnings for public-space ranges and broad wildcards.

Management mutations live on the dashboard origin (default http://127.0.0.1:24051) and require trusted peers, exact dashboard-origin provenance, and the per-start X-Vosu-CSRF token injected only into dashboard pages. Installed overlays stay on http://127.0.0.1:24050 and cannot use their origin to authorize management writes (403). Explicit scoped API-key and loopback native broker value/profile grants and the existing command-socket settings protocol remain on the overlay origin. Forwarded headers do not authorize HTTPS reverse-proxy writes.

See privacy and security, developer security, and troubleshooting. Release installation and update choices are covered in install and updates.

Sources: schema, parsing and validation, migration, and configuration README.

Edit this page on GitHub