Reverse Proxy

Bring Your Own Proxy (BYOP) lets you run your own reverse proxy on your own infrastructure, bound exclusively to your EagleSafe ZTB tenant. Only your tenant's services route through it — no other tenant on the same management instance can use the same proxy domain.

Choose BYOP when you need full control over where traffic terminates, specific geographic placement, or your own TLS certificates under a domain you own.

Note: BYOP is currently in beta.

Shared and account clusters

A cluster is a group of one or more proxy instances that serve the same apex domain. EagleSafe ZTB supports two cluster types:

	Shared cluster	Account cluster (BYOP)
Who runs it	The platform operator	Your organization
Who can use it	All tenants on the management instance	Only your tenant
Apex domain	Provided by the platform	Your own domain (e.g. proxy.company.com)
TLS	Managed by the platform	Issued by your proxy (ACME or your own certs)
Geographic placement	Fixed by the platform	Wherever you deploy the container
Visible to other tenants	Yes	No
Deletable from dashboard	No	Yes (account owner only)

Clusters are listed under Reverse Proxy → Clusters. The Features column shows the capabilities reported by each cluster's connected proxies:

• Custom Ports — can bind arbitrary TCP/UDP ports for L4 services.
• CrowdSec — IP reputation filtering is active.
• Private — supports NetBird-Only Access (services reachable only from peers in your ZTB network). Requires the proxy to run in embedded peer mode with NB_PROXY_PRIVATE=true.

Prerequisites

• A server with a public IP that accepts inbound TCP on port 443 (and port 80 if using the http-01 ACME challenge).
• Docker installed on that server.
• A domain you control where you can create two DNS records: one A record for proxy.company.com and one CNAME wildcard for *.proxy.company.com.
• Network Admin role or higher in your ZTB tenant.

Setup walkthrough

Step 1 — Open the Clusters page

Go to Reverse Proxy → Clusters and click Setup Self-Hosted Cluster.

Step 2 — Choose your domain

Enter the apex domain for this proxy cluster (e.g. proxy.company.com). This becomes the suffix of every service URL hosted on it: {subdomain}.proxy.company.com. Click Continue.

Step 3 — Configure DNS records

At your DNS provider, create the following records:

Type	Name	Value
A	proxy.company.com	Your server's public IP
CNAME	*.proxy.company.com	proxy.company.com

Both records must resolve correctly before Let's Encrypt can issue TLS certificates. Click Continue.

Step 4 — Run the proxy

The wizard generates a ready-to-run docker run command with a one-time account-scoped token. Copy the entire command and store it securely — the token is shown only once.

docker run -d \
 -v /var/lib/certs:/certs \
 -e NB_PROXY_CERTIFICATE_DIRECTORY=/certs \
 -e NB_PROXY_ACME_CERTIFICATES=true \
 -e NB_PROXY_DOMAIN=proxy.company.com \
 -e NB_PROXY_LOG_LEVEL=info \
 -e NB_PROXY_TOKEN=<token> \
 -p 443:443 \
 netbirdio/reverse-proxy:latest

Run this command on your server. The container will connect to the management server, register as part of the proxy.company.com cluster, and begin requesting TLS certificates. Click Finish Setup.

Step 5 — Verify

Back on the Clusters page, the new account cluster appears with an Online badge once the proxy registers. You can also check health directly on the proxy host:

curl -s http://localhost:8080/healthz

A healthy response shows management_connected: true and initial_sync_complete: true.

Use the proxy for services

Once the cluster is online, your BYOP domain appears as a Cluster option in the domain picker when creating or editing a reverse proxy service. Configure the service as described in Reverse Proxy.

High availability

Run multiple proxy replicas with the same token and the same NB_PROXY_DOMAIN to form an HA cluster. Point both DNS records at all replica IPs (round-robin) or at a load balancer in front of them. For ACME, share NB_PROXY_CERTIFICATE_DIRECTORY across replicas (e.g. a network volume) to avoid hitting Let's Encrypt rate limits from concurrent certificate requests.

TLS configuration

The default mode uses ACME with the tls-alpn-01 challenge (port 443 only). Common alternatives:

Goal	Variable
Use Let's Encrypt via port 80	NB_PROXY_ACME_CHALLENGE_TYPE=http-01
Provide your own certificate and key	Unset NB_PROXY_ACME_CERTIFICATES, mount files into NB_PROXY_CERTIFICATE_DIRECTORY
Use a wildcard certificate	NB_PROXY_WILDCARD_CERT_DIR=/certs/wildcard

Manage tokens

One token can register multiple proxy replicas. Revoking a token disconnects all replicas registered with it within approximately 60 seconds. To revoke and regenerate: go to Reverse Proxy → Clusters, manage the token via the API, then restart the proxy container with the new token.

Troubleshooting

Symptom	Likely cause	Fix
Proxy logs Unauthenticated	Wrong or revoked token	Generate a new token and restart
cluster address already in use	Another tenant or proxy already owns this domain on the same management instance	Choose a different domain
Service stuck in certificate_pending	ACME challenge failing — ports blocked or DNS not propagated	Verify DNS records, ensure port 443 is reachable, switch to http-01 if needed
Service stuck in tunnel_not_created	Proxy cannot reach the target peer over WireGuard	Confirm the target peer is online and access policies allow the proxy to reach it
Proxy disconnects ~60s after start	Token revoked or expired	Generate a new token and restart

What's next?

Custom Domains

Reverse Proxy overview