Yard Docs
Sign in
On this page

Hosting behind another proxy

Run Yard hosting on a machine where another proxy already holds ports 80 and 443, check it with the hosting doctor, and find the setup page for your proxy.

Updated November 1, 2026 · 11 min read

Some machines already run a reverse proxy (nginx, Caddy, Traefik, Coolify). It holds ports 80 and 443, so the proxy Yard starts for hosting cannot have them. Yard then runs behind the other proxy: that proxy keeps the ports and the certificates and sends your domain on to the runner.

This page holds the concepts. The steps for your proxy are on its own page:

Your setup Page
Coolify (coolify-proxy) Run a runner on Coolify
nginx Behind nginx
Caddy Behind Caddy
Traefik, not from Coolify Behind Traefik
By hand or systemd, no container Behind a proxy, by hand

Ask the hosting doctor

If something does not work, start with the doctor. It answers "why, and what do I change":

  • the deployment mode it found (runner on the host, in a container, Coolify, another proxy on the host, or nothing else on 80/443), with the holder named;
  • a checklist, each line ok, warn, fail or skipped with a one-line reason;
  • a proposed change as a diff.

Run it in the Hosting settings (Hosting doctor) or on the machine: yard hosting doctor (--json for the report as data).

It is read-only. It reads ports, containers and files, and asks the proxy container to fetch the runner's own address. It writes nothing, saves nothing and restarts nothing. A change is made only when you click Apply (or run yard hosting doctor --apply) on the proposal it showed, and the route is tested again after. If the situation changed since the report, Apply is refused and you run the check again. Checks it cannot make (no Docker socket, no permission to read the firewall) are listed as skipped with the reason. It never changes firewall rules, networks or the proxy's own configuration.

Modes

Mode What it means Typical fix
Runner on the host, directly Started by hand or by systemd. Listen on 127.0.0.1:8443; a proxy on the host reaches it there.
Runner in a container Plain docker run or compose. The proxy shares a network with it, or reaches the published port.
Coolify coolify-proxy holds 80/443. The proxy is in a container: use its network's gateway.
Proxy on the host nginx, Caddy or Traefik as a host process. Loopback is enough.
Standalone Nothing else on 80/443. Not behind a proxy; Yard's own proxy takes the ports.

The listen address

