https://github.com/marceloeatworld/discord-bridge
Discord Gateway bridge for ClopinetteAI — forwards messages to Cloudflare Workers via HMAC-signed HTTP. Bun, Docker, ~180 lines.
https://github.com/marceloeatworld/discord-bridge
bridge bun clopinette cloudflare-workers discord discord-bot docker gateway
Last synced: 16 days ago
JSON representation
Discord Gateway bridge for ClopinetteAI — forwards messages to Cloudflare Workers via HMAC-signed HTTP. Bun, Docker, ~180 lines.
- Host: GitHub
- URL: https://github.com/marceloeatworld/discord-bridge
- Owner: marceloeatworld
- Created: 2026-04-01T13:36:19.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-04-02T15:13:53.000Z (3 months ago)
- Last Synced: 2026-04-27T13:32:26.289Z (about 2 months ago)
- Topics: bridge, bun, clopinette, cloudflare-workers, discord, discord-bot, docker, gateway
- Language: TypeScript
- Homepage: https://clopinette.app
- Size: 11.7 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Discord Gateway Bridge
Lightweight bridge that connects to the Discord Gateway WebSocket and forwards messages to a [ClopinetteAI](https://github.com/marceloeatworld/clopinette-ai) worker via HTTP.
Discord requires a persistent WebSocket connection (Gateway) to receive regular messages — there is no webhook push like Telegram or WhatsApp. This bridge maintains that connection and forwards `MESSAGE_CREATE` events to the Clopinette worker.
## How it works
```
Discord Gateway (WSS)
|
v
Bridge (Bun, ~180 lines)
| - Maintains WebSocket + heartbeat
| - Handles reconnect/resume
| - Filters: DMs forwarded directly,
| guilds only on @mention or reply
|
v (HTTP POST, HMAC-SHA256 signed)
Clopinette Worker (/webhook/discord-bridge)
|
v
Durable Object (per-user or per-guild)
```
## Security
- **HMAC-SHA256** signature over `timestamp + body` — the shared secret never transits in the request
- **Anti-replay** — worker rejects requests older than 5 minutes
- **Timing-safe comparison** on the worker side
- **No public ports** — the bridge only initiates outbound connections (Discord WSS + Worker HTTPS)
- **Health check** returns only `ok` or `disconnected`, no sensitive data
## Setup
### 1. Deploy the Clopinette worker
Follow the [core setup](https://github.com/marceloeatworld/clopinette-ai#discord) to configure Discord secrets and register slash commands:
```bash
# In clopinette-ai-dev/
wrangler secret put DISCORD_TOKEN
wrangler secret put DISCORD_PUBLIC_KEY
wrangler secret put DISCORD_APPLICATION_ID
bun run deploy
# Register slash commands + generate bridge secret
curl -X POST https://your-worker/api/admin/setup-discord \
-H "Authorization: Bearer YOUR_API_AUTH_KEY"
# → returns { bridgeSecret, interactionsUrl, bridgeUrl }
```
### 2. Deploy the bridge
Set these environment variables on your Docker host (Coolify, etc.):
| Variable | Description |
|----------|-------------|
| `DISCORD_TOKEN` | Bot token from Discord Developer Portal |
| `BRIDGE_SECRET` | From the setup-discord response above |
| `WORKER_URL` | Your worker URL, e.g. `https://agent.clopinette.app` |
```bash
docker compose up -d
```
### 3. Discord Developer Portal
- **Bot** tab → enable **Message Content Intent**
- **General Information** → set Interactions Endpoint URL to `https://your-worker/webhook/discord`
- **OAuth2 → URL Generator** → scopes `bot` + `applications.commands`, permissions: View Channels, Send Messages, Embed Links, Attach Files, Read Message History, Add Reactions, Use Slash Commands
## Behavior
| Context | Trigger | Response |
|---------|---------|----------|
| DM | Any message | Forwarded to worker |
| Server | @mention or reply to bot | Forwarded to worker |
| Server | Regular message | Ignored |
| Any | Bot messages | Ignored |
## Gateway features
- Heartbeat with ACK tracking (zombie connection detection)
- Automatic reconnect with exponential backoff (max 30s)
- Session resume on disconnect (no message loss)
- Graceful shutdown on SIGTERM/SIGINT
## Requirements
- [Bun](https://bun.sh) runtime (via `oven/bun:1-slim` Docker image)
- A running ClopinetteAI worker with Discord secrets configured
## License
MIT