# Add Health Checks to a Socket Mode Slack Bolt App

Yes. An agent adds liveness and readiness routes to your Socket Mode Bolt app that report the WebSocket's real state, tested without a workspace, as a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-health-checks/slack-bolt/). 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 app connects to Slack before adding a probe, because a Socket Mode app has no inbound HTTP and a health check copied from a web service would probe nothing. In the app from slack-samples/bolt-js-getting-started-app, `package.json` depends on `@slack/bolt` ^5.1.0 alone, with `"type": "module"` and a single `start` script, and `package-lock.json` resolves `@slack/socket-mode` and `@slack/web-api` beneath it. `app.js` constructs `new App({ token, socketMode: true, appToken })`, registers a `message('hello')` listener and a `button_click` action, and calls `app.start(process.env.PORT || 3000)`. `manifest.json` has `socket_mode_enabled` true and no request URL. `AGENTS.md` asks for no code comments, with reasons in the pull request. The one workflow, `dependencies.yml`, auto-merges Dependabot's minor and patch updates.

Bolt's Socket Mode receiver can serve HTTP after all: when `customRoutes` is given, it creates a Node `http` server on `installerOptions.port`, which defaults to `3000`, and listens on it from `start()`. The port argument passed to `app.start` is not what that server uses, which the pull request says plainly because the existing call suggests otherwise. The agent builds the receiver explicitly as `new SocketModeReceiver({ appToken, customRoutes, installerOptions: { port } })` and passes it to `App` through `receiver`, which is the only way to reach the receiver's `client`, the `SocketModeClient` that emits `connecting`, `connected`, `authenticated`, `reconnecting`, `disconnecting` and `disconnected`. A small `connectionState` module subscribes to those events, keeps the latest name and the time it changed, and exposes a function the routes read.

The routes are two. `GET /healthz` answers `200` with `{ status: 'ok' }` whenever the process is up, so a Slack outage never makes an orchestrator restart a process that will reconnect by itself. `GET /readyz` answers `200` with `{ status: 'ok', socket: 'connected', since }` when the latest state is `connected` or `authenticated`, and `503` with the current state when it is anything else, including the window after `start()` before the first `hello` from Slack. Both set `Cache-Control: no-store`. Readiness means something for a Socket Mode app because a process whose WebSocket has been `reconnecting` for minutes is not receiving events, and that is the state a dashboard should show. The port comes from `HEALTH_PORT` with `3000` as the fallback, and the README gains a line per variable.

The agent proves this without a Slack workspace. `test/health.test.js`, run by a new `test` script using `node --test`, constructs the receiver with placeholder tokens, drives the `connectionState` module by emitting the client's events in sequence, starts only the HTTP server through the receiver's own `httpServer` on an ephemeral port, and asserts `/readyz` is `503` before any event, `200` after `connected`, `503` after `reconnecting` and `200` again after `authenticated`, while `/healthz` is `200` throughout. It runs `npm install`, `npm test` and `node --check app.js`, then starts the app once with placeholder tokens to show the HTTP server bound and `/readyz` answering `503` with `connecting` while the app fails to authenticate, and opens the pull request.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add health checks to this Socket Mode Bolt for JavaScript app. Read package.json, package-lock.json, app.js, manifest.json, README.md and AGENTS.md first. Build the receiver explicitly with new SocketModeReceiver and pass it to App through receiver, keeping the message and action listeners as they are. Add a connectionState module that subscribes to the receiver's client events connecting, connected, authenticated, reconnecting, disconnecting and disconnected and keeps the latest state and when it changed. Add customRoutes with GET /healthz, which answers 200 with status ok and no I/O, and GET /readyz, which answers 200 with the socket state and the time since it changed when the state is connected or authenticated, and 503 with the current state otherwise; set Cache-Control no-store on both. Serve them on installerOptions.port read from HEALTH_PORT with 3000 as the fallback, and explain in the pull request that the argument to app.start is not the port this server uses. Add a test script using node --test and test/health.test.js that builds the receiver with placeholder tokens, emits the client events in sequence, starts only the receiver's HTTP server on an ephemeral port, and asserts /readyz is 503 before any event, 200 after connected, 503 after reconnecting and 200 after authenticated, with /healthz 200 throughout. Follow AGENTS.md: no code comments. Document HEALTH_PORT in README.md. Run npm install, npm test and node --check app.js, start the app with placeholder tokens to show the HTTP server bound and /readyz answering 503 while authentication fails, and open a pull request that pastes the responses.",
  "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

What comes back is a pull request that changes `app.js`, `package.json` and `README.md`, and adds `connectionState.js` and `test/health.test.js`. The description pastes the `node --test` summary with the four readiness transitions, the responses from `/healthz` and `/readyz` against the app started with placeholder tokens, showing `503` and the `connecting` state while Slack refuses the token, and says in one paragraph why `installerOptions.port` and not the `app.start` argument decides the port.

The run's record holds the install, the test run, the syntax check and the short run with placeholder tokens. The listeners for the `hello` message and the button are untouched, and `manifest.json` does not change because the app stays in Socket Mode.

Before merging, a reviewer decides whether the Dockerfile or deployment should expose the health port, which orchestrator probe maps to which route, and whether a long `reconnecting` state should also alert somewhere beyond the readiness answer.

## Run it on every new Slack app

A team that runs several Socket Mode apps starts one run per repository from its own server: one `POST /o/{org}/sessions` each, with that 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 rather than a second pull request. Each run reads that app's own receiver setup, so an app already using HTTP mode gets its routes added to the existing receiver instead of a second server.

Afterwards, an automation on the Project with a `github` trigger on `pull_request.opened` and `pull_request.synchronize` and the prompt "if this pull request changes how the App or receiver is constructed, run the health test and comment with whether the readiness route still tracks the socket state" keeps a refactor from quietly disconnecting the probe from the client it watches. The trigger adds the pull request after the prompt; only work by an owner, member or collaborator fires it, never a fork's.

## Why run it on Rush?

A Socket Mode app can be alive, bound to a port and useless, because its WebSocket has been reconnecting for an hour, and a health check that returns `200` for a running process hides exactly that. The agent reads the receiver and client source to find the events that describe the connection, wires the readiness answer to them, and drives every transition in a test in its own sandbox, so the reviewer sees the `503` during reconnecting rather than trusting a route that always says ok.

The sandbox keeps the test run and the responses with the run, and the pull request cites them. For a team with many Slack apps, each gets its own run and its own pull request with the same two paths, so one probe configuration serves all of them.

## Frequently asked questions

### Why does a Socket Mode app need an HTTP port at all?

Slack never calls it, but an orchestrator does. Socket Mode replaces inbound event delivery with an outbound WebSocket; liveness and readiness probes are a separate concern, and Bolt's receiver serves `customRoutes` on its own small HTTP server for exactly this. Nothing about the Slack side of the app changes and the manifest stays as it was.

### Why is the port not the one passed to app.start?

Because with Socket Mode the receiver's `start()` opens the WebSocket and, when custom routes exist, listens on `installerOptions.port`, which defaults to `3000`; the argument given to `app.start` is forwarded but not used for that server. The agent sets `installerOptions.port` from `HEALTH_PORT` and says so in the pull request, so the existing `process.env.PORT || 3000` line stops being misleading.

### What does readiness report before the first connection?

`503` with the state `connecting`, which is the honest answer during the window between `start()` and Slack's `hello` message, and again whenever the client reports `reconnecting` or `disconnected`. Liveness stays `200` through all of it, so the process is left alone to reconnect.

### How does the test run without a workspace?

The receiver is built with placeholder tokens and never asked to open the WebSocket; the test starts only its HTTP server and emits the client's state events itself. That exercises the state module and both routes end to end on a real socket, while the only Slack call that would fail is never made.

## More Slack Bolt jobs

- [Add a Message Shortcut to a Slack Bolt App](https://getrush.ai/run/add-message-shortcuts/slack-bolt/)
- [Add a Modal to a Slack Bolt App](https://getrush.ai/run/add-modals/slack-bolt/)
- [Add an OAuth Install Flow to a Slack Bolt App](https://getrush.ai/run/add-oauth-install-flow/slack-bolt/)

## The same job on other stacks

- [Add a Health Check Endpoint to a Slim 4 App](https://getrush.ai/run/add-health-checks/slim/)
- [Add a Health Check Endpoint to a Socket.IO Server](https://getrush.ai/run/add-health-checks/socket-io/)
- [Add Health Checks to a Symfony App](https://getrush.ai/run/add-health-checks/symfony/)

## 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/)