A proxy on the host reaches 127.0.0.1:8443. A proxy in a container cannot: 127.0.0.1 there is the container. It needs an address of the host that its network can reach, and that is the gateway of a network the proxy is on. It differs from machine to machine (172.17.0.1 on the default bridge, another one on Coolify's coolify network), so there is no default: the doctor reads the proxy container's networks and proposes the right one.

What happens by itself

When you turn hosting on and nobody chose a listen address, the runner checks who holds the port it wants (443, and 80 with HTTP-01). It looks at Docker (docker ps) first and then at the host (ss). If another container or process holds it, the runner:

  • listens on the first free port from 127.0.0.1:8443, never on 0.0.0.0, and writes the choice down in its data directory, so the address is the same after every restart (see Several runners on one server);
  • turns TLS off on its side and binds no port 80, so there is no HTTP-01;
  • refuses any Host outside your verified domains before it routes;
  • says so in the Hosting settings: Found coolify-proxy on the port, so this runner went behind it.

A listen address or TLS mode that you chose (in Yard, in RUNNER_HOSTING_LISTEN, or on the machine) is kept as it is. Detection never picks 0.0.0.0 on its own.

If the port was taken and you set the address yourself, the settings name the owner (Port 443 is held by coolify-proxy) and offer Run behind another proxy: one click sets the address the runner suggests (never 0.0.0.0) and TLS off.

Several runners on one server

Each runner behind the proxy needs its own listen port, and the route in your proxy points at exactly that port.

  • How the port is chosen. With no listen address set, a runner takes the first free port from 127.0.0.1:8443 (the second runner gets 8444, and so on) and stores it in its data directory (behind-listen.json). Keep that directory on a persistent volume.
  • It does not move. At a later start the runner keeps its port. If another process holds it now, hosting stops with an error that names the holder and the next free port. It does not pick another one by itself, because your proxy's file would then point at the wrong port. The Hosting settings offer the suggested address with one click (Use 127.0.0.1:8444); save, then copy the updated file.
  • A saved address that is taken gets the same error and suggestion.
  • One file per runner. The generated file is named after the runner: yard-<runner>.yaml (Coolify: /data/coolify/proxy/dynamic/), or yard-<runner>.conf for nginx. Two runners never overwrite each other's routes.
  • One wildcard domain, one runner. *.apps.example.com goes to exactly one runner. A second runner needs its own domain or subdomain zone, such as *.b.apps.example.com, with its own wildcard certificate.
  • Stale file. When the listen port changes, the settings show a banner that the file in your proxy is stale, with the updated YAML to copy.

Keep the address on loopback or a firewalled interface. The settings never suggest 0.0.0.0.

Put the config into the other proxy

With TLS: Behind another proxy, the Hosting settings show a ready config for each verified domain (Traefik, nginx, Caddy tabs, nothing secret in it). It sends *.apps.example.com and apps.example.com to the runner's listen address at the lowest priority and passes the Host header on.

Behind an existing proxy

Where the runner listens depends on what holds port 443 on the machine. The runner detects it and proposes the address; the "Run behind it" button in the runner's Hosting settings applies it.

What holds 443 Runner listens on Why
A container (Coolify's Traefik, a Caddy or nginx container) <bridge gateway>:8443, for example 172.17.0.1:8443 The proxy container reaches the host through the Docker bridge gateway, not through its own loopback. Falls back to 127.0.0.1:8443 when no gateway is found.
A process on the host (nginx, Caddy as a service) 127.0.0.1:8443 The proxy and the runner share the host's loopback.
Nothing 0.0.0.0:443 No other proxy: the runner serves visitors itself.

Which 502 is it?

  • Cloudflare's own 502 page (a Cloudflare-branded error): Cloudflare could not reach your origin, which is the other proxy. Check that it is running and that its router for the host exists.
  • Plain text from Yard, with one of these messages, means the other proxy did reach the runner:
    • The app did not answer. / The app refused the connection.: the app's container is stopped or not listening on its port.
    • This app's runner is not connected right now. / …not reachable right now.: the edge (tunnel mode) has no live connection to the runner.

Check the hop from the proxy

From inside the other proxy's container, send a request to the listen address with the app's host:

Shell
docker exec <proxy-container> curl -sS -H 'Host: app.example.com' http://172.17.0.1:8443/

A response from the app, or Yard's own sign-in redirect, means the runner is reachable. A connection error means the address is wrong or a firewall blocks the bridge subnet (Security).

Several apps on one port

Two apps that both listen on 5173 do not conflict. Each app runs in its own container and the runner routes by Host(), so one.example.com and two.example.com each reach their own app.

After you open an app from Yard, the runner redirects to the app's own https:// address, whatever address the other proxy used to reach the runner.

Wildcard certificates need DNS-01

Every app gets its own name under the domain. One certificate for *.apps.example.com covers them all, and Let's Encrypt only issues a wildcard through the DNS-01 challenge, so the proxy in front needs DNS-01 for your DNS provider (see your proxy's page). DNS records stay as on the Runner page: the _yard-verify TXT record, and apps.example.com and *.apps.example.com pointing at the server.

Test route

When the runner's TLS mode is HTTP-01, the settings remind you of this. HTTP-01 also needs port 80, which the other proxy holds, so it cannot be the runner's own mode here. Yard's own dns01 mode (Cloudflare) is unchanged: it is for a runner that holds the ports itself.

DNS records stay as on the Runner page: the _yard-verify TXT record, and apps.example.com and *.apps.example.com pointing at the server.

Check it

The Hosting doctor (see Ask the hosting doctor) is the first thing to run: it is read-only and names the cause and the fix.

Test route, in the Hosting settings, makes a request to a sample host (doctor-xxxxxx.apps.example.com) the way a visitor would, and says what is missing. On the machine, yard runner hosting doctor does the same and adds the upstream test: it asks the other proxy's container to open the runner's address.

What it says What it means What to do
*.apps.example.com does not resolve DNS has no wildcard record. Create it, pointing at the server.
Nothing answered on https Port 443 is closed, or the record points elsewhere. Open 443 to the proxy; check the record.
certificate that does not cover *.apps.example.com No wildcard certificate. Issue it with DNS-01.
no router … The proxy has no route for the host. Load the route file; check the entrypoint name.
could not reach the runner (HTTP 502/503/504) The route matched, but the proxy cannot reach the listen address. Run the hosting doctor: it names the proxy's network and the address to use.
answered … but not as this runner Another route or site takes the name. Give Yard's route a rule that matches, or remove the other.

"No available server"

Traefik answers no available server (or 404 page not found) when no router matched the host. The runner never saw the request. Check, in this order:

  1. The file is loaded: it is in Traefik's dynamic directory (Coolify: Proxy → Dynamic Configurations), and the proxy's log shows no error for it. Choose Restart Proxy if Traefik did not pick it up.
  2. The router's entryPoints names an entrypoint that exists (https on Coolify).
  3. The rule matches the host you opened: the domain is the verified one.
  4. No router with a higher priority claims the name. Yard's router has priority 1 on purpose.

Test route and yard runner hosting doctor run these checks for a sample host. The provider-specific steps for Coolify are on Run a runner on Coolify.

Names

Browsers warn about "lookalike" addresses, and api-useyard-app.apps.example.com reads like the domain useyard.app. Hosted names never end in a TLD-like word:

  • a name with a dot (useyard.app) loses its dots and TLD tail, and gets a short stable id (useyard-3k9x2p), so useyard.app and useyard.io stay apart;
  • a name that is already dashed (useyard-app) loses a trailing app, io, com, dev… and gets the same id;
  • every other name keeps its label.

The workspace and project name fields warn when a name looks like a domain.

Chrome's Did you mean …? warning appears because app hostnames are <app>-<workspace>.<domain>. A workspace named like a domain, such as useyard.app, gives api-useyard-app, which reads like it. To avoid it, rename the workspace slug or the app so it carries no domain-like ending.

An app that already runs under a lookalike address keeps it: changing it would silently break the old link. The Apps page marks such an app and offers Rename. The new address is shown first, and the app restarts under it; the old address stops working.

Security

  • The runner listens on 127.0.0.1 by default, and only loopback or private addresses are accepted for the generated config. The doctor warns when the upstream is 0.0.0.0 or a public address.
  • The runner's proxy accepts only hosts under your verified domains in this mode; any other Host gets a 404 from the proxy before any routing.
  • The config contains no token and no secret. Yard never writes one into it.
  • Traefik's file provider is trusted: whoever can write a file in the dynamic directory can route any host to any service. Keep that directory writable by root only.
  • Firewall. Only the other proxy should reach the upstream port. When the runner listens on a gateway address, allow that network's subnet and deny the rest (ufw deny 8443, then ufw allow from <subnet> to any port 8443). Docker bypasses ufw for published ports: put the rule in the DOCKER-USER chain. A listener on 127.0.0.1 needs no rule. The doctor only reads these rules; it never changes them.
Was this page useful?
Edit this page