What the agent does
The agent reads how the app authenticates today before it changes a line, because the OAuth flow replaces the token rather than sitting beside it. In an app laid out like slack-samples/bolt-js-getting-started-app, package.json is an ES module with one dependency, @slack/bolt at ^5.1.0 (the lockfile resolves 5.1.0), and one script, start, which is node app.js. app.js creates new App({ token: process.env.SLACK_BOT_TOKEN, socketMode: true, appToken: process.env.SLACK_APP_TOKEN }), listens for messages containing hello with a button block, acknowledges the button_click action, and starts on process.env.PORT || 3000. manifest.json asks for three bot scopes, channels:history, chat:write and im:history, subscribes to message.channels and message.im, enables interactivity and Socket Mode, sets org_deploy_enabled to true and token_rotation_enabled to false, and has an oauth_config with scopes but no redirect_urls. AGENTS.md says the code carries no comments and explains itself through names. The README's setup installs the app into one workspace by hand and exports the two tokens, which is exactly what a second workspace cannot do.
The agent keeps Socket Mode and adds OAuth on top of it, since Bolt's Socket Mode receiver serves the install and redirect routes over a small HTTP server on the port app.start already takes. app.js loses the token option and gains clientId, clientSecret, stateSecret and signingSecret from new environment variables, scopes copied from the manifest's three bot scopes so the two cannot disagree, and an installationStore with the three functions Bolt calls: storeInstallation keyed by enterprise.id for an org-wide install and team.id otherwise, fetchInstallation for the same keys, and deleteInstallation for the app_uninstalled and tokens_revoked events, which the agent subscribes to in the manifest so a workspace that removes the app is forgotten. installerOptions.directInstall is set so /slack/install sends a visitor straight to Slack's consent page. The store itself lives in installation-store.js as a JSON file keyed by those ids, with the file path from an environment variable, and its three functions are the whole interface a database-backed store would replace.
manifest.json gains oauth_config.redirect_urls with the app's public https address plus /slack/oauth_redirect, and settings.event_subscriptions.bot_events gains app_uninstalled and tokens_revoked. The README's setup section changes from exporting a bot token to reading the client id, client secret and signing secret from the app's Basic Information page, generating a state secret, and opening /slack/install once per workspace. Following AGENTS.md, the new code has no comments, and the reason for each change sits in the pull request description instead. org_deploy_enabled stays true, and the store's enterprise key is what makes an org-wide install resolve.
To check it, the agent runs npm ci and node --check app.js in its sandbox, writes installation-store.test.js with node --test covering store, fetch and delete for a team install and an enterprise install, and runs it. It then starts the app with placeholder secrets and no app token, which keeps Socket Mode from connecting, and requests http://localhost:3000/slack/install to confirm the receiver answers with a redirect to Slack's authorize URL carrying the three scopes and a state parameter, which it records. It does not install the app anywhere, because that needs your Slack app's credentials and a person's consent.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add Slack's OAuth install flow to this Bolt app so it can be installed in more than one workspace. Read package.json, app.js, manifest.json, AGENTS.md and README.md first. Keep Socket Mode. Replace the bot token with clientId, clientSecret, stateSecret and signingSecret from environment variables, set scopes from the manifest's bot scopes, and add an installationStore in its own module backed by a JSON file at a path from an environment variable, keyed by enterprise id for org installs and team id otherwise, with store, fetch and delete. Handle app_uninstalled and tokens_revoked by deleting the installation and subscribe to both in the manifest. Add the redirect URL to the manifest's oauth_config and update the README's setup steps. Follow AGENTS.md: no code comments. Add node --test tests for the store, run them, run node --check, start the app with placeholder secrets and show that /slack/install redirects to Slack's authorize URL with the scopes and a state parameter, and open a pull request with the output. Do not install the app anywhere.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- 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.
- 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.
- 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 app.js, manifest.json, README.md and package.json, and adds installation-store.js and installation-store.test.js. Its description explains each change the way AGENTS.md asks, pastes the node --test output, and shows the redirect the install route returned in the sandbox with its scopes and state parameter.
The repository's only workflow handles Dependabot merges, so there is no check to wait for; the evidence is the run's record, with the test output, the node --check result and the HTTP exchange against the install route. The first real install happens when you open /slack/install with your own app's credentials.
Before merging, a reviewer decides whether the JSON store is enough for the first deployment or whether to swap the three functions for a database table now, whether to turn on token rotation in the manifest and in Bolt, and which public address goes into redirect_urls. The message and action listeners are unchanged.
Run it on every Bolt app that still runs on one bot token
A team with several Slack apps sends this body once per repository to POST /o/{org}/sessions, each with its own 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 app.js: an app on an HTTP receiver gets the routes on that receiver instead of the Socket Mode server, and one that already uses an authorize function gets it replaced by the store rather than duplicated.
A webhook_url on the key reports each run.completed with the pull request in result, and a run.failed names an app whose code the agent could not start in its sandbox, for instance one that reads a secret at import time and exits without it.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
Moving a Bolt app from one token to OAuth touches the constructor, the manifest, the setup docs and two events, and the mistakes are quiet ones: a scope list that drifts from the manifest, an install keyed by team id that breaks for an org-wide install, an uninstall that leaves a dead token behind. The agent reads the manifest and the constructor together, keys the store the way Bolt will look it up, and proves the install route answers in its own sandbox.
The tests, the start-up log and the install redirect stay with the run and are pasted into the pull request, so the review is reading evidence rather than re-deriving Bolt's OAuth options. Several apps can get the same change at once, each in its own sandbox.
Frequently asked questions
Does the app have to leave Socket Mode?
No. Bolt's Socket Mode receiver can serve the /slack/install and /slack/oauth_redirect routes from a small HTTP server on the port the app already starts on, so events keep arriving over the socket and only the install pages are served over HTTP. The redirect URL in the manifest must point at that server's public https address.
Where are the installations stored?
In a JSON file at a path from an environment variable, through a module that exposes exactly the three functions Bolt calls. That is enough to run and to test; the pull request names it as the module to replace with a database table before the app is installed widely, and the keys, enterprise id or team id, stay the same.
Will it still work for the workspace that installed it by hand?
Not with the old token, because the token option is removed. That workspace installs once more through /slack/install, which takes a few seconds, and from then on its token lives in the store like every other workspace's.
Does the agent install the app into a workspace to test?
No. Installing needs your app's client secret and a person's consent on Slack's page, so the agent stops at proving the install route redirects to Slack's authorize URL with the right scopes and a state parameter, and at testing the store. The first install is yours.