WebDashboard

WebDashboard

🌐 English · Deutsch

WebDashboard is the companion cog that turns Red into a web-manageable bot. It runs inside the bot process and exposes a small, secure JSON-RPC gateway on localhost, an integration registry that collects widgets, panels and pages contributed by other cogs, and a persistent audit log for write actions. The actual browser UI — with Discord OAuth2 login, the widget board and contextual panels — lives in a separate repository: PDC_Redbot_Webapp. This cog is the bot side; the web app is the frontend.

The design runs alongside the AAA3A Red-Web-Dashboard (its command group is named pdcdashboard, not dashboard), so the two can coexist. Author: pd-codes · requires Red 3.5.0+ · Status: Release.

How it fits together

Two separately deployable parts talk over a token-authenticated JSON-RPC link:

Red-DiscordBot (Python)                 Web app (Node / SvelteKit)
┌───────────────────────────┐          ┌───────────────────────────┐
│ pdc_webdashboard (this cog)   │  JSON-   │ SvelteKit server (BFF)    │
│  ├─ RPC gateway (aiohttp) │◄─ RPC ──►│  ├─ Discord OAuth2        │
│  ├─ Integration registry  │  + WS    │  ├─ Session / cookies     │
│  ├─ Core provider         │ (token)  │  └─ RPC client            │
│  └─ Permission mapper     │          └───────────┬───────────────┘
└───────────────────────────┘                      │ HTTP/WS
┌───────────────────────────┐          ┌───────────▼───────────────┐
│ Third-party cogs          │          │ SPA (Svelte + Tailwind)   │
│  (DashboardIntegration)   │          │  widget board / panels    │
└───────────────────────────┘          └───────────────────────────┘

• This cog provides the gateway, the registry into which cogs register, and a permission mapper that resolves a Discord user to a Red permission level.
• The SvelteKit web app is a Backend-for-Frontend (BFF): it owns Discord OAuth2, holds the session, and is the only client that knows the gateway token. The browser SPA never talks to the bot directly.

Installation

[p]repo add PDC_Redbot_Cogs https://github.com/pd-codes/PDC_Redbot_Cogs
[p]cog install PDC_Redbot_Cogs pdc_webdashboard
[p]load pdc_webdashboard

[p] is your bot's prefix. See Installation for the full Downloader walkthrough. On load the gateway starts automatically (autostart is on by default) on 127.0.0.1:6970.

Setting it up

1. Check the gateway

[p]pdcdashboard status

This shows whether the gateway is running, its address and the number of registered contributions. To change the address use bind (a restart is required), and stop / start to control it:

[p]pdcdashboard bind 127.0.0.1 6970
[p]pdcdashboard stop
[p]pdcdashboard start

Security: keep the gateway bound to 127.0.0.1. Don't bind directly to 0.0.0.0 — expose it only through a reverse proxy or tunnel with TLS.

2. Get the token

[p]pdcdashboard token

The token is sent to you by DM (so it never appears in a channel). The web app's BFF is the only thing that should hold it. If you ever leak it, rotate it:

[p]pdcdashboard regen

regen creates a fresh token and restarts the gateway, so you must update the web app afterwards and fetch the new value with [p]pdcdashboard token.

3. Configure the web app .env

In the PDC_Redbot_Webapp project:

GATEWAY_URL=http://127.0.0.1:6970
GATEWAY_TOKEN=<token from [p]pdcdashboard token>
DISCORD_CLIENT_ID=...
DISCORD_CLIENT_SECRET=...
DISCORD_REDIRECT_URI=https://your-domain/auth/callback
SESSION_SECRET=<openssl rand -hex 32>

The full web-app setup is documented in its own wiki: https://github.com/pd-codes/PDC_Redbot_Webapp/wiki.

Owner commands

The pdcdashboard group (alias pdcdash) is bot-owner only.

Command	What it does
[p]pdcdashboard status	Show running state, address (http://host:port) and the number of registered contributions (and how many cogs they come from).
[p]pdcdashboard start	Start the gateway.
[p]pdcdashboard stop	Stop the gateway.
[p]pdcdashboard bind <host> <port>	Persist host and port. A reload/restart is required for it to take effect.
[p]pdcdashboard token	DM you the current gateway token (generates one if none exists).
[p]pdcdashboard regen	Generate a new token and restart the gateway. Update the web app afterwards.

The group uses the custom name pdcdashboard deliberately, so it runs in parallel with AAA3A's [p]dashboard.

The gateway

The gateway is an aiohttp application bound to localhost by default. It offers both a request/response surface and a streaming surface:

Endpoint	Method	Purpose
/api/health	GET	Liveness probe. Returns {"status":"ok", "bot_ready": …, "time": …} without a token.
/api/manifest	GET	Convenience mirror of manifest.get. Requires the token.
/rpc	POST	JSON-RPC 2.0 request/response (and batches). Requires the token.
/rpc	GET (WebSocket)	JSON-RPC 2.0 over WS for streams/server push (live logs, stats). Authenticates in the first connection_init frame.

Authentication between the BFF and the gateway uses a shared secret compared in constant time (hmac.compare_digest). The token travels in the X-Dashboard-Token header for HTTP, or in the connection_init frame for WebSocket. Every endpoint except /api/health and the WS upgrade requires it.

The web app sends the verified Discord user context (e.g. X-User-Id, X-Guild-Id); the gateway resolves the effective Red permission level server-side on every call. Frontend filtering is purely cosmetic.

Permission levels

User access is mapped onto Red's own permission system. Levels are ordered — a higher level satisfies every lower one.

Level	Resolved when…
bot_owner	bot.is_owner(user) is true.
guild_owner	The user is the guild's owner (guild.owner_id == user.id).
guild_admin	The user has Red's admin role, or the Discord Manage Server permission.
guild_mod	The user has Red's mod role.
guild_member	The user is a member of the guild.
authenticated	The user is logged in (no guild context, or not/no-longer a member).

Tip: if users see no servers or widgets despite having permission, enable the Server Members Intent in the Discord Developer Portal. Without it Red doesn't know the members and permission resolution falls back to authenticated.

Audit log

Write actions are audited. Each entry records the action, the acting user, the guild, a detail payload and a timestamp; the cog persists the last 1000 entries in its config. Audit entries are also written to the bot log.

Security at a glance

• Gateway is localhost-only by default; token auth (constant-time) between BFF and cog.
• Discord OAuth2 happens in the BFF; permissions are enforced server-side per call.
• Cogs return only declarative schemas (no raw HTML) → no XSS surface.
• No secrets in the frontend: the Discord client secret and gateway token stay server-side.

For developers

Want to surface your own cog in the dashboard? See Dashboard Integration for the contract (@dashboard_widget, @dashboard_panel, @dashboard_page and register_third_party). A ready-made consumer of the gateway's stats methods is Web DashboardStats.

Related pages

• Dashboard Integration — wire your cog into the board
• Web DashboardStats — per-guild statistics for the dashboard /stats page
• Web app wiki: https://github.com/pd-codes/PDC_Redbot_Webapp/wiki
• Home