# Add the Admin UI to a Socket.IO Server

Yes. An agent instruments a Socket.IO server with @socket.io/admin-ui behind basic auth from environment variables, checks it in a browser, tests it and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-admin-ui/socket-io/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads how the server is built before adding instrumentation, because the admin UI attaches to the `Server` instance and inherits its adapter and CORS settings. In an app laid out like socketio/chat-example, `package.json` is an ES module with `socket.io` `^4.7.2`, `express` `^4.18.2`, `@socket.io/cluster-adapter` `^0.2.2`, `sqlite` `^5.0.1` and `sqlite3` `^5.1.6`, and one script, `start`, that runs `node index.js`. `index.js` forks one worker per CPU with `node:cluster`, each given `PORT` from `3000` upward, and calls `setupPrimary()` in the primary. Each worker opens `chat.db`, creates a `messages` table with `id`, a unique `client_offset` and `content`, serves `index.html` at `/` through Express, and creates `new Server(server, { connectionStateRecovery: {}, adapter: createAdapter() })`. The `chat message` handler inserts the row, treats a `SQLITE_CONSTRAINT` error as a duplicate and acknowledges, and `io.emit`s the message with its id; a client that was not recovered gets rows past its `serverOffset` replayed. There is no `cors` option on the server, no `.github` directory and no test.

The package is `@socket.io/admin-ui`, whose current release lists `socket.io` at or above `3.1.0` as a peer and depends on `bcryptjs`. Its `instrument(io, options)` call creates an `/admin` namespace the hosted dashboard at `https://admin.socket.io` connects to, and `auth` is mandatory: either `false`, or `{ type: 'basic', username, password }` where `password` is a bcrypt hash. The agent reads the username and a plain password from `ADMIN_UI_USERNAME` and `ADMIN_UI_PASSWORD` at startup, hashes the password with `bcryptjs.hashSync` in memory, and skips `instrument` entirely when the variables are unset, so a developer who starts the app as before gets exactly the old behaviour and no open admin namespace. `mode` follows `NODE_ENV`, so a production process sends the lighter payloads the package documents, and `serverId` is set to the hostname joined with `process.pid`, because every worker in this cluster shares one hostname and the dashboard would otherwise show them as one server.

Two more changes make the dashboard reachable. The `Server` gets `cors: { origin: ['https://admin.socket.io'], credentials: true }`, which the package's README asks for; the chat page is served by the same server, so same-origin clients are unaffected. And the pull request explains the cluster shape: each worker listens on its own port, so the dashboard is pointed at one worker's address, such as `http://localhost:3000`, and the cluster adapter is what lets that worker report sockets and rooms held by its siblings. The README's note that basic auth across several servers needs a shared `store` is quoted, with `RedisStore` named as the option for a deployment that has Redis; this app does not, so the default in-memory store stays and the pull request says what that means for a reconnecting dashboard.

The test is small and runs with Node's built-in runner, since the repository has none: `test/admin.test.js` starts a single worker's server on a free port through a new `createApp` export split out of `index.js`, connects a `socket.io-client` to the `/admin` namespace without credentials and asserts `connect_error`, then connects with the configured username and password and asserts `connect`. The agent runs `npm install`, `node --test`, then starts the app with the two variables set and opens `https://admin.socket.io` in its sandbox browser, enters the worker's URL and the credentials, and takes a screenshot of the dashboard listing the server, its namespaces and a connected chat client for the pull request. `.gitignore`, which lists `chat.db`, is left alone, and `README.md` gains a short section on the two variables.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add the Socket.IO admin UI to this server. Read package.json, package-lock.json, index.js, index.html, .gitignore, the .codesandbox directory and README.md first. Install @socket.io/admin-ui. Call instrument on the Server only when ADMIN_UI_USERNAME and ADMIN_UI_PASSWORD are set, with basic auth using a bcryptjs hash computed at startup, mode from NODE_ENV, and a serverId of hostname plus process id because the app runs one worker per CPU. Add the cors origin for https://admin.socket.io with credentials. Split server creation into an exported createApp so a test can start one worker on a free port, and add test/admin.test.js with node --test that asserts the /admin namespace refuses a client without credentials and accepts the configured ones. Run npm install and node --test, start the app with the variables set, open https://admin.socket.io in the browser against one worker's port and screenshot the dashboard, then open a pull request with the output and the screenshot.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

