Routing and Trusted Proxies

Proxer routes public requests by host. This makes every route explicit and keeps unrelated clients isolated from each other.

---

Root and Subdomain Routes

Run the server with a public domain:

proxer server --listen 0.0.0.0:8080 --domain proxy.example.com --token dev-token

A client without --subdomain registers the root route:

proxer http 3000 --server ws://proxy.example.com:8080 --token dev-token

Requests for proxy.example.com go to that client.

A client with --subdomain demo registers demo.proxy.example.com:

proxer http 3000 --server ws://proxy.example.com:8080 --subdomain demo --token dev-token

Requests for unknown hosts return 404.

---

Local Testing

When you test without DNS, pass the host explicitly:

curl -H 'Host: demo.proxy.example.com' http://127.0.0.1:8080/

Direct localhost or IP-based requests are not automatically routed to a connected client.

---

Behind a Reverse Proxy

If Traefik, Caddy, NGINX, or another reverse proxy sits in front of Proxer, keep the original host header. For Traefik, this usually means leaving passHostHeader enabled.

Then tell Proxer which proxy addresses are trusted to provide forwarded headers:

proxer server \
  --listen 0.0.0.0:8080 \
  --domain proxy.example.com \
  --trusted-proxy loopback \
  --trusted-proxy private

The environment variable form is comma-separated:

PROXER_TRUSTED_PROXIES=loopback,private,10.42.0.0/16 proxer server --domain proxy.example.com

Trusted proxies may supply X-Forwarded-For, X-Real-IP, X-Forwarded-Host, and X-Forwarded-Proto. Untrusted peers are ignored for forwarded-header routing decisions.

---

Reserved Internal Paths

All Proxer internal endpoints live under /__proxer__/:

/__proxer__/control
/__proxer__/health/live
/__proxer__/health/ready

Do not route these paths to your local app. They are handled by the public server itself.