Admin Panel

@colyseus/admin is a browser-based operations console for projects using @colyseus/database. The panel provides user management (browse, ban, revoke sessions), CRUD over your drizzle tables, a live room inspector, and a customizable dashboard. Everything is gated by session-based login with role-based access control and an append-only audit log.

For a lightweight, no-auth dashboard intended for room and process inspection, see the Monitoring Panel instead. The admin panel is the heavier counterpart, built for production operations.

Installation

On top of @colyseus/core, the panel has two peer dependencies: @colyseus/database (user store, audit log, drizzle table introspection) and @colyseus/auth (JWT signing, password hashing). Install all three together:

npm install --save @colyseus/admin @colyseus/database @colyseus/auth

pnpm add @colyseus/admin @colyseus/database @colyseus/auth

yarn add @colyseus/admin @colyseus/database @colyseus/auth

bun add @colyseus/admin @colyseus/database @colyseus/auth

Mounting

The admin panel mounts in two ways:

import { defineServer, createRouter } from "colyseus";
import { GameDatabase } from "@colyseus/database";
import { admin } from "@colyseus/admin";
 
export const db = new GameDatabase({ connectionString: process.env.DATABASE_URL });
 
export default defineServer({
    database: db,
    routes: createRouter({
        ...admin({}),
    }),
});

import { defineServer } from "colyseus";
import { GameDatabase } from "@colyseus/database";
import { admin } from "@colyseus/admin";
 
export const db = new GameDatabase({ connectionString: process.env.DATABASE_URL });
 
export default defineServer({
    database: db,
    express: (app) => {
        app.use(admin({}));          // UI at /admin/, API at /admin-api
 
        // or, under a path: UI at /ops/, API at /ops/admin-api
        // app.use("/ops", admin({}));
    },
});

Usage

Once mounted, start your server and open http://localhost:2567/admin/ in your browser (the bare /admin redirects to the trailing slash). If you customized uiPath, adjust the URL accordingly.

The REST API mounts in parallel at http://localhost:2567/admin-api and is consumed by the SPA. Every endpoint enforces the same session and role rules as the UI, so you can script the panel with curl or fetch using the session cookie. The sub-pages list the endpoints for each area. GET /admin-api/_health is the one unauthenticated route: it answers 200 { ok, db, latencyMs } or 503 when the database is unreachable, for readiness probes.

First-run bootstrap

The admin panel includes no built-in admin user. The SPA calls GET /admin-api/auth/status on load; while no user has the admin role it reports needsBootstrap: true and the panel renders a one-time setup form.

Submitting the form calls POST /admin-api/auth/bootstrap with { email, password }. If a user with that email already exists (for example, you registered through your game first), that account is promoted instead of created. After bootstrap:

• A session cookie is set (HttpOnly, SameSite=Strict, JWT-signed).
• You’re redirected into the panel with full admin role access.
• All sibling routes gated with admin.guard() (e.g. the Playground or Monitor) now resolve against the same session.
• The endpoint refuses further calls with 403 as soon as one admin exists.

Hardening for production

The defaults are tuned for local development. Before exposing the panel to the public internet:

• Set a strong JWT_SECRET and SESSION_SECRET: see Auth Module → Required Environment Secrets. With NODE_ENV=production, admin() throws at startup when no JWT secret is configured; outside production it only warns. Rotating JWT_SECRET invalidates all admin sessions (SESSION_SECRET only signs OAuth state cookies).

• Keep player accounts out of the panel. POST /admin-api/auth/login accepts any user row with a password. The user role then passes the list/read gate on every resource and on the room inspector. A player with an email and password can therefore read live room state and other players’ emails through the API. Until the package closes this, serve the panel on a separate hostname or behind your own network guard. Keeping admin accounts in a dedicated database also works. See Authentication → Roles.

• Wire auth.settings.onForgotPassword so password reset links reach your admins. The panel ships no reset page yet; see Password reset for the API flow.

• Tighten the session cookie via the session option: set an explicit cookieDomain, an appropriate ttlSeconds, and confirm the cookieSecure/cookieSameSite values match your deployment.

• Disable allowDevHeader if you don’t need it. It auto-disables when NODE_ENV === "production", but setting it to false explicitly avoids surprises in mixed environments.

• Swap the in-memory rate limiters for a Redis-backed implementation on multi-process deployments. The default token buckets don’t share state across instances. The limiter keys on X-Forwarded-For / X-Real-IP when present, so only expose the panel behind a proxy that overwrites those headers.

• Gate the Monitor and Playground behind admin.guard() so you don’t have multiple unauthenticated panels exposed:

  src/app.config.ts

  routes: createRouter({
      ...playground({ use: [admin.guard()] }),
      ...monitor({    use: [admin.guard()] }),
      ...admin({}),
  }),

Options reference

admin(options) accepts the following AdminOptions:

Session defaults

The session config controls the JWT cookie. Defaults:

session: {
    ttlSeconds: 7 * 24 * 60 * 60, // 1 week
    cookieSameSite: "Strict",
    cookieSecure: process.env.NODE_ENV === "production",
    // cookieDomain: undefined  ← host-only; set explicitly when serving from a subdomain
}

The cookie is always HttpOnly, scoped to Path=/, and signed with JWT_SECRET. Revoking a session is done via db.auth.bumpTokenVersion(userId). See Database → Authentication.

Next steps

• Authentication & RBAC: sessions, roles, password reset, and admin.guard().
• Resources & CRUD: exposing custom tables, customizing columns and forms, custom actions, the audit log.
• Dashboard & widgets: configuring presets and appending custom widgets to the homepage.
• Live rooms: the built-in room inspector.