When a service is behind a reverse proxy, Ragnarr only needs the public or private URL that reaches the service API from your iPhone or iPad. Ragnarr talks to the same HTTP API the web UI uses - so if the proxy serves the web UI correctly but strips or blocks API traffic, Ragnarr will fail where a browser appears to work.

Recommended checks

  • Open the proxied URL in Mobile Safari from the same network.
  • Confirm the proxy forwards API paths (/api/…), not only the web UI route.
  • Confirm authentication headers and API key parameters are not stripped - Sonarr-family services authenticate with an X-Api-Key header.
  • Prefer HTTPS for any URL exposed outside your home network.

Watch out for auth middleware

Basic auth, Authelia, Authentik or a Cloudflare Access rule in front of a service will intercept Ragnarr's API requests and answer with a login page or a 401. Common patterns that keep the protection while letting Ragnarr through:

  • Exclude the service's /api routes from the auth middleware - the API is already protected by its own key.
  • Or skip the middleware entirely for that hostname and rely on the service's API key + HTTPS.

A telltale symptom: Test connection fails with an HTML response or a redirect while the same URL "works" in a browser where you are already logged in.

Base URL examples

Both subdomain and path-based routing can work if your service supports the route and the proxy forwards it correctly:

  • https://sonarr.example.com - subdomain routing, no extra service config.
  • https://media.example.com/sonarr - path-based routing; the service's URL Base setting must match (/sonarr), and the same path goes into Ragnarr.

Common errors

  • 502 Bad Gateway - the proxy is up but can't reach the backend; check the upstream address and port.
  • 404 on API calls only - the proxy routes / but not /api, or the URL Base doesn't match.
  • 401 with a valid key - an auth layer in front is intercepting the request (see above), or the key was regenerated. Re-copy it via the API keys guide.

When to use VPN instead

If exposing services publicly is not necessary, a VPN such as Tailscale is usually simpler and safer: nothing to expose, no certificates to renew, no auth middleware to tune. In that case, use the VPN hostname in Ragnarr.

Related guides

Back to all guides, or see the support FAQ for connection troubleshooting.