Reverse proxies and remote access

How to reach your stack from outside the house - reverse proxies, base paths, tunnels, VPNs, and the login gates that quietly break API access.

Kochab talks straight to your servers. Nothing is relayed through us, so whatever address you give Kochab has to be an address your phone can actually reach.

At home that is usually the LAN address. Away from home it is whatever you already use to reach your stack: a reverse proxy, a tunnel, or a VPN. All of them work. This guide covers the setup details that are easy to get wrong.

Pick the shape you already run

You do not need a new setup for Kochab. Use the one you have.

A subdomain per service

The most common shape, and the simplest.

sonarr.example.com  ->  192.168.1.10:8989
radarr.example.com  ->  192.168.1.10:7878

In Kochab, enter https://sonarr.example.com as the address. Nothing else to configure. Leave the service’s own base path empty.

One hostname with a path per service

media.example.com/sonarr  ->  192.168.1.10:8989
media.example.com/music   ->  192.168.1.10:8686

This one has a requirement people miss: the service itself must know its base path. In Sonarr, Radarr, Lidarr and Prowlarr that is Settings > General > Host > URL Base. Set it there, restart the service, and configure your proxy to pass the prefix through rather than stripping it.

Then give Kochab the full address including the path:

https://media.example.com/music

Not https://media.example.com. The base path is part of the address.

A useful detail: your path does not have to match the service name. If Lidarr’s URL Base is /music, then /music is the address, and /lidarr will not work.

Per-proxy walkthroughs, with a minimal config for both shapes above: Caddy, Traefik, and nginx or SWAG.

A tunnel

Cloudflare Tunnel and similar products give you a public hostname without forwarding any ports. This is often the easiest option when your router cannot forward ports at all - behind CGNAT, double NAT, or a VPN with a killswitch.

The tunnel hostname behaves like any other address. Enter it in Kochab as-is. See Remote access with Cloudflare Tunnel and Access for a minimal tunnel config and how Cloudflare Access’s service tokens plug into Kochab.

A VPN

WireGuard, Tailscale and similar put your phone on your network. With a VPN connected, use your ordinary LAN addresses in Kochab - the same ones that work at home. That is the whole point, and it means no extra configuration.

If you use Tailscale with subnet routing on your router, your LAN addresses work from anywhere with no changes. See Remote access with Tailscale for that setup and the per-device alternative.

Certificates

If your proxy has a real certificate - Let’s Encrypt, or one issued by your tunnel provider - Kochab validates it and there is nothing to do.

If you use a self-signed certificate, see Certificate trust. Kochab will ask before trusting it, and will keep checking that the same certificate is still there.

Reverse proxies are the easiest way to get a real certificate on a home service, including one that has no HTTPS of its own. If your router cannot accept inbound connections on port 80, most proxies can still issue a certificate using a DNS challenge instead.

Login gates: the one that breaks things quietly

If you put Authelia, Authentik, Cloudflare Access or a similar single sign-on layer in front of a service, it intercepts every request - including Kochab’s.

Those gates are designed for browsers. When Kochab asks for data, the gate answers with a redirect to its login page instead of the data. Kochab is sending the correct API key, and the service behind the gate is perfectly healthy, but the reply never reaches it.

You will see the service fail to connect, or fail to load data, even though it works fine in a browser where you are already signed in.

The fix: let the API through

Add a rule to your gate that skips authentication for the API path, and keep the gate on everything else. The web interface stays protected; only the API path is exempt.

In Authelia, that is a bypass rule ahead of your normal rule:

access_control:
  default_policy: deny
  rules:
    - domain: 'sonarr.example.com'
      resources:
        - '^/api/.*$'
      policy: bypass
    - domain: 'sonarr.example.com'
      policy: one_factor

Authentik and Cloudflare Access have the same concept under different names - an unauthenticated path, or a bypass policy. Cloudflare Access and Pangolin are also the two gates Kochab can authenticate against directly with a service token, without a bypass rule at all - see Remote access with Cloudflare Tunnel and Access.

This is safe as long as the service’s own authentication is still on. The API path is not unprotected; it still requires the API key, which is what Kochab sends. You are removing a second lock from the door the app uses, not removing the lock.

If you would rather not exempt the path, the alternative is to keep that service off the gate entirely and reach it over a VPN instead.

When something is not working

If a configured service stops connecting, work through this checklist in order.

  1. Try the address in a browser, on the same network the phone is using. If the browser cannot reach it, the phone will not either.
  2. Check the base path. If the service has a URL Base set, the address in Kochab must include it.
  3. Check for a login gate. If the browser shows a sign-in page that is not the service’s own, that gate is also intercepting Kochab. See above.
  4. Check the certificate. A certificate that changed - a renewal, or a new proxy - will prompt in Kochab before it is trusted again.
  5. Check the API key. A key copied with a trailing space is a surprisingly common cause.

For the full connection-test checklist, see Why won’t Kochab connect to my service? If the service loads fine in a browser but Kochab still calls it offline, see It works in a browser but Kochab says it’s offline - a passing browser test and a passing Kochab test are not the same test.

Home and away

Kochab can hold two addresses per service: one for home and one for outside. It picks based on which network you are on, and falls back to the other if the first does not answer.

You do not have to fill in both. If a single address works everywhere - a VPN, or a hostname that resolves correctly on both sides - use just that one.

If your proxy or tunnel hostname is reachable only from outside your home network, add it under Advanced > External address rather than replacing the primary one, so Kochab keeps using the faster LAN address at home.