The pull request changes `package.json`, `package-lock.json`, `index.js` and `README.md`, and adds `test/admin.test.js`. Its description pastes the `node --test` output, the startup log line that says instrumentation is on, and the screenshot of the hosted dashboard connected to one worker, showing the server id with its process id, the `/` and `/admin` namespaces and a connected chat socket.

The run's record keeps the install, the test run, the server start and the browser session, so a reviewer can see which worker the dashboard was pointed at and what it displayed. There is no CI in this repository; the pull request suggests a `node --test` workflow as a separate change.

Before merging, a reviewer sets the two environment variables in their deployment, decides whether to self-host the dashboard files from the package's `ui/dist` instead of using `https://admin.socket.io`, and whether `readonly: true` should be on so nobody can disconnect sockets from the dashboard. The chat handlers and the database are unchanged.

## Run it on every Socket.IO service without a dashboard

A team with several Socket.IO services starts one run per repository from its own server: a `POST /o/{org}/sessions` each, with the repository in `resources` and a `request_id` that is a UUID v5 of the repository's full name, so a retried call returns the run already started. Each run reads its own `index.js`, so a service behind a load balancer with sticky sessions gets the `RedisStore` wired for shared sessions when Redis is already present, and a single-process service gets the default `serverId`.

To keep the namespace locked, an automation in the Project with a `github` trigger on `pull_request.opened` and `pull_request.synchronize` and the prompt "if this pull request touches the instrument call or the cors option, check the admin namespace still requires credentials and the origin list has not grown, and say so in a comment" reviews each change. The trigger adds the pull request after the prompt and fires only for work by owners, members and collaborators.

## Why run it on Rush?

The admin UI is a three-line install with two traps: `auth: false` copied from a tutorial leaves a namespace that can disconnect any user open to the internet, and a clustered app with the default `serverId` shows every worker as one server. The agent reads the actual cluster code, gates instrumentation on environment variables, gives each worker its own id and proves the whole thing by opening the dashboard in a real browser before it opens the pull request.

Every command and the browser session stay with the run, and the pull request quotes the test output and carries the screenshot. Doing this for several services at once costs no more attention than one, each on its own machine with its own pull request.

## Frequently asked questions

### Is the dashboard safe to expose?

Only with authentication, which is why the agent refuses to call `instrument` without `ADMIN_UI_USERNAME` and `ADMIN_UI_PASSWORD` and uses basic auth with a bcrypt hash. The package also offers `readonly: true`, which disables join, leave and disconnect from the dashboard; the pull request names it for a reviewer who wants observation only.

### Why does each worker need its own serverId?

Because the default is the machine's hostname and this app runs one worker per CPU on the same machine, so the dashboard would merge them. Appending `process.pid` makes each worker a distinct server in the list, which is also how the package's README suggests handling several servers on one host.

### Do I have to use https://admin.socket.io?

No. The package's `ui/dist` folder holds the same static files, and the README says hosting them yourself is fine. If the team self-hosts, the `cors` origin changes to that address; the pull request shows where.

### Why test with node --test instead of adding a framework?

The repository has no test runner, and Node's built-in runner needs no dependency. The test starts one worker through the new `createApp` export and uses `socket.io-client`, which is already the client half of `socket.io`, to check that the `/admin` namespace rejects an anonymous client and accepts the configured credentials.

## More Socket.IO jobs

- [Add CORS to a Socket.IO Server](https://getrush.ai/run/add-cors/socket-io/)
- [Add Dependabot to a Socket.IO App](https://getrush.ai/run/add-dependabot/socket-io/)
- [Add a Dockerfile to a Socket.IO Chat Server](https://getrush.ai/run/add-dockerfile/socket-io/)

## More jobs like this: Hand off a long task

- [Add Admonitions to an mdBook](https://getrush.ai/run/add-admonitions/mdbook/)
- [Add Analytics to an Astro Blog](https://getrush.ai/run/add-analytics/astro/)
- [Add Google Analytics to a Gatsby Blog](https://getrush.ai/run/add-analytics/gatsby/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
