the symptom, in your words

"s&box ships a headless dedicated server that can run an unpublished local project"

✓ verified on 26.07.08e
lane Tooling & environmentposted updated

▸ SYMPTOM

You want to run a dedicated server for your s&box project during development but assume you need to publish the package first, or you're searching for Garry's Mod/Source-1 style server setup (sv_tickrate, workshop.txt, dm_crossfire) that doesn't apply to s&box.

▸ CAUSE

s&box has its own first-class headless dedicated server, a separate Steam app (1892930, distinct from the client 590830). It installs via SteamCMD with anonymous login and runs headless (no GPU/render window). Pointing +game at a local .sbproj path makes connecting clients stream and hotload the project's code and assets straight from the server: the sanctioned dev/iteration workflow, and the only supported way to run server-only code (published sbox.game packages have server code stripped).

Discovery is via Steam lobbies / the multiplayer UI, not a paste-an-IP server browser. The dedicated server surfaces to clients when Networking.QueryLobbies(filters, includeServers:true, ct) is called with includeServers = true (a bool most lobby code leaves false), then Connect(id) joins it.

▸ FIX

Install and launch

snippet
# SteamCMD (anonymous login works)
steamcmd +login anonymous +app_update 1892930 validate +quit

# Launch headless
sbox-server.exe +game "C:/path/to/project.sbproj" +hostname "My Dev Server"

Optional flags: +net_game_server_token <tok>, +port <n>, +net_query_port <n>.

Traps to know

  1. Refresh SteamCMD metadata first: +app_info_update 1 +app_info_print 1892930. Without the refresh, the install may return Missing configuration. After the refresh, it installs normally. Prefer the branch matching your installed client build.

  2. +game <path> loads the project but does NOT activate networking. The game code must call Networking.CreateLobby itself, or it silently runs a headless single-player world. A dedicated process cannot call Networking.QueryLobbies (unable to query lobbies on a dedicated server), so its host path must skip lobby-search flows and create/advertise directly.

  3. Steam drops custom Networking.SetData when aggregate game tags exceed 128 characters: the log reads Steam game tags exceed 128 char limit ... Data dropped. Use tiny discovery metadata (e.g. g=x,p=1,d=1).

  4. Compare .version to clients. An older public build may not recognise +game. Always verify the server and client builds match. Check for updates before reporting issues.

  5. net_game_server_token (persistent server Steam ID) is documented as available "once the game is publicly released", moot for a local/unpublished project; set it once you publish, before announcing a persistent server.

▸ WHY IT WORKS

The dedicated server app is a headless instance of the same engine, running the same game assembly. Pointing it at a local .sbproj means the server has the full unstripped project (including server-only code that sbox.game publish strips), and connecting clients receive the code and assets over the network, no publish/package step needed during development.

Verified on engine 26.07.08e: seen in a real project.
s&box moves fast; an undated fix is a liability. Spot a stale detail?
changelog
  • Removed unverified clause about server token on unpublished projects; aligned to source.

Want to know when new guides or fixes drop? Join the community to help build this out. Report gotchas, flag outdated fixes, or just lurk.

Join the Discord