Monitoring Panel

The Colyseus Monitoring Panel is a browser-based administration tool for inspecting and managing your multiplayer server in real time. It gives you visibility into active rooms, connected clients, and room state. It also lets you take actions like disposing rooms, disconnecting clients, or broadcasting messages.

Features

List all active rooms
- Force dispose a specific room
Inspect a specific room
- View room’s state
- Send/broadcast messages for a client
- Force disconnect a client

⚠️

The monitoring panel exposes full control over your rooms and clients. Do not expose it in production without password protection. See Password protection below.

Installation

This package is installed by default on new projects created via npm create colyseus-app.

npm install --save @colyseus/monitor

pnpm add @colyseus/monitor

yarn add @colyseus/monitor

bun add @colyseus/monitor

Mounting

The monitor can be mounted in two ways.

Standard router (recommended)

Spread monitor() into createRouter. The monitor is served at /monitor by default. Customize the mount path with the prefix option:

app.config.ts

import { defineServer, createRouter } from "colyseus";
import { monitor } from "@colyseus/monitor";
 
const server = defineServer({
    routes: createRouter({
        ...monitor(), // served at /monitor by default
    })
});

Express middleware

Use this mode if you rely on existing Express middleware or libraries:

app.config.ts

import { defineServer } from "colyseus";
import { monitor } from "@colyseus/monitor";
 
const server = defineServer({
    // ...
    express: (app) => {
        app.use("/monitor", monitor());
    }
});

In express-middleware mode the Express mount path must match the monitor’s prefix (default /monitor). The monitor dispatches on the full original URL, so a mismatched mount path silently 404s. Pass a matching prefix when mounting elsewhere.

Usage

Once mounted, start your server and navigate to http://localhost:2567/monitor in your browser.

If you mounted the monitor at a different path, adjust the URL accordingly.

All active rooms spawned by your server are automatically listed, along with their clients and metadata.

Password protection

The monitoring panel exposes full control over your rooms and clients. Do not expose it in production without password protection. Pass a guard middleware through the monitor’s use option. Colyseus ships with a built-in basicAuth:

app.config.ts

import { defineServer, createRouter, basicAuth } from "colyseus";
import { monitor } from "@colyseus/monitor";
 
const guard = basicAuth({ users: { admin: "s3cret" } });
 
const server = defineServer({
    routes: createRouter({
        ...monitor({ use: [guard] }),
    })
});

The use option works in both mounting modes, so you can pass the same guard when mounting via Express:

app.config.ts

app.use("/monitor", monitor({ use: [guard] }));

See HTTP Routes → Basic authentication for basicAuth options and behavior.

Custom room listing columns

Customize which columns appear in the room list by passing a columns option:

app.config.ts

import { defineServer, createRouter } from "colyseus";
import { monitor } from "@colyseus/monitor";
 
const server = defineServer({
    routes: createRouter({
        ...monitor({
            columns: [
                'roomId',
                'name',
                'clients',
                { metadata: "spectators" }, // display 'spectators' from metadata
                'locked',
                'elapsedTime',
            ],
        }),
    })
});

If unspecified, the default columns are: ['roomId', 'name', 'clients', 'maxClients', 'locked', 'elapsedTime'].

Playground Load Testing