TLS and reverse proxies

In production the hub requires RUNAWAY_HUB_URL to be set to an https:// URL — it refuses to boot otherwise. This is the canonical public URL of the hub: the browser, GitHub, and agents all default to it. It gates the session cookie’s Secure flag and the CSRF trusted origin, so running over plain HTTP in production would leave both silently insecure. Failing closed is the point.

The container serves the API, auth, the agent WebSocket, and the frontend from one origin on one port (default 3000), so a single proxy rule covers everything.

Caution

Your proxy must pass WebSocket upgrades for /api/agent. Agents dial home over that path, and a proxy that strips the upgrade will leave every agent unable to connect.

Examples

Caddy

Caddy provisions and renews TLS automatically and proxies WebSockets without extra config:

runaway.example.com {
  reverse_proxy localhost:3000
}

Set RUNAWAY_HUB_URL=https://runaway.example.com in the hub’s environment.

Traefik

Route the hub’s service to your domain with TLS via your usual certresolver. Traefik forwards WebSocket upgrades by default, so /api/agent works without special handling. Set RUNAWAY_HUB_URL to the public https:// URL you route to.

Cloudflare

Put Cloudflare in front of your proxy or origin for TLS at the edge. WebSocket support is on by default. Set RUNAWAY_HUB_URL to the public hostname Cloudflare serves.

Split-hostname deploys

If the public origin where GitHub delivers webhooks differs from the canonical hub URL — for example, the hub runs on an internal hostname while webhook deliveries arrive through a public tunnel — set RUNAWAY_WEBHOOK_URL to the public webhook-ingress origin. The webhook receiver registers the GitHub-side hook under that URL; it falls back to RUNAWAY_HUB_URL, so single-origin deploys leave it unset. See Webhooks.

Troubleshooting

• Sign-in succeeds but you’re bounced back to the login page. The auth origin doesn’t match the URL in your browser. Cookies are scoped to that origin — set RUNAWAY_HUB_URL (or RUNAWAY_APP_URL, if the browser reaches the hub at a different origin than the canonical URL) to the exact user-facing https:// URL and restart.

For the full list of URL-related variables, see the environment variables reference.

What’s next

Exposing the hub publicly What protects a hub on the open internet.