Run a runner on Coolify
Deploy a Yard runner as a Docker Compose resource on a Coolify server, and host apps on it next to Coolify's own proxy.
A server that runs Coolify can also be a Yard runner. The runner runs as a container that Coolify deploys. It starts each workspace in a container of its own through the server's Docker. This page covers deploying it and hosting apps on it. Coolify's proxy already holds ports 80 and 443, so hosting needs one extra setting.
Before you start
- A Coolify server running Linux, with at least the resources in Sizing. Workspaces and apps share the server with everything else Coolify runs.
- An organization in Yard where you are an admin, to register the runner.
1. Register the runner in Yard
On your organization's Runners page, choose Register runner, give it
a name and pick Docker Compose. Yard shows the compose file and two
values: RUNNER_API_URL and RUNNER_TOKEN. Keep the page open. The token is
shown only once.
2. Deploy it in Coolify
- In Coolify, add a resource to a project and choose Docker Compose Empty.
- Paste the compose file from Yard. The API also serves it at
https://api.useyard.app/runner-compose.yml. - Under Environment Variables, set
RUNNER_API_URLandRUNNER_TOKENto the values Yard showed. LeaveRUNNER_DATA_DIRunset, as explained in Docker Compose. - Do not add a domain to the resource. The runner opens no web port, and it connects out to Yard.
- Deploy. The runner shows as Online in Yard within a minute.
If Yard shows a red notice about the data directory, see When the data directory is wrong.
3. Turn on hosting
Open the runner's Settings in Yard and turn Hosting on.
Why it shows "Down" on Coolify
coolify-proxy (Traefik) owns ports 80 and 443 on the server. Yard's own
proxy wants 443, and port 80 as well with TLS Automatic (HTTP-01), so it
cannot start. The runner then shows the proxy as Down with port 80 is
taken by coolify-proxy (or 443). Hosting has to run behind Coolify's
proxy: Yard listens on a private address with TLS off, and Coolify's Traefik
terminates TLS and forwards your domain to it.
When nobody chose a listen address, the runner does this by itself: it listens
on the first free port from 127.0.0.1:8443 (and keeps it), turns TLS off and
takes no port 80. The settings say so
(Found coolify-proxy on the port, so this runner went behind it by
itself). If the settings still show Down, set it by hand:
- Set the Listen address to
127.0.0.1:8443(or the bridge address from step 5), or setRUNNER_HOSTING_LISTENon the resource (see Setting the address on the machine instead). - Set TLS to Behind another proxy (
off). - Save hosting.
Both are needed. A listen address alone leaves TLS on HTTP-01, which still asks for port 80. TLS: Automatic (HTTP-01) cannot work behind Coolify: the certificate challenge needs port 80, and Coolify's proxy holds it. Coolify's Traefik issues the certificates instead (see step 6).
Free subdomain and Tunnel (no open port) only affect the free
yrd.sh name. They do not move a custom domain behind Coolify: a custom
domain always needs the listen address and TLS settings above.
Then choose how visitors reach your apps.
Option A: a free subdomain (no DNS)
This is the simplest route. It needs no open port, no domain and no change in Coolify.
- Turn on Free subdomain on yrd.sh and pick Tunnel (no open port).
- Save hosting.
Apps get names such as web-x7k2.yrd.sh. Visitors reach them through the
runner's outbound tunnel. On the machine should read Proxy: Running and
Tunnel: Connected to the edge.
Option B: your own domain, served by Coolify's proxy
Use this option when apps should live under your own domain, such as
web-atlas.apps.example.com. Steps 1 to 7 below are all needed.
1. DNS records
The runner's Hosting settings list the records. In your DNS provider:
- Add the
_yard-verifyTXT record shown there, then choose Verify. - Point
apps.example.comand*.apps.example.comat the server: anA(andAAAA) record to its IP address, or aCNAMEto a name that resolves to it.
2. Hosting settings
Listen address and TLS as in Why it shows "Down". In the Behind another proxy block, the settings show the Coolify / Traefik config for your verified domain.
3. Add the wildcard route in Coolify
-
In Coolify, open Servers, choose your server, then Proxy, then Dynamic Configurations.
-
Choose Add.
-
Set the file name to
yard-<runner>.yaml(the settings show the exact name; each runner has its own file). -
Paste the config from the Yard settings (Copy). It looks like this (the upstream URL is explained in step 5):
YAMLhttp: routers: yard-apps-example-com: rule: 'HostRegexp(`^.+\.apps\.example\.com$`) || Host(`apps.example.com`)' priority: 1 entryPoints: - https service: yard-apps-example-com tls: certResolver: letsencrypt domains: - main: apps.example.com sans: - "*.apps.example.com" services: yard-apps-example-com: loadBalancer: passHostHeader: true servers: - url: "http://127.0.0.1:8443"HostRegexpmatches every app under the domain.entryPoints: httpsis Coolify's HTTPS entrypoint.priority: 1is the lowest, so the exactHost()routers Coolify writes for its own apps win.certResolvernames the resolver that issues the certificate (see step 6).
-
Save. Coolify writes
/data/coolify/proxy/dynamic/yard-<runner>.yamlon the server.
You can also create that file on the server yourself. Traefik watches the directory and reloads by itself, so nothing needs restarting. If the route does not show up, choose Restart Proxy on the server's Proxy page.
4. Redeploy the runner
If you set RUNNER_HOSTING_LISTEN on the resource, it must be a runtime
variable (not build-only), and saving it is not enough: redeploy the
resource so the container starts with it. A value set in Yard's Hosting
settings applies without a redeploy.
5. Make the upstream reachable
Traefik runs in a container. 127.0.0.1:8443 in the YAML is Traefik's own
loopback, not the server's, so the route returns an error even though the
runner is listening. Check how your proxy runs (docker inspect coolify-proxy
shows its network mode):
| Traefik runs … | Upstream URL in yard-<runner>.yaml |
Runner listens on |
|---|---|---|
On the host network (network_mode: host) |
http://127.0.0.1:8443 |
127.0.0.1:8443 |
| On a Docker bridge network (Coolify's default) | http://<bridge gateway>:8443, usually http://172.17.0.1:8443 |
The same gateway address, such as 172.17.0.1:8443 |
In the Behind another proxy block choose Proxy in a container (Docker
bridge). The settings then write the bridge gateway address into the config
and show it, so copy the file again and set that address as the Listen
address. This is what the product generates. host.docker.internal is not
generated: it only works if you added it to the proxy container yourself
(extra_hosts: host.docker.internal:host-gateway), and it resolves to the same
gateway, so the listen address must be that interface too.
Never listen on 0.0.0.0 or a public address. Close the port to the
internet in the server's firewall and allow only the bridge subnet (see
Firewall).
6. Certificates
Every app gets its own name, so the choice is:
- HTTP-01 certificates per host are enough when Coolify's resolver can issue them name by name and port 80 is open to the internet. Each new app name waits for its own certificate on the first request.
- A wildcard certificate (
*.apps.example.com) is needed to serve every app at once, with no wait. Let's Encrypt only issues it with DNS-01. Configure the DNS challenge on Coolify'sletsencryptresolver, as Wildcard certificates describes.
7. Test it
Choose Test route in the Hosting settings. It requests a sample host the way a visitor would and names what is missing: DNS, the router, the certificate or the upstream. The causes are in Check it.
More than one runner on the server
Every runner needs its own listen port (8443, 8444, …, chosen once and kept),
its own yard-<runner>.yaml file, and its own domain or subdomain zone:
one wildcard domain maps to exactly one runner. If the port of a runner
changes, the settings show that the Coolify file is stale and offer the
updated YAML. See Several runners on one
server.
When hosting does not start
Run the doctor inside the runner's container. In Coolify, open the resource's Terminal:
yard runner hosting doctor
The doctor prints the listen address in use and where it came from: the
runner's Hosting settings in Yard, RUNNER_HOSTING_LISTEN, the machine's
config.json, or the default. It names any container that holds the port.
Common causes:
| What you see | What to do |
|---|---|
port 443 is taken by coolify-proxy |
Choose Run behind another proxy (or leave the listen address empty so the runner picks it). |
| Test route says no available server or no router | No Traefik router matched the host: yard-<runner>.yaml is not loaded, its entrypoint is not https, or another router outranks it. See No available server; yard hosting doctor names the cause. |
| Test route says HTTP 502/503 | The router matched but Traefik cannot reach the runner. See step 5. |
| The browser warns Did you mean …? | The app name resembles a domain. See Names. |
port 8443 is taken by … |
Another resource or runner holds the port this runner chose earlier. The settings suggest the next free one: apply it, save, and copy the updated file. |
| The Listen address hint says the machine sets another one | The resource's environment has RUNNER_HOSTING_LISTEN, or someone ran yard runner hosting set --listen on the machine. The machine's value wins. Remove the variable and redeploy, or run yard runner hosting set --listen yard and restart the runner. |
| The hint says the runner is too old | Restart the resource. The runner fetches the newest build when it starts. Or set RUNNER_HOSTING_LISTEN=127.0.0.1:8443 in Coolify and redeploy. |
| Tunnel: Cannot reach the edge | The server must be able to make outgoing https connections to edge.yrd.sh. |
Setting the address on the machine instead
You can also set the address on the server, without Yard. Add it to the resource's environment in Coolify and redeploy:
RUNNER_HOSTING_LISTEN=127.0.0.1:8443
Make it a runtime variable, not build-only, and redeploy: saving it does not change the running container. The machine's value wins over the one set in Yard, and the Listen address field says so. To change the address from Yard again, remove the variable and redeploy.
Security
- Do not expose the listen port to the internet. Keep it on
127.0.0.1or on the Docker bridge address, with the port firewalled. The firewall rules are on Hosting behind Coolify or another proxy. - Apps default to team visibility: opening an app asks for a Yard sign-in, and only people who can see the project get in. Make a port public only when you mean to (see Apps).
- Only people who can write to
/data/coolify/proxy/dynamicon the server (or to Coolify's Proxy settings) can change routing. Treat that access as root.
Which address the runner listens on behind an existing proxy, and how to read a 502: Behind an existing proxy.