SHARDWIRE
Guides

Keeping it alive

Run your bot on Railway, Render, or a VPS—use wss://, protect secrets, and think in two pieces: bot + app.

Running your bot in production means running two things you already have locally:

  1. Bot bridge — still uses createBotBridge (Discord + bridge server).
  2. App — still uses connectBotBridge, but The Connection URL becomes wss:// instead of ws:// on localhost.

You are not learning “systems architecture”—you are picking a host and setting env vars.

The one rule that trips people up

ws:// is only for loopback. On the public internet, use wss:// (TLS), same idea as HTTPS.

Railway or Render (friendly PaaS)

Typical shape:

  • Service A (bot) — Node 22+, start command runs your bot entry (createBotBridge). Expose the bridge port (or use the platform’s private networking if both services live in the same project).
  • Service B (app) — Node 22+, start command runs your app entry (connectBotBridge) with SHARDWIRE_URL=wss://…/shardwire pointing at A.

WebSockets on PaaS

Confirm your platform allows WebSocket upgrades on the route to the bridge (some need explicit “enable websockets” or a dedicated port). If connections drop, check idle timeouts—bridges use heartbeats; aggressive proxies need to allow bidirectional ping/pong.

Secrets

  • Put DISCORD_TOKEN and SHARDWIRE_SECRET in the host’s secret store, not in your repo.
  • The app secret must match a secret configured on the bot bridge.

VPS (you control the box)

  • Run the bot process under systemd, pm2, or a container.
  • Put TLS in front of the bridge (Caddy, nginx, or a cloud load balancer) and expose wss:// to your app.
  • Run one or more app processes wherever makes sense; each uses wss:// to connect.

Capability audit before you blame the network

If “it connects but nothing happens,” it is often intents, secret scope, or subscriptions—not “the wire is broken.” Use Troubleshooting and, when you need raw types, Reference → Errors & failures.

Checklist

  • Bridge path end-to-end (often /shardwire).
  • Remote URL uses wss://.
  • Secrets match between bot config and app env.
  • Node 22+ on the app side.

Reference

Your first slash command

Register a /hello command, reply from the app, then change the text and restart only the app—no gateway reconnect.

React cookbook

Patterns for @shardwire/react: connection lifecycle, strict manifests, and avoiding unnecessary reconnects.

On this page

Railway or Render (friendly PaaS)VPS (you control the box)ChecklistReference