TLS and reverse proxies
In production the hub requires BETTER_AUTH_URL to be set to an https:// URL — it refuses to
boot otherwise. That value 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.
Examples
Section titled “Examples”Caddy provisions and renews TLS automatically and proxies WebSockets without extra config:
runaway.example.com { reverse_proxy localhost:3000}Set BETTER_AUTH_URL=https://runaway.example.com in the hub’s environment.
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
BETTER_AUTH_URL to the public https:// URL you route to.
Put Cloudflare in front of your proxy or origin for TLS at the edge. WebSocket support is on by
default. Set BETTER_AUTH_URL to the public hostname Cloudflare serves.
Split-hostname deploys
Section titled “Split-hostname deploys”If the public origin where GitHub delivers webhooks differs from your auth origin — for example,
auth runs on an internal hostname while webhook deliveries arrive through a public tunnel — set
RUNAWAY_PUBLIC_URL to the public webhook-ingress origin. The webhook receiver registers the
GitHub-side hook under that URL; it defaults to BETTER_AUTH_URL, so single-origin deploys leave it
unset. See Webhooks.
Troubleshooting
Section titled “Troubleshooting”- Sign-in succeeds but you’re bounced back to the login page.
BETTER_AUTH_URLdoesn’t match the URL in your browser. Cookies are scoped to that origin — set it to the exact user-facinghttps://URL and restart.
For the full list of URL-related variables, see the environment variables reference.