dev/docs/00 INBOX/ai/steamcmd servers.md

SteamCMD servers

Use modules.services.steamcmd as the low-level runner for one SteamCMD server. Create a game module under configs/nixos/modules/services/games/ for each game.

The game module owns game-specific defaults and command-line flags. The host owns deployment-specific paths, names, secrets, and network placement.

Create a game module

1. Create configs/nixos/modules/services/games/<game>.nix.
2. Define options under modules.services.games.<game>.
3. Expose only values the host must choose.
4. Map those values to modules.services.steamcmd.
5. Set the Steam dedicated-server app ID in the game module.
6. Set the server executable in the game module.
7. Generate game-specific arguments in the game module.
8. Open the game's documented UDP ports in the game module.

Keep modules.services.steamcmd focused on shared SteamCMD behavior. Do not put game-specific flags or port rules there.

Configure a host

During validation, enable the game module directly on a host.

modules.services.games.valheim = {
  enable = true;
  steamDir = "/pikachu/data/steamcmd";
  installDir = "/pikachu/data/servers/valheim/main";
  stateDir = "/pikachu/media/games/servers/valheim/main";
  serverName = "main";
  password = "foobarbaz";
};

Use host paths for direct host deployment. Use guest paths after the server moves into a guest.

Deploy and test

1. Evaluate the host configuration.

   nix eval .#nixosConfigurations.<host>.config.system.build.toplevel.drvPath --raw
   

2. Deploy the host.

   deploy-to <host>
   

3. Check the game service.

   sudo systemctl status <game>.service
   sudo journalctl -u <game>.service -n 200 --no-pager
   

4. Check UDP listeners.

   sudo ss -lunp | grep -E '<port>|<port-plus-one>|<game>'
   

5. Connect from the game client.

The Valheim server is ready after the log contains Game server connected. It can spend time generating a new world before it accepts connections.