Socket.IO Admin UI

dashboard screenshot

How to use


First, install the package:

npm i

And then invoke the instrument method on your Socket.IO server:

const { createServer } = require("http");
const { Server } = require("");
const { instrument } = require("");

const httpServer = createServer();

const io = new Server(httpServer, {
  cors: {
    origin: [""],
    credentials: true

instrument(io, {
  auth: false


The module is compatible with:

  • Socket.IO v4 server
  • Socket.IO v3 server (>= 3.1.0), but without the operations on rooms (join, leave, disconnection)


You can then head up to, or host the files found in the ui/dist folder.

Important note: the website at is totally static (hosted on Vercel), we do not (and will never) store any information about yourself or your browser (no tracking, no analytics, …). That being said, hosting the files yourself is totally fine.

You should see the following modal:

login modal screenshot

Please enter the URL of your server, including the namespace (for example, http://localhost:3000/admin or and the credentials, if applicable (see the auth option below).

Available options


Default value: -

This option is mandatory. You can either disable authentication (please use with caution):

instrument(io, {
  auth: false

Or use basic authentication:

instrument(io, {
  auth: {
    type: "basic",
    username: "admin",
    password: "$2b$10$heqvAkYMez.Va6Et2uXInOnkCT6/uQj1brkrbyG3LpopDklcq7ZOS" // "changeit" encrypted with bcrypt

WARNING! Please note that the bcrypt package does not currently support hashes starting with the $2y$ prefix, which is used by some BCrypt implementations (for example or You can check the validity of the hash with:

$ node
> require("bcrypt").compareSync("<the password>", "<the hash>")

You can generate a valid hash with:

$ node
> require("bcrypt").hashSync("changeit", 10)

See also:


Default value: /admin

The name of the namespace which will be created to handle the administrative tasks.

instrument(io, {
  namespaceName: "/custom"

This namespace is a classic Socket.IO namespace, you can access it with:

const adminNamespace = io.of("/admin");

More information here.


Default value: false

Whether to put the admin UI in read-only mode (no join, leave or disconnect allowed).

instrument(io, {
  readonly: true


Default value: require("os").hostname()

The ID of the given server. If you have several Socket.IO servers on the same machine, please give them a distinct ID:

instrument(io, {
  serverId: `${require("os").hostname()}#${}`


Default value: new InMemoryStore()

The store is used to store the session IDs so the user do not have to retype the credentials upon reconnection.

If you use basic authentication in a multi-server setup, you should provide a custom store:

const { instrument, RedisStore } = require("");

instrument(io, {
  store: new RedisStore(redisClient)

How it works

You can check the details of the implementation in the lib/index.ts file.

The instrument method simply:

  • creates a namespace and adds an authentication middleware if applicable
  • register listeners for the connection and disconnect event for each existing namespaces to track socket instances
  • register a timer which will periodically send stats from the server to the UI
  • register handlers for the join, leave and _disconnect commands sent from the UI




View Github