All jobs

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 RushOpens 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.emits 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 with this body:

{
  "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.

The use case this job follows, with its automation and trigger: Hand off a long task.

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

More jobs like this: Hand off a long task

Keep reading