Admin Dashboard

The team's GUI for running the game server day-to-day โ€” services, logs, deploys, player/GM tools, helpdesk, and an approval-gated AI ops agent โ€” so the team can operate without SSH keys or shell access. Lives at /opt/crossworlds-dashboard, service crossworlds-dashboard.

Access

https://playcrossworlds.com:4000 โ€” nginx terminates TLS here (reusing the playcrossworlds.com cert) and proxies to the actual Node app, which listens on 127.0.0.1:4001 only (not directly internet-reachable). Session-cookie login, not HTTP Basic Auth.

โ„น๏ธ Multi-user accounts (2026-07-29)

Login is backed by a dashboard_users table in the crossworlds DB (username, password_hash bcrypt, is_owner, active, last_login) โ€” no longer a single shared password. Every account gets full access to Services, Live Logs, Stats, Player Accounts, Management, Deploy, Game Stats, GM Commands/Permissions, Enchants, Characters, Server Controls, and Tickets. The Agent Console and Agent Audit Log tabs are owner-only (is_owner=1) โ€” enforced server-side (403 on /api/agent/* for non-owners, verified directly) and hidden client-side via GET /api/me. Team accounts are currently created directly in the DB (no self-service account management UI yet).

Five failed login attempts from one IP locks that IP out for 15 minutes.

Deploy tab

Shows the live game binary path/mtime (/game/server/CrossWords.x86_64 โ€” see Canonical Facts & Doc Divergences for the naming history) and a Restart button.

โ„น๏ธ Browser build upload (2026-07-29)

You can now upload a build directly instead of scp: zip the build folder (binary + _Data/) and use Upload Build โ€” it extracts into /game/server and auto-chmods the binary. A separate Misc / Build Files section takes patch notes, configs, or single assets that aren't the main binary, landing in /game/misc with a download list. Both need the dashboard's ubuntu user to have write access to /game/server, which it didn't by default โ€” see the Gotchas section below. See Build & Deploy for the full pipeline including this new path.

Agent Console โ€” read-only diagnostics + approval-gated actions

An AI ops agent (Claude Code, headless) a logged-in owner can chat with to diagnose problems and, with explicit approval, fix some of them. Built in three phases; the internal design doc lives at /opt/crossworlds-dashboard/crossworlds-agent-dashboard.md with full technical detail โ€” this section is the summary.

The core safety property, worth understanding before using it: the agent runs under a dedicated, deliberately locked-down OS account (claude-agent) โ€” not ubuntu, not the account this dashboard or any other service runs as. That account:

  • Has read-only sudo (systemctl status *, journalctl * only) โ€” restart attempts fail (verified: sudo: a password is required)
  • Cannot read any .env file or other secret (file permissions block it โ€” this also surfaced that the production .env files were world-readable before this work, a real pre-existing hole, now fixed to 600)
  • Cannot write outside its own home directory
  • Can only reach a staging database (crossworlds_staging, cloned schema, seeded with fake test accounts โ€” never real player data) โ€” SELECT-only for its own queries; production crossworlds is completely unreachable to it

Phase 1 (read-only): ask it about service health, recent errors, staging DB state. It answers immediately, no approval needed, because every capability available to it is already incapable of changing anything.

Phase 2 (approval-gated actions): it can also propose โ€” never execute โ€” a service restart or a staging-DB write (INSERT/UPDATE/DELETE only, no DDL). Proposals render as a card with Approve/Deny. Critically, approval never grants the agent execution power โ€” clicking Approve runs the action through the dashboard's own already-existing code (the same function behind the Services tab's Restart button, or a dedicated staging-only DB credential the agent's own session never holds). The LLM's session physically cannot execute a restart or a write, approved or not.

  • mysql is excluded from restartable services entirely (too big a blast radius, rarely the actual fix)
  • Restarting a production service (crossworlds-auth, crossworlds-server, crossworlds-dashboard) needs the literal word RESTART typed to confirm, checked server-side, not just in the UI
  • Every proposal is independently re-validated at approval time, not just when first proposed

Phase 3 (review): a separate Agent Audit Log tab (also owner-only) โ€” filterable by status/admin/ search, with summary counts and a detail view for every message, proposal, approval, denial, and execution ever made. The doc is explicit that Phase 3 itself isn't a build task โ€” it's "run this for a while and watch the audit log" before deciding whether to widen access or allow production restarts at all; the audit tab just makes that review possible.

**Built since (2026-08-02): a staging clone of the game server.** The Gotchas section below found that a second copy of the prod binary reusing :7777 was unsafe (double UDP bind, no error). The actual staging game server sidesteps that entirely by using a different port โ€” crossworlds-server-staging launches the same binary with -port 7778 -authurl http://127.0.0.1:3010, into /game-staging, fully separate from prod's /game/server. It's no longer Agent-Console-only either: the client's real Prod/Dev login toggle points at this same stack. See Build & Deploy and Login & Authentication Flow.

A general "upload/download files via the agent" capability was explicitly not built โ€” that's a different, much larger trust boundary (this session's own access looks like unrestricted VPS access; the Agent Console deliberately never will) and file transfer needs are served by SFTP instead (existing SSH key, no new service).

Gotchas found building this (2026-07-28 โ†’ 2026-07-29)

  • NoNewPrivileges=true on the dashboard's own systemd unit silently broke every Start/Stop/Restart button (not staging-specific) โ€” that flag blocks sudo from escalating for anything the unit's process spawns. Removed from crossworlds-dashboard.service only; left in place on every unit that doesn't itself need to invoke sudo.
  • Uptime Kuma's "Auth Server" monitor was checking the wrong port (:5000, which is rod-realtime, not the auth server) โ€” fixed to :3000/api/health. Had likely been "healthy" against the wrong service the whole time.
  • /game/server is owned by a different user (bogar, a dev account with its own sudo) โ€” ubuntu had zero write access. The dashboard runs as ubuntu; build uploads need write access. Fixed by adding ubuntu to the bogar group + chmod g+w + setgid on the directory, rather than changing ownership.
  • The game server's install dir used to be a numbered, drifting directory (/game/72626, and /game/72526 before that) that happened to read as a date (7-26-26). Renamed to the stable /game/server on 2026-07-30 โ€” updated the crossworlds-server.service unit's WorkingDirectory/ ExecStart and the dashboard's GAME_DIR/GAME_BINARY constants to match. The CI pipeline's deploy-server.sh self-detects its target from the unit's ExecStart rather than hardcoding a path, so this shouldn't need any changes on that side โ€” confirm this holds on the next CI deploy.
  • fs.rename() across the upload temp dir and /game failed with EXDEV โ€” the dashboard's PrivateTmp=true puts its /tmp in a separate mount namespace from /game, even though both are on the same physical disk. Fixed by putting the upload temp dir under /game itself.
  • Copying the game server binary and running a second instance on the same box is not just blocked, it's actively unsafe โ€” tested directly: the Unity/KCP transport bound UDP :7777 alongside the live production server without erroring (ss -ulnp showed both PIDs on the port simultaneously). Two UDP sockets sharing a port don't cleanly load-balance; real player packets could get silently misrouted to a test instance. This is a sharper version of the existing "orphaned processes squatting on :7777" warning in Known Issues & Tech Debt โ€” a second instance needs a genuinely separate host, a config change alone won't do it.
  • The Deploy tab had been silently checking a binary path (/game/Builds/CrossworldsBCE.x86_64) that has never existed on this box โ€” see Canonical Facts & Doc Divergences for the real path history.

Related: Build & Deploy ยท Known Issues & Tech Debt ยท Canonical Facts & Doc Divergences ยท GM Console & Tools