mirageslack

mirage-slack

A thin reverse proxy / multiplexer for Slack Apps development — one shared parent Slack App, many developer endpoints.

  Slack workspace                                   developer endpoints
  ┌────────────────┐                                ┌────────────────────┐
  │ Slash commands │                                │  alice's ngrok     │
  │ Interactivity  │──▶ mirage-slack ──────────────▶│  bob's local server│
  │ Events API     │    (channel-based routing)     │  main / production │
  └────────────────┘                                └────────────────────┘

Instead of spinning up a separate Slack App per developer (dev Alice, dev Bob, staging, …), create one parent Slack App once, point it at mirage-slack, and let each channel dispatch to a different endpoint. Developers use slash commands to register their own endpoint, bind it to a channel, and stop when done.

• Simple forwarder — Slack payloads pass through untouched. The endpoint sees the same request shape it would see when wired directly to Slack, so end-to-end behaviour observed via mirage-slack matches production.
• Self-discovering storage — The runtime uses a bot-owned Slack List as its only backing store. No DynamoDB / Postgres to set up. mirage-slack finds or creates the list on startup.
• Lambda / server / container ready — Single binary runs on all three via fujiwara/ridge.

Contents

• Install
• Quick start
• Slash subcommands
• Configuration
• Design & architecture
• Contributing

Install

go install github.com/mashiike/mirage-slack/cmd/mirage-slack@latest

Requires Go 1.26+.

Quick start

1. Create the parent Slack App

Create an app at api.slack.com/apps and configure:

The URL paths shown above (/slack/commands, /slack/interactive, /slack/events) are the defaults mirage-slack listens on. If your hosting layer requires different paths, override them via server.paths.* in the config and register the matching URLs in the Slack App settings.

Minimal Bot Token scopes:

• commands (receive slash commands)
• lists:write, lists:read (manage the bot-owned Slack List)

Add any scope your forward targets need in production (app_mentions:read, chat:write, channels:history, …). These must be registered here because the parent App is the one actually subscribed to Slack events.

2. Generate a starter config

mirage-slack init-config > config.jsonnet
# or
mirage-slack init-config --output config.jsonnet

Edit the file if you want to override defaults. The minimum workable configuration uses only two environment variables:

local env = std.native('env');

{
  slack: {
    signing_secret: env('SLACK_SIGNING_SECRET'),
    bot_token: env('SLACK_BOT_TOKEN'),
  },
  command: { name: '/mirage-slack' },
  routing: {},
}

3. Run the server

export SLACK_SIGNING_SECRET=...
export SLACK_BOT_TOKEN=xoxb-...
mirage-slack run --config=config.jsonnet --addr=:8080

On startup, mirage-slack:

1. Calls auth.test to resolve the bot's user ID and team URL.
2. Searches files.list?types=lists for a bot-owned list whose title matches slack.list_name (defaults to the slash command name without the leading slash; e.g. /mirage-slack → mirage-slack).
3. If no list is found, creates one via slackLists.create with mirage-slack's fixed schema.
4. Caches the list metadata (column IDs, permalink components) and starts serving HTTP.

No separate init / migration step is required.

AWS Lambda: match the Function URL Invoke Mode

mirage-slack relies on fujiwara/ridge to adapt the HTTP handler to the Lambda runtime. Ridge defaults to the buffered response format ({statusCode, headers, body, ...}). If the Lambda Function URL's Invoke Mode is set to RESPONSE_STREAM, set the RIDGE_STREAMING_RESPONSE=true environment variable so ridge switches to the streaming response format. When the two disagree, Function URL cannot unwrap the response and the raw Lambda proxy envelope leaks through to Slack as a JSON string.

Slack slash commands complete within the 3-second ACK window, so BUFFERED is the natural choice unless you already have a reason to use RESPONSE_STREAM.

4. Register a development endpoint

From any channel:

/mirage-slack register alice https://alice.ngrok.app
/mirage-slack launch alice

Subsequent slash commands / interactivity / events in that channel are forwarded to https://alice.ngrok.app. When you are done:

/mirage-slack terminate alice       # stop forwarding, keep the registration
/mirage-slack unregister alice      # remove the registration entirely

Slash subcommands

Rules:

• Registrations are workspace-wide; launch bindings are per-channel.
• One environment per channel: if another entry is already launched in the same channel, launch errors out — terminate the other one first.
• DMs are not supported as launch targets (public / private channels only).
• Success responses post in the channel (in_channel). Errors and usage go to the invoking user only (ephemeral).

Configuration

Config is a Jsonnet file. Two native functions are registered:

CLI flags:

mirage-slack [--config=path] [--log-format=json|text] [--log-level=debug|info|warn|error] <command>

Commands:
  run          [--addr=:8080]                    start the HTTP server
  init-config  [--output path] [--force]         emit a starter config.jsonnet

Design & architecture

• Transparent forwarding is the non-negotiable property. mirage-slack does not validate, enrich, or reshape payloads on the forward path by default. This is what makes it a development aid: if the endpoint works under mirage-slack, it will work when wired to Slack directly.
• Opt-in signature verification (launch --protect, routing.default_endpoint_protect) exists for production-ish endpoints that should not be usable as an open relay.
• 3-second Slack SLA is handled with context.WithoutCancel: the forward request is detached from the inbound context so the endpoint can keep processing past the 2.5-second ACK deadline. Late replies must use Slack's response_url (this is the standard Slack pattern anyway).

For the complete rationale, see docs/ARCHITECTURE.md.

Contributing

• See CLAUDE.md for the developer hand-off notes (architecture invariants, non-obvious gotchas, how to reason about changes).
• go build ./... / go vet ./... should pass without errors.
• my-local/echo-endpoint/ is a throwaway forward target useful for manual end-to-end verification with ngrok / devtunnels.

License

MIT