Yard Docs
Sign in
On this page

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.

Updated November 1, 2026 · 9 min read

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

  1. In Coolify, add a resource to a project and choose Docker Compose Empty.
  2. Paste the compose file from Yard. The API also serves it at https://api.useyard.app/runner-compose.yml.
  3. Under Environment Variables, set RUNNER_API_URL and RUNNER_TOKEN to the values Yard showed. Leave RUNNER_DATA_DIR unset, as explained in Docker Compose.
  4. Do not add a domain to the resource. The runner opens no web port, and it connects out to Yard.
  5. 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:

  1. Set the Listen address to 127.0.0.1:8443 (or the bridge address from step 5), or set RUNNER_HOSTING_LISTEN on the resource (see Setting the address on the machine instead).
  2. Set TLS to Behind another proxy (off).
  3. 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.

  1. Turn on Free subdomain on yrd.sh and pick Tunnel (no open port).
  2. 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:

  1. Add the _yard-verify TXT record shown there, then choose Verify.
  2. Point apps.example.com and *.apps.example.com at the server: an A (and AAAA) record to its IP address, or a CNAME to 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

  1. In Coolify, open Servers, choose your server, then Proxy, then Dynamic Configurations.

  2. Choose Add.

  3. Set the file name to yard-<runner>.yaml (the settings show the exact name; each runner has its own file).

  4. Paste the config from the Yard settings (Copy). It looks like this (the upstream URL is explained in step 5):

    YAML
    http:
      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"
    
    • HostRegexp matches every app under the domain.
    • entryPoints: https is Coolify's HTTPS entrypoint.
    • priority: 1 is the lowest, so the exact Host() routers Coolify writes for its own apps win.
    • certResolver names the resolver that issues the certificate (see step 6).
  5. Save. Coolify writes /data/coolify/proxy/dynamic/yard-<runner>.yaml on 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's letsencrypt resolver, 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:

Shell
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:

Code
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.1 or 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/dynamic on 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.

Was this page useful?
Edit this page