Operations
Remote bridge (wss)
Run the app process off-host with wss://, TLS, secret rotation, logging boundaries, and realistic health expectations.
Shardwire allows ws:// only on loopback (127.0.0.1, localhost, ::1). Any other host must use wss:// (App bridge).
This page is the operator view for remote bridges—not a replacement for your platform’s TLS and network standards.
TLS and ingress
- Terminate TLS at your edge or load balancer and forward WebSocket upgrades to the process running
createBotBridge. - Preserve the bridge path (default
/shardwire) end-to-end. - Confirm idle timeouts: Shardwire uses heartbeats; aggressive proxies must allow bidirectional ping/pong or equivalent keepalive.
Secrets and trust
- Treat each
SHARDWIRE_*secret like a bearer token for Discord-backed capabilities. - Prefer scoped secrets per app (Secret cookbook).
- Rotate by introducing a new secret value, deploying clients, then removing the old value—see rotation notes in the cookbook.
What to log (and what to avoid)
Safe / useful
- connection id, app name, auth success/failure (without secret values)
- action name,
requestId, duration,ok, and stableerror.codefromActionResult - diagnosis output from
formatShardwireDiagnosison strict-startup failure
Avoid
- full Discord message bodies in info-level logs on busy guilds
- raw secret values or Discord tokens in logs
Use AppBridgeMetricsHooks for structured action completion metrics (Observability).
Health and failure modes
Operators should assume two liveness questions:
- Discord gateway / bot process — is
createBotBridgerunning and healthy? - App connections — are expected app processes connected and authenticated?
Common failures look like transport issues but are usually capability issues: wrong intents, narrow allow, or manifest mismatch. Run diagnoseShardwireApp with production-like botIntents and a frozen negotiation fixture (CI contract validation).