> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mesh.texturehq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Slack automatic setup

# Automatic Slack setup

Mesh can create a distinct Slack app for each agent, configure its permissions and events URL, upload its avatar, and collect its bot credentials through Slack OAuth. The manual connection flow remains available.

## Once per Mesh instance

1. Configure `MESH_AGENT_MASTER_KEY` and a stable, publicly reachable HTTPS `PUBLIC_URL`. Automatic setup requires an HTTPS origin without a path. Mesh uses HTTP Events API delivery; no Socket Mode app token is needed.
2. In Slack's [Your Apps](https://api.slack.com/apps) page, find **Your App Configuration Tokens** and generate a configuration token for the intended workspace. The Slack account must have permission to create apps. Workspace app-approval policies still apply.
3. In Mesh **Settings → Slack app provisioning**, paste the **refresh token**. Mesh rotates it immediately, stores the resulting access/refresh pair encrypted, and refreshes it while the server runs. This credential belongs to a Slack user and workspace; it is not a universal Slack administrator key.

The implementation and research are available in [PR #243](https://github.com/TextureHQ/mesh/pull/243).

The first version supports one current provisioning workspace per Mesh instance. Replacing that connection changes the workspace used for new setup. Existing bot installations continue working. To update an app created in a previous workspace, reconnect provisioning for that workspace.

## Creating an agent

1. Name the agent and connect OpenRouter or Ramp Router, then choose its models.
2. Write the persona or describe the agent's purpose and select **Draft a profile**. Review and save the draft. Upload a PNG/JPEG avatar, keep the generated geometric default, or use **Generate picture** with an image model from OpenRouter's current image catalog.
3. Choose Slack and select **Create Slack app**. Mesh creates the app, saves its credentials, registers a signed events URL, configures permissions and OAuth, and attempts to upload the picture.
4. Select **Install in Slack** and approve the installation. Slack may require workspace-admin approval. Mesh exchanges the authorization code on the server, validates the workspace and granted permissions, saves the bot credential, and activates the connection.
5. Open the app in Slack and send a test message. Invite it to channels where it should participate.

Profile generation works through either text provider. Ramp Router image generation is not enabled because its image-output API has not been verified. OpenRouter image generation uses `/images/models` and `/images`; generation uses the agent's saved provider credential and may incur provider charges. A failed generation does not block manual editing or upload.

A wizard draft URL survives reload. Provisioning progress is stored on the server, so refreshing or resuming a draft does not create another Slack app. Credentials are never persisted in browser storage.

## Recovery and maintenance

* **Creation outcome uncertain:** Mesh will not retry app creation blindly. Inspect the apps in Slack and recover that app using the manual connection option. The creation intent remains blocked rather than risking duplicates. Automated orphan reconciliation/deletion is not implemented.
* **Configuration failure:** resume setup against the saved app ID. Rate-limit errors expose Slack's retry delay; retry after that interval.
* **Picture upload failure:** installation remains available. Download the avatar and upload it through Slack's app settings, or retry **Sync profile picture**.
* **Expired/cancelled OAuth:** return to the saved setup and start a new installation attempt. OAuth state is single-use, session-bound, user-bound, and expires after ten minutes.
* **Saved installation awaiting activation:** use **Activate connection**. The bot credential has already been saved; another OAuth approval is unnecessary.
* **Changed hostname or configuration:** open the connection's **Manage automatic Slack setup and picture** link and select **Update Slack configuration**. This updates the existing app's event and OAuth callback URLs using the current `PUBLIC_URL`.
* **Changed avatar:** use **Sync profile picture** on each managed Slack connection. Uploading/generating a new Mesh avatar marks app icons pending; it does not silently publish the new picture to every connected app.
* **Revoked or expired provisioning grant:** reconnect it in Settings. Disconnecting provisioning removes its Mesh credential; it does not uninstall existing apps or revoke their bot tokens.

Mesh's existing single-replica deployment model still applies. The database prevents competing creation attempts and serializes configuration-token rotation, but runtime registry reload is local to the serving process.

## Implementation and verification

Migration `0041` adds durable Slack app intents, OAuth attempts and bounded PNG avatar storage. App client/signing credentials and OAuth bot credentials are encrypted with the existing secret store. Pending URL verification checks Slack's timestamped HMAC before the app is installed; active events must also match the recorded app and workspace before entering the existing ingress.

Automated checks cover encrypted persistence, concurrent token rotation, interrupted/ambiguous app creation, safe retries, pending signed challenges, OAuth session/workspace/scope validation and replay prevention. Browser coverage uses the real Go server and PostgreSQL with local Slack/OpenRouter fakes, and exercises both manual and automatic onboarding, identity generation, reload/resume, OAuth activation, configuration repair and expired authorization.

No real Slack app was created during implementation, and no paid model request was made. Before rollout, smoke-test the full flow in an authorized disposable workspace, especially `apps.icon.set` authorization, public URL verification, app approval and actual DM behavior. Slack's public icon documentation and CLI token behavior have inconsistencies; the fallback upload path is intentional. Test one real OpenRouter image response as well.

This implementation does not include manager-app enrollment, unattended child-app installation, shared instance model billing, public-channel discovery/joining, uninstall/revocation event handling, automatic orphan cleanup, a dedicated provisioning audit UI, or bulk hostname repair. See [the research and broader rollout plan](/slack-turnkey-onboarding-research).

## Troubleshooting the configuration connection

An expired **access token** on Slack's App Configuration Tokens page does not
require pasting that access token into Mesh. Mesh uses the **refresh token** to
obtain a new pair through `tooling.tokens.rotate`.

If connecting returns `Slack: invalid_arguments` on an older build, upgrade to
the fix that sends rotation requests as `application/x-www-form-urlencoded`.
Slack's live endpoint ignores JSON rotation bodies and reports a missing
`refresh_token`, even though its reference lists JSON support. A rejected request
of this kind does not rotate the token; retry with the refresh token after upgrading.
If Slack instead returns `invalid_refresh_token`, generate a new configuration
token pair in Slack and paste its refresh token.

Unexpected provisioning failures (HTTP 5xx responses) now reach the configured
error tracker with component `admin.api`, the route pattern, and a classified
error code, including `slack_invalid_arguments`. Tokens, request bodies, URLs,
and raw provider/database errors are excluded. Expected OAuth and setup-state
conflicts are not reported as failures.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.