Built-in proxy

atreoAGENT includes a built-in HTTPS reverse proxy that routes requests to your apps based on the hostname. It handles TLS termination, ACL enforcement, and trusted-network bypass automatically.

How it works

When a request arrives at https://jellyfin.alice.atreo.link:

1. The proxy matches the first subdomain (jellyfin) against registered apps in the ACL.
2. It checks the source IP against the ACL to verify access permission.
3. If the source IP is in a trusted network, ACL checks are bypassed.
4. The request is forwarded to the app’s internal URL (e.g. http://localhost:8096).
5. The upstream’s response is streamed back to the requester.

The built-in proxy enforces the ACL itself and does not inject identity headers into the upstream request. The X-Auth-User, X-Auth-Member-ID, and X-Auth-Role headers are produced only by the separate forward-auth endpoint, for external proxies that delegate authentication to the agent.

Exposed-port apps

The proxy carries no traffic for exposed-port apps — clients connect to the port directly. For a port app with the HTTP or HTTPS protocol, though, the proxy answers the app’s subdomain with a 307 redirect to http(s)://<address>:<port>, where the address is the one the request arrived on: the WireGuard tunnel address for tunnel peers, the agent’s LAN address for requests from a trusted network. Tunnel peers only get the redirect for apps they’ve been granted — the same grant that opens the port in the per-peer firewall. TCP/UDP slugs stay unrouted (404 or 403, as for any unknown slug).

URL format

https://<app-slug>.<apps-hostname>

For example, if your subdomain is alice.atreo.link:

App	URL
Jellyfin	https://jellyfin.alice.atreo.link
Immich	https://immich.alice.atreo.link
Home Assistant	https://homeassistant.alice.atreo.link

If you’ve attached a custom domain like home.example.com, apps are also reachable at https://jellyfin.home.example.com. Both URLs serve the same app.

TLS certificates

The proxy automatically obtains wildcard TLS certificates from Let’s Encrypt using DNS-01 challenges via atreoLINK’s DNS relay. Certificates are:

• Issued for *.<apps-hostname> (and *.your-custom-domain.com if you’ve attached one).
• Stored in /var/lib/atreoagent/certs/.
• Automatically renewed daily (when within 30 days of expiration).

See TLS certificates for the full flow.

Trusted networks

Requests from trusted networks bypass ACL checks and are treated as admin access. No networks are trusted by default — you opt in to specific CIDRs in the config file.

You can customise trusted networks in the config file or read more on the Trusted networks page.

Disabling the built-in proxy

If you prefer to use your own reverse proxy (Caddy, Traefik, nginx), disable the built-in proxy:

proxy:
  enabled: false

Or with an environment variable:

PROXY_ENABLED=false

The forward-auth endpoint on port 9091 always runs regardless of this setting, so your external proxy can delegate authentication to it.