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

@colyseus/admin 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({}));
    },
});

Usage

Once mounted, start your server and navigate to http://localhost:2567/admin in your browser. 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. The endpoints are normal createEndpoint(...) routes and respect the same admin.guard() semantics if you wrap them for use elsewhere.

First-run bootstrap

The admin panel includes no built-in admin user. The first visit to /admin checks for an existing admin account and, if none exists, renders a one-time bootstrap form.

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.

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. Rotating JWT_SECRET invalidates all admin sessions (SESSION_SECRET only signs OAuth state cookies).

• Wire auth.settings.onForgotPassword to deliver password reset emails through your transactional email provider, the same hook that powers your player-side reset flow.

• Tighten the session cookie via the session option: set an explicit domain, an appropriate maxAge, and confirm the Secure/SameSite flags 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.

• 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 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.