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.
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.
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
.envfile or other secret (file permissions block it โ this also surfaced that the production.envfiles were world-readable before this work, a real pre-existing hole, now fixed to600) - 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; productioncrossworldsis 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.
mysqlis 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 wordRESTARTtyped 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=trueon the dashboard's own systemd unit silently broke every Start/Stop/Restart button (not staging-specific) โ that flag blockssudofrom escalating for anything the unit's process spawns. Removed fromcrossworlds-dashboard.serviceonly; left in place on every unit that doesn't itself need to invokesudo.- Uptime Kuma's "Auth Server" monitor was checking the wrong port (
:5000, which isrod-realtime, not the auth server) โ fixed to:3000/api/health. Had likely been "healthy" against the wrong service the whole time. /game/serveris owned by a different user (bogar, a dev account with its own sudo) โubuntuhad zero write access. The dashboard runs asubuntu; build uploads need write access. Fixed by addingubuntuto thebogargroup +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/72526before that) that happened to read as a date (7-26-26). Renamed to the stable/game/serveron 2026-07-30 โ updated thecrossworlds-server.serviceunit'sWorkingDirectory/ExecStartand the dashboard'sGAME_DIR/GAME_BINARYconstants to match. The CI pipeline'sdeploy-server.shself-detects its target from the unit'sExecStartrather 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/gamefailed withEXDEVโ the dashboard'sPrivateTmp=trueputs its/tmpin a separate mount namespace from/game, even though both are on the same physical disk. Fixed by putting the upload temp dir under/gameitself.- 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
:7777alongside the live production server without erroring (ss -ulnpshowed 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