Caddy

Caddy supports forward auth natively with the forward_auth directive.

Caution

The agent ignores X-Forwarded-For / X-Forwarded-Host unless the caller’s source IP is listed in proxy.trusted_proxies. Add your Caddy host’s IP (e.g. 100.64.0.1/32 or the LAN IP it binds to) before forward auth will see real client tunnel IPs.

Example Caddyfile

jellyfin.alice.atreo.link {
    bind 100.64.0.1

    forward_auth 100.64.0.1:9091 {
        uri /auth
        header_up X-Forwarded-For {remote_host}
        header_up X-Forwarded-Host {host}
    }

    reverse_proxy localhost:8096
}

Wildcard configuration

To handle all apps with a single block:

*.alice.atreo.link {
    bind 100.64.0.1

    forward_auth 100.64.0.1:9091 {
        uri /auth
        header_up X-Forwarded-For {remote_host}
        header_up X-Forwarded-Host {host}
    }

    # Route to apps based on subdomain
    @jellyfin host jellyfin.alice.atreo.link
    handle @jellyfin {
        reverse_proxy localhost:8096
    }

    @immich host immich.alice.atreo.link
    handle @immich {
        reverse_proxy localhost:2283
    }
}

Tip

Bind to the WireGuard tunnel IP (100.64.0.1) so that only VPN clients can reach Caddy.

Passing auth headers to apps

Some apps can use the auth headers for single sign-on. Copy them from the forward auth response:

forward_auth 100.64.0.1:9091 {
    uri /auth
    header_up X-Forwarded-For {remote_host}
    header_up X-Forwarded-Host {host}
    copy_headers X-Auth-User X-Auth-Member-ID X-Auth-Role
}

TLS certificates

The agent obtains and renews wildcard TLS certificates automatically. Each served suffix has its own subdirectory under certs/:

./agent-data/certs/<your-subdomain>.atreo.link/fullchain.pem
./agent-data/certs/<your-subdomain>.atreo.link/privkey.pem

If you’ve attached a custom domain, its cert lives in a sibling subdirectory keyed on the parent zone (e.g. ./agent-data/certs/home.example.com/).

Bind-mount the agent’s certs/ directory into your Caddy container read-only so it can read them:

volumes:
  - /path/to/agent-data/certs:/atreo-certs:ro

(Use the absolute path if your Caddy compose file lives outside the agent’s directory.)

Then point Caddy at the files for each suffix you want it to serve:

*.alice.atreo.link {
    tls /atreo-certs/alice.atreo.link/fullchain.pem /atreo-certs/alice.atreo.link/privkey.pem
    bind 100.64.0.1
    # ...
}

They’re renewed by the agent in the background; Caddy picks up new files on the next request.