Yard Docs
Sign in
On this page

Connect a runner

Turn a server, a cloud VM or your own computer into a runner that hosts your organization's workspaces.

Updated November 11, 2026 · 50 min read

A runner is the machine where workspaces live: their files, containers, repositories, terminals and agents. It can be a server, a cloud VM or the computer under your desk. A workspace is placed on one runner when it is created.

One runner process serves one organization or several: each organization it serves gets its own connection, its own data and its own workspaces (see Adding an organization to a runner). A runner connects out to Yard. It needs no open port, no public IP address and no certificate.

Single runner machine or multi runner machine

The setup steps in Yard (the Register runner dialog, a runner's setup and reconnect steps, and the new token after a rotation) have two tabs:

  • Single runner machine: the machine has no Yard runner yet. Install one for this organization with the installer, the CLI or the compose file. The rest of this page, from Requirements, is about this case.
  • Multi runner machine: the machine already runs a Yard runner for another organization. Nothing is installed: that runner serves this organization too, with yard runner add-org <org-id> <token> (or its compose variant). See Adding an organization to a runner.

Yard cannot tell which kind of machine you are on, so you pick the tab; the choice is remembered in your browser.

Requirements

System macOS, Linux (Ubuntu or Debian recommended) or Windows (experimental)
Docker Docker Desktop (macOS, Windows) or Docker Engine 24 or newer (Linux), running. On Linux the installer offers to install it. Not needed in direct mode.
Account Your own user account is enough. As root on Linux, each workspace also gets its own system user.
CPU and memory Depends on how many agents work at the same time: see Sizing
Disk Room for your repositories and their checkouts, plus about 4 GB for the workspace image
GPU (optional) An NVIDIA GPU with its driver and nvidia-container-toolkit (Linux)
Sysbox (optional) The Sysbox runtime (Linux), for Docker inside containers
KVM (optional) /dev/kvm (Linux on bare metal, or a VM with nested virtualisation), for an Android emulator in the containers

Every workspace runs in its own Docker container, so agents, terminals and code from repositories never run directly on the machine.

Sizing

CPU and memory: at least 2 CPUs and 4 GB of memory, for one agent at a time; 4 CPUs and 8 GB recommended. The runner, an idle workspace and monitors take about 1 CPU and 2 GB; each agent working at the same time needs about 1 CPU and 2 GB more, and the sizes below leave room for its builds and tests.

Size Agents at once CPUs Memory Disk Hetzner DigitalOcean Vultr
Minimum 1 2 4 GB 20 GB CX22 or CPX21 Basic 2 vCPU / 4 GB Regular 2 vCPU / 4 GB
Recommended for Solo 2 4 8 GB 40 GB CX32 or CPX31 Basic 4 vCPU / 8 GB Regular 4 vCPU / 8 GB
Team of 5 4 8 16 GB 80 GB CX42 or CPX41 Basic 8 vCPU / 16 GB Regular 8 vCPU / 16 GB
Team of 10 8 16 32 GB 160 GB CX52 or CPX51 CPU-Optimized 16 vCPU / 32 GB Regular 16 vCPU / 32 GB

Plus what your own builds and browser tests need. Monitors, cron checks and insights add little: one short process per run. Disk: about 4 GB for the workspace image plus your repositories. The example servers are named by size only; take the nearest your provider has.

Register a runner

Organization admins register runners:

  1. Open the Runners page (All runners in the menu behind the runner's name in the workspace switcher) and choose Register runner. That menu also has Connect a runner, which opens the same dialog.
  2. Give it a name.
  3. Pick how to install it: macOS / Linux, Windows, Compose, or Installed (for a machine that already has the yard CLI).
  4. Follow the numbered steps the dialog shows for that platform. The first says what the machine needs (see Sizing); then Docker, the command, and for Compose the file and its variables, each with its own copy button.

A runner online on a machine below the minimum gets a warning on its row in the Runners page and in the workspace's health card ("This runner has 2 GB of memory; agents need at least 4 GB"). With Agents at once set higher than its memory fits, the setting says how many it fits. Nothing is blocked; the runner's load gate still protects the machine.

The command carries a setup token (yrs_…). It works only until the machine first connects: Yard then hands the runner a token of its own over that connection, saves it on the machine and the setup token stops working. Until a machine has connected, the runner's Settings open on these setup steps again, setup token included, so closing the dialog loses nothing. The last step follows the machine: it says Token checked as soon as the installer has checked the token, and Connected once the runner is online and new workspaces can use it. When the token was checked but the runner is still not online after ten minutes, it says what to run on the machine.

Install and connect

macOS and Linux

Shell
curl -fsSL https://api.useyard.app/install.sh | sh -s -- --token <token>

Run it as the account that will run the runner, in a real login (SSH, or su - <user> with the dash). That account must be able to run docker version. See Running as a dedicated account.

The script installs the yard CLI (see Install the yard CLI). When its folder is not on your PATH it asks whether to add it to your shell's profile (Enter adds it, once; --yes adds it without asking). When another, older yard comes first on your PATH it names it and how to remove it. Then it runs yard runner up, the guided setup. It goes through numbered steps, asks only for what is missing, and marks each step done or failed:

Code
Downloading yard 0.12.2 for linux-x64…
Installed /usr/local/bin/yard
Setting up a Yard runner · yard 0.12.2 (/usr/local/bin/yard) · root@server
  1. Data directory ✓ /var/lib/yard
  2. Token          ✓ checked and saved (runner rnr_…)
  3. Mode           ✓ docker: one container per workspace
  4. Docker         ✓ docker 29.0.1 (installed just now)
  5. Box image      ✓ yard-box:latest built
  6. Service        ✓ yard-runner installed, enabled at boot, started
  7. Online         … waiting for the runner to connect
  7. Online         ✓ connected to https://api.useyard.app as rnr_…
Setup complete. This runner shows as online under Yard → Runners.

Every question says what Enter does, for example Run as a background service, started at boot? (Enter for yes, n for no).

  1. Data directory. Where the runner keeps its settings and workspaces: /var/lib/yard as root on Linux, ~/.yard otherwise. It is not asked for unless that cannot be used; give --data-dir for another one. A directory with other files in it is refused; the bin folder the install script puts yard in (~/.yard/bin) does not count. If this machine already has a runner, see Several runners on one machine.
  2. Token. Checked with Yard and saved straight away, before anything that can fail. A token Yard refuses fails here, in seconds. Without --token the setup asks for it (what you type is not shown).
  3. Mode. Asked once (press Enter for Docker; see Runner modes).
  4. Docker. When Docker is missing on Linux and the script runs as root, it asks whether to install Docker Engine with Docker's own install script (get.docker.com). Press Enter to install it; the setup then enables and starts it and carries on. A stopped Docker is offered systemctl enable --now docker. As an ordinary user it prints the commands to run instead, for your account by name, "as root" or with sudo when sudo works for you. It tells apart a Docker that is not installed, one whose daemon is not running, a docker that could not be started at all, an account not in the docker group, and one added to the group after this shell started (log in again: su - <user>, a new SSH session or newgrp docker). Anything else is shown as Docker said it. On macOS and Windows, install Docker Desktop first. When it is installed but not running, the setup says so and offers to start it, then waits up to two minutes for it to answer.
  5. Box image. Builds the workspace image (a few minutes the first time).
  6. Service. Installs the background service, enables it at login or boot, and starts it. For an ordinary account on Linux it first turns on lingering (so the service runs without a login) and finds the account's systemd user session, also from a shell that came from su.
  7. Online. Waits until the runner is connected to Yard. Only then does it print Setup complete. If the service stops (for example because the token was refused) or does not connect within 90 seconds, it prints why, the runner's last log lines and what to run, and exits with an error. --verbose shows the log lines as they come. Ctrl-C while it waits stops only the waiting: the service keeps running.

Carrying on. When a step fails, the last line starts with Next: and says what to do, which usually ends in yard runner up. The token, mode and data directory are saved, so it is not asked for again and the steps already done are quick.

Script options, after sh -s --:

Option What it does
--token <token> The runner's token (or set YARD_TOKEN).
--api <url> Connect to another API than the one the script came from.
--dir <path> Where to put yard (default: ~/.yard/bin, or /usr/local/bin as root).
--data-dir <path> Where the runner keeps its data (or set YARD_DATA_DIR). A new or empty directory, or one a runner already uses.
--mode docker or --mode direct Choose the mode up front instead of being asked.
--home-root <folder> Where workspaces are kept (default: <data dir>/home). Change it later with yard runner config set home-root <folder>.
--install-docker Linux, as root: install Docker Engine without asking when it is missing. For unattended installs.
--no-install-docker Never offer to install Docker.
--yes Take the defaults without asking: add yard's folder to PATH in your shell's profile, and with --mode direct skip the confirmation.
--no-service Run the runner in this terminal instead of installing a service.
--wait <seconds> How long to wait for the runner to come online (default 90).
--replace Another runner uses the data directory: move it to this token (see below).
--insecure Allow a plain http:// API address.

Without a terminal to ask on (a script, CI) and without --install-docker, a missing Docker is not installed: the setup stops and says so. The script exits with the setup's exit code, so a failed setup fails curl … | sh.

Running the script again with the same token updates yard and restarts the runner; this holds for the setup token too after it has been swapped, since the machine recognises it as its own runner. With another token on a machine that already has a runner, it asks what to do; see Adding an organization to a runner. It never takes over a runner without asking.

Windows

In PowerShell, with Docker Desktop running:

Shell
$env:YARD_TOKEN = "<token>"; irm https://api.useyard.app/install.ps1 | iex

Workspaces run as Linux containers under Docker Desktop. Windows support is experimental.

In Git Bash (or MSYS2 or Cygwin) the macOS and Linux one-liner works too: curl -fsSL https://api.useyard.app/install.sh | sh -s -- --token <token> sees that it runs on Windows and hands over to PowerShell's installer, with the token and --data-dir. When powershell.exe is not found, it prints the PowerShell line to run instead.

When the install folder is not on your Path yet, the setup prints an ACTION NEEDED block with the two PowerShell lines that add it: run them, or yard is only found in that window.

Windows without Docker: direct mode

To work on something that needs Windows itself (a game, a desktop app), the runner can run workspaces directly on the PC: agents are ordinary Windows programs, the windows they open appear on your screen, and yard-shot screen takes pictures of the desktop or of one window.

It is not containerized. Agents run as your Windows account: they can read and change your files, use your network and devices, see your screen and send it keys and clicks, and reuse sign-ins they find. Workspaces are not separated from each other and have no memory or CPU limits. The setup says all of this and asks you to type direct. Use it on a PC where you are the only person with workspaces.

Install these first, then open a new PowerShell window so it finds them:

What How
Git for Windows winget install --id Git.Git -e, or git-scm.com. Keep the default folder: the runner uses its bash, sh and Unix tools.
Python 3 winget install --id Python.Python.3.12 -e, or python.org. The python3 that opens the Microsoft Store does not count.
An agent CLI Claude Code: irm https://claude.ai/install.ps1 | iex; Codex: npm install -g @openai/codex

Then run the installer and answer 2 at the mode question (or run yard runner up --mode direct afterwards). The setup finds Git Bash and Python where they are installed (they need not be on Path), installs pywinpty for terminals, asks for a folder for workspaces (Enter for %USERPROFILE%\yard; keep it short, Windows paths stop at 260 characters), and registers a Scheduled Task that starts the runner when you sign in. It runs in your desktop session without a window of its own (on Windows 10 before version 1809 it has a console window, and closing it stops the runner); yard runner service logs shows its output. It is not a Windows service on purpose: a service has no desktop, so games could not open windows and screenshots would be empty. --no-service runs it in the PowerShell window instead.

Git LFS. Repositories that keep large files in Git LFS need git-lfs where the runner runs git: tick Git LFS when installing Git for Windows, or run winget install --id GitHub.GitLFS -e. The runner also finds a git-lfs that is not on its own Path (installed after it started: it reads the Path from the registry, and looks in Git for Windows' mingw64\bin and in Program Files\Git LFS), so no restart or sign-out is needed. An MSYS2 git-lfs (C:\msys64\…) is not used: the runner's Git for Windows cannot run it. A project's worktree is checked out first and its LFS files are downloaded after, with the repository's GitHub access; when that fails the project still sets up, with pointer files and a note in its chat that says why.

Not available in direct mode on Windows: hosted apps (they need Docker), and per-workspace limits and usage numbers. A workspace's ports and its agents' background work are found by process: a program counts as the workspace's when it was started from there.

A machine that already has yard

Shell
yard runner up --token <token>

Adding an organization to a runner

A runner process serves as many organizations as you give it. When the machine already runs a runner, you do not install another one: you add the organization to the one that is there.

Register the runner in the new organization as usual, so that you get its setup token, and pick the Multi runner machine tab in the dialog. It shows the command to copy, with the real organization id and token in it (under CLI; Docker Compose shows the compose variant):

Shell
yard runner add-org <org-id> <token>

The running runner opens a session for the organization within a few seconds. There is no new service and no restart. Without a running service, the session opens when the runner starts. For a runner in a container, run it through compose, in the folder of its compose file:

Shell
docker compose -f runner-compose.yml run --rm runner add-org <org-id> <token>

To stop serving an organization:

Shell
yard runner remove-org <org-id>

Its session closes within a few seconds and its data stays: nothing is deleted. Add it again later and its workspaces are there.

Running add-org again replaces the token

add-org for an organization that is already added does not fail: it asks Yard about the new token and the one saved on the machine, then:

  • the same token (or one it already replaced): nothing changes;
  • a new token of the same runner (rotated in Yard): the token is updated;
  • the saved token's runner was removed in Yard, or its token no longer works: the new token replaces it, and the organization's directory (orgs/<org-id>) is released so the new runner can claim it;
  • the saved token still works for another runner: it asks first, and --replace answers yes. Without a terminal nothing changes and it prints the command with --replace;
  • a token Yard refuses, or Yard cannot be reached: nothing changes.

When an organization's session fails

When Yard refuses an organization's session for good (its runner was removed, or its directory belongs to another runner), the runner keeps serving the other organizations and saves the reason. It does not try again until the token or the directory changes. yard runner status lists every organization with its state (connected, connecting, failed and why):

Shell
yard runner status

To recover, register a new runner for the organization in Yard and run yard runner add-org <org-id> <token> with its token (see above). To let the next runner of the organization take its directory over without a new token:

Shell
yard runner adopt-data-dir --org <org-id> --yes

Where an organization's data lives. Under the runner's data directory, in orgs/<org-id>/: its workspace state, home directories, archive, trash and vault key. Its boxes and app containers carry the label yard.org=<org-id>. The runner's own identity, config.json, the lock and hosting (the proxy and its listen address) stay at the top of the data directory and are shared by every organization of that runner. Each organization still has its own vault and its own quotas.

Not a hard security boundary. The organizations of one runner share one Docker daemon, one proxy and one listen address; they are kept apart by labels, name prefixes and separate vaults. That suits organizations you run yourself. For tenants that must not trust each other, use a runner of its own for each (see the next section).

When the install script finds a runner

With another token on a machine that already has a runner, the install script (or yard runner up) says so and asks:

Code
This machine already has a runner in /var/lib/yard
  runner rnr_…  ·  connected to https://api.useyard.app  ·  service yard-runner (running)
What should this token do?
  1) Add this org (org_…) to the existing runner: no new service, no restart (recommended)
  2) Add a second runner next to it, in /var/lib/yard/runner-2 (advanced)
  3) Replace that runner: move its service to this token (its workspaces stay in /var/lib/yard)
Choose 1, 2 or 3 [1]:
  • 1 (the default, and what --yes picks) is the same as yard runner add-org with this token and the organization the token belongs to.
  • 2 is the advanced option below.
  • 3 moves the existing service to the new token. The workspaces in that directory belong to the old runner: the setup says whether it is running on this machine and offers to stop it and release the directory, then carries on with the new token. Only do this when the old runner is gone for good. Said no to, it prints the commands to do it yourself (yard runner service stop, yard runner adopt-data-dir --yes, then yard runner up --token <token> --replace), joined with ; on Windows so they run in PowerShell 5.

Without a terminal to ask on, nothing is changed and the commands for all three are printed, add-org first. The same happens when the token's organization cannot be resolved (a personal runner's token has none): add it by hand with yard runner add-org <org-id> <token>.

Several runners on one machine (advanced)

Most machines need one runner, however many organizations it serves. Run more only when you want a runner to be separate from the first: its own data directory, its own service, its own Docker labels and its own update and restart schedule, for example for an organization whose workspaces must not share a runner with the others.

Each runner has its own data directory and its own background service. To choose it up front, answer 2 in the prompt above, or give the new runner its own directory:

Shell
curl -fsSL https://api.useyard.app/install.sh | sh -s -- --token <token> --data-dir /var/lib/yard/org-b

Answering 2 leaves the first runner and its service as they are, and sets up the new one in the first free runner-N folder, with a service of its own.

Services. The runner in the default data directory keeps the service name every install had: yard-runner (systemd) or app.useyard.runner (launchd). Every other data directory gets its own, named after its folder: /var/lib/yard/runner-2 runs as yard-runner-runner-2 / app.useyard.runner.runner-2.

Managing each one. Every yard runner command takes --data-dir to pick the runner; without it, it means the one in the default directory:

Shell
yard runner list                                         # every runner on this machine, its data directory and state
yard runner service status --data-dir /var/lib/yard/runner-2
yard runner service logs -f --data-dir /var/lib/yard/runner-2
yard runner config show --data-dir /var/lib/yard/runner-2

yard update updates yard once and restarts every runner service on the machine.

Hosting is per runner process: each runner starts its own proxy, so two runners that host apps cannot both listen on port 443 of the machine. Give one a different address (yard runner hosting set --listen …).

Moving to the per-org layout

A runner that ran before this layout kept one organization's state at the top of its data directory. The first start of a version with the per-org layout moves it, once, by itself:

  • The state (state/, home/, archive/, trash/, vault.key) moves to <data-dir>/orgs/default/, after it was copied to <data-dir>/backup-pre-orgs/. default is the first organization's own name.
  • The runner's own boxes are removed once. Their home directories moved, so they are made again the next time a workspace is used. Workspace files are not touched.
  • Hosting, the proxy, config.json, the lock and the runner id stay at the top.

Nothing else is needed: the runner connects as before, and add-org is available from then on.

Rollback. If you need the previous version back:

Shell
yard runner service stop
yard runner org-layout rollback

Then start the previous version of the runner (with a service: install it again or pin the previous build, then yard runner service start). The rollback restores the single-organization layout from backup-pre-orgs/; it refuses to run while a runner is using the data directory. Organizations that were added with add-org are not served by the previous version, and any change made to the first organization's state after the move is lost, since the backup was taken at the move.

yard runner up

yard runner up is the guided setup above. Run it again at any time: it uses what was saved and only does what is still missing.

Flag What it does
--token <token> Connect the runner with this token. Without it, the saved one is used, or the setup asks for it.
--data-dir <path> The runner's data directory (see above).
--service / --no-service Install the background service, or run in this terminal. Without either, a terminal is asked (Enter: the service); a run without a terminal stays in the foreground, as in a container.
--mode docker or --mode direct How workspaces run. Asked the first time when not given; saved for later.
--install-docker / --no-install-docker Install Docker Engine without asking (Linux, root), or never offer it.
--wait <seconds> How long the Online step waits (default 90).
--replace Move the runner in this data directory to the new token.
--yes Take the defaults; with --mode direct, skip the confirmation.
--rebuild Build the workspace image again.
--no-gpu Do not build the GPU image, even when the machine has a GPU.
--insecure Allow a plain http:// API address. The token would travel unencrypted.

Without the service the runner runs in the terminal until you press Ctrl-C; Setup complete. is printed once it connects.

A data directory is used by one runner process at a time. If one started in a terminal is already running there, up says so, with its process id and how to see or stop it, and does nothing.

Runner modes

  • Docker (default, recommended): every workspace runs in its own container, isolated from the machine.
  • Direct (discouraged): no containers. Agents, terminals and everything a repository runs become ordinary processes on the machine, with access to its network, devices and, outside root on Linux, your own files. Use it only on a machine that cannot run Docker. The runner explains what it gives up and asks you to type direct to confirm. Direct mode needs git, python3, bash and tar on the machine, and the agent CLIs you want to use (claude, codex, cursor-agent).

yard runner config set mode docker switches a direct runner back to Docker.

Running as a service

On macOS (launchd) and Linux (systemd), the runner can run in the background and start again after a crash, at login or at boot. yard runner up --service and the install script set this up; to do it yourself:

Shell
yard runner service install
Command What it does
yard runner service install Install the service, start it and wait until the runner is online. Refused while the runner is not enrolled.
yard runner service uninstall Remove the service.
yard runner service status Whether it is installed and running, since when, whether it is connected to Yard, and its last log lines.
yard runner service start Start it, and wait until the runner is online.
yard runner service stop Stop it. It starts again at the next login or boot.
yard runner service restart Restart it, and wait until the runner is online.
yard runner service logs Show its log. -f follows it; -n <lines> sets how many lines (default 50). Without a service it shows the log of a runner started with yard runner start.

install, start and restart wait, and fail with the reason and the runner's last log lines when it does not come online; --no-wait returns at once. Every command takes --data-dir to pick the runner (see Several runners on one machine).

service status takes --json for the same as JSON, and -n <lines> for how many log lines to show (default 10). It exits with 0 when the service runs and 3 when it does not.

As root on Linux the service is system-wide; otherwise it belongs to your user. On macOS the runner keeps the Mac from going to sleep while idle, because a sleeping Mac takes its workspaces offline. Closing the lid still puts it to sleep; the runner reconnects when it wakes.

Running as a dedicated account

On a Linux server a runner can run as an account of its own instead of root. As root, once:

Shell
useradd -m runner-nps                 # the account
usermod -aG docker runner-nps         # it may use Docker
loginctl enable-linger runner-nps     # its services run from boot, with no login

Then log in as that account over SSH, with machinectl shell runner-nps@, or with su - runner-nps (with the dash), check that id lists docker and docker version shows a server version, and run the install command there.

A plain su runner-nps (without the dash) keeps root's directory and PATH. The setup works around the directory, and warns when an older yard comes first on PATH. A shell from su also has no systemd user session; the setup finds the account's session by itself once lingering is on. When it is off and the account may not turn it on, the setup says so before it asks for the token, and its last line is the command root runs: loginctl enable-linger runner-nps.

To run the runner in a terminal instead, without a service:

Shell
yard runner start

It logs to the terminal and to <data-dir>/logs/runner.log (started again past 10 MB), so yard runner service logs has something to show either way.

When a project does not set up

A failed setup says which step failed and quotes git's own last line. The project's Details under the message show the git command, the folder it ran in, how it ended and how long it took, git's last 60 lines, and in direct mode the git, git-lfs, PATH and HOME it had; Copy copies them. The runner logs the same as a container_setup_failed line. Tokens are never shown.

For more, start the runner with --debug (or set YARD_DEBUG=git, or yard runner config set debug git): every git command is logged with its timing and exit code, together with git's and git-lfs's own trace.

Shell
yard runner start --debug

Change settings

yard runner config shows and changes a runner's settings without running the whole setup again. With --data-dir it addresses that runner.

Shell
yard runner config show
Code
data directory  /var/lib/yard                          (default)
api             https://api.useyard.app                (saved)
token           yrn_…9f2c, confirmed 2026-10-05        (saved)
runner          rnr_…
mode            docker                                 (saved)
debug           off                                    (default)
service         yard-runner (running, enabled at boot)

Each value says where it comes from: saved, the environment, or the default. The token is only shown by its first and last characters. --json prints the same for scripts.

Command What it does
yard runner config set token <token> Checks the new token with Yard first and saves it only when Yard accepts it; a refused token leaves the old one. Without a value it asks (hidden).
yard runner config set mode docker Checks Docker (and offers to install it, as in the setup), builds the workspace image, then switches.
yard runner config set mode direct Asks you to confirm, as the setup does (--yes skips it).
yard runner config set data-dir <path> Points the service at another data directory that already has a runner. Nothing is moved; the old service is removed. For a new directory, set a runner up there with yard runner up --data-dir <path>.
yard runner config set debug git Logs every git command with its timing and git's own trace (When a project does not set up). off turns it off. YARD_DEBUG wins.

After a change the service is restarted and followed until the runner is online. --no-restart only saves; without a service, the change applies at the next yard runner start. A mode change is refused while workspaces run on the runner. A setting that the runner's environment sets (RUNNER_TOKEN, RUNNER_MODE, RUNNER_API_URL, for example in a compose file) wins over the saved one: set says so and tells you to change it there.

Checking a runner

Shell
yard runner status

Shows where the runner's settings are, which API it is connected to, whether its token is confirmed (token saved, not confirmed yet until it first connects), the mode, whether it is running (and whether by the service or in a terminal), and whether a newer build exists.

Shell
yard runner doctor

Shows what this machine offers: the mode, whether the workspace image is there, whether the runner is connected to Yard, the GPU, whether Docker has the Sysbox runtime (sandboxedDocker), the direct-address settings, and hosting's listen address with any clash between the two. Use it when a runner does not behave as expected.

Shell
yard runner check
yard runner install docker      # or git, python, wsl

check lists what the computer has and lacks, one line each, and every problem names its error code and a guide (for example YRD-DOCKER-002 · https://useyard.app/docs/troubleshooting/docker-not-running). install installs one missing piece the usual way for the platform. A failed yard runner up ends with the same code and guide on its Next: line.

Docker inside containers

With Sysbox installed on a Linux runner, yard runner setup also builds the Docker sidecar image, and each workspace on the runner can turn on Docker inside containers in its settings, under Runner (workspace owners). Agents and terminals in that workspace's containers can then use docker and docker compose. They talk to a Docker daemon of the workspace's own, run in a sandboxed container next to them, never to the machine's Docker, and no container is ever privileged. A port a container publishes is reached at docker:<port>. Without Sysbox there is no switch: the Docker section says the runner has no Sysbox and names the runners the workspace could move to that have it. A Docker Compose runner gets it the same way: install Sysbox on the host, then docker compose -f runner-compose.yml up -d again so the runner sees the runtime and builds the sidecar image. Runners with it are marked "Docker" in the runner list. See the runner guide in the repository (the "Docker inside containers" section of docs/runner.md) for what the sandbox can touch.

Both print JSON.

Android emulator (KVM)

On a Linux machine with hardware virtualisation (/dev/kvm), the runner reports it (yard runner doctor shows "kvm": { "gid": … } under capabilities), and each workspace on it can turn on Android emulator (KVM) in its settings, under Runner (workspace owners). Its containers then get the device, and nothing else: no capability or privilege is added. Agents can run yard android setup and yard android start to open an Android emulator, and look at a React Native or Expo app's screens.

Which machines have it: a Linux server or PC on bare metal (with virtualisation on in its firmware), and cloud VMs only with nested virtualisation (for example Google Cloud with --enable-nested-virtualization, or AWS .metal instances). Docker Desktop on macOS and Windows does not pass it to containers. Without it there is no switch: the Android emulator section says the machine has none and names the runners the workspace could move to that have it. A Docker Compose runner finds the host's /dev/kvm through Docker, so it needs no change to its compose file.

Updating

A runner checks for a newer build when it starts and every few hours. When there is one, yard runner status and the Runners page say so. To update:

Shell
yard update

This downloads the newest build from the API the runner is connected to, checks it, replaces yard and restarts every runner service on the machine. yard update --check only says whether there is one.

You can also choose Update next to an online runner on the Runners page: organization admins for the organization's runners, and you for your own personal runners. If something is running on it (an agent turn, a terminal, work the agent left in the background), Yard first lists it: each project or workspace, what runs there, and for how long, with a link to its chat when there is one. Then you choose:

  • Update when idle (the default) waits for that work to end. The runner shows Updates when idle and installs the update once nothing runs on it. Cancel update next to it drops the wait.
  • Stop and update updates it now. The agent turns it stopped carry on by themselves once the runner is back, whatever the workspace's Carry on interrupted work when the runner is back setting says; terminals and background work are not started again.

A runner older than 0.30.0 can't wait, and one older than 0.26.0 can't say what is running: Yard says so and offers only Stop and update. Runners too old for the Update button need one yard update on the machine first.

Runners that cannot update themselves

Two kinds of runner are updated by hand. The Runners page shows the command for each, with Copy, instead of Update now:

  • Windows builds before 0.50.2 take themselves for a checkout and refuse yard update ("this runner runs from a checkout"). Run the installer again in PowerShell, without a token:

    Shell
    irm https://api.useyard.app/install.ps1 | iex
    

    It moves the running yard.exe aside, puts the new one in its place and restarts the runner's scheduled task. From then on yard update and the Update button work.

  • A runner run from a checkout of the repository (bun apps/runner/src/cli.ts …) has no executable to swap. yard update prints the checkout's folder and the commands that update it:

    Shell
    cd "<checkout>" && git pull --ff-only && bun install
    

    then restart the runner. yard update --pull runs them for you and restarts the runner's service; it refuses when the checkout has changes or the pull is not a fast-forward.

To have a runner install new builds by itself, between jobs, set RUNNER_AUTO_UPDATE=1 in its environment before installing the service.

Docker Compose

On a Linux server with Docker Engine, or a platform such as Coolify or Portainer, the runner can itself be a container. In Register runner, choose Docker Compose: copy the compose file and set the two variables shown, RUNNER_API_URL and RUNNER_TOKEN. Leave RUNNER_DATA_DIR unset. The API also serves the file at https://api.useyard.app/runner-compose.yml.

Shell
docker compose -f runner-compose.yml up -d

A server that already runs a compose runner takes another organization the same way as any runner: docker compose -f runner-compose.yml run --rm runner add-org <org-id> <token> (see Adding an organization to a runner).

The compose file also passes RUNNER_HOSTING_LISTEN through to the runner. Leave it as it is unless another proxy on the server holds port 443:

YAML
environment:
  RUNNER_DATA_DIR: ${RUNNER_DATA_DIR:-/var/lib/yard}
  # Where the runner's proxy (yard-proxy-<id>) listens. The default,
  # 127.0.0.1:8443, is reachable from the host only. Change it when a proxy
  # in a container (Coolify's Traefik) has to reach it: use the Docker
  # bridge address, such as 172.17.0.1:8443 (see "Behind Coolify or Traefik").
  RUNNER_HOSTING_LISTEN: '${RUNNER_HOSTING_LISTEN:-127.0.0.1:8443}'

Things to know:

  • Workspaces still get one container each. The runner starts them through the host's Docker socket, which is mounted into the runner's container only.
  • Workspace files live in /var/lib/yard on the host. That path must be the same inside and outside the container, and it is the only folder the file mounts.
  • RUNNER_DATA_DIR is optional. Unset, the runner uses /var/lib/yard. If you set it, it must be /var/lib/yard or a folder inside it, such as /var/lib/yard/runner-2. Anything else, for example /var/lib/yard-2, exists only inside the runner's container: Docker on the host cannot see it, and every workspace fails to start.
  • Restarting the container fetches the newest runner build, and the file sets RUNNER_AUTO_UPDATE=1, so it also updates itself between jobs.
  • The file mounts the host's /etc/machine-id, so a recreated container still counts as the same machine (see below).

When the compose file changes

Updating the runner replaces the runner build inside the container, not the compose file around it. The file carries its own version, RUNNER_COMPOSE_VERSION, and the runner reports it. When Yard serves a newer file than the one a runner was deployed from, the Runners page says so on that runner, for example New Docker Compose file: version 3, this runner was deployed from version 2, with a link to the new file. Files from before the variable existed count as version 1.

To move to the new file, copy it again from Register runner (or from /runner-compose.yml), keep your RUNNER_API_URL and RUNNER_TOKEN (and RUNNER_DATA_DIR if you set one), and redeploy. The notice goes away once the runner is back online. Do not edit RUNNER_COMPOSE_VERSION yourself.

When the data directory is wrong

At start the runner asks Docker how its own container's folders map to the host. When its data directory is not at the same path on both sides, it still comes online, but the Runners page shows a red notice on it (also in Register runner while you wait), new workspaces are refused at once with the same text, and its log has a data_dir_not_shared line. For example:

Code
RUNNER_DATA_DIR is /var/lib/yard-130p, but this container only shares /var/lib/yard with the host,
so Docker cannot see this runner's files and no workspace can start. Remove RUNNER_DATA_DIR to use
/var/lib/yard, or set it to a folder inside it such as /var/lib/yard/runner-2.

To fix a runner deployed this way:

  1. Stop it (stop the Coolify / Portainer resource, or docker compose -p <project> down).
  2. If the old folder holds anything (it did only if you mounted it yourself), move it on the host into /var/lib/yard, for example mv /var/lib/yard-130p /var/lib/yard/runner-2. A folder that existed only inside the container is gone with it; nothing to move.
  3. Remove RUNNER_DATA_DIR, or set it to the folder inside /var/lib/yard (/var/lib/yard/runner-2).
  4. Redeploy. The red notice goes away once the runner is back online.

Several runners on one server (advanced)

One compose runner serves every organization you add to it with add-org. Run a further compose runner only when you want one that is separate: its own container, data directory and update schedule. Each further runner needs:

  • Its own token. Register it in Yard (Register runner on the Runners page).
  • Its own deployment. A separate Coolify or Portainer resource, or with plain compose its own project name. Without -p, docker compose up in the same folder replaces the first runner's container.
  • Its own RUNNER_DATA_DIR inside /var/lib/yard: /var/lib/yard/runner-2, /var/lib/yard/runner-3, and so on. Never a sibling such as /var/lib/yard-2.
  • Nothing else changed in the compose file. The volume stays /var/lib/yard:/var/lib/yard for every runner, as do the Docker socket and /etc/machine-id. Each runner's identity comes from its own key in its own data directory, so sharing the machine id is fine.

With plain compose, the second runner on the same server:

Shell
RUNNER_TOKEN=<second token> RUNNER_DATA_DIR=/var/lib/yard/runner-2 \
  docker compose -p yard-runner-2 -f runner-compose.yml up -d

What they share, and why it is fine:

  • One Docker daemon. Every workspace container is named and labelled by its workspace id, and each runner only touches its own.
  • The same uid range. Each runner hands out uids and gids from 62000 up, so two runners' workspace files can show the same number on the host. They stay apart, because each box mounts only its own workspace's home.
  • The first runner's folder. A runner never looks into folders of its data directory it did not make, so /var/lib/yard/runner-2 inside the first runner's /var/lib/yard is left alone.

Two runners pointed at the same folder do not take turns: the second one logs data_dir_taken and waits until that folder is free. Give it its own folder instead.

For runners installed with the install script, see Several runners on one machine. To serve more organizations from the runner you have, see Adding an organization to a runner.

The runner's machine

A runner is pinned to the machine it first connects from. A copy of its token alone is not enough to receive workspace files or agent work on another machine.

When the runner's token is used from another machine (a different computer, or the runner's data folder copied elsewhere), that connection is held: connected, but given no work. The organization's admins are notified, and the Runners page shows that the runner connected from another machine:

  • Approve this machine pins the runner to the new machine. It goes live straight away, without reconnecting.
  • Reject closes the connection and refuses that machine from then on. Rotate the token too.

Moving a runner to another machine

Open the runner's settings (choose the runner in the menu behind the runner's name in a workspace's switcher, or Settings on it on the Runners page; they open as a dialog over the page you are on, with a tab per subject) and choose Reset device on the Machine and token tab. The runner forgets its machine, and the next machine that connects with its token is pinned without asking. Then install the runner on the new machine with the same token, or rotate the token first and use the new one.

Rotating the token keeps the pin: the pin belongs to the runner, not the token. Give every machine its own runner; two machines cannot share one.

Vault access

Secrets you store (agent sign-ins and API keys, app and monitor secrets, database addresses, bucket keys, webhooks, integration keys) are sealed to your organization's vault. Only runners that hold it can open them; Yard's servers store them sealed and cannot.

  • The organization's first runner makes the vault when it connects. Its fingerprint is shown under Settings, Vault, and the runner logs the same one when it loads it (vault_loaded).
  • Every other runner, a personal runner of a member included, waits on the Runners page with its machine and key fingerprint until an admin chooses Approve vault access. A runner that already holds the vault then shares it, so one of them must be online. Until then the approved runner's row says Vault · waiting for a key; it gets the key within seconds of a holder connecting. When a holder is online but cannot share the key, the row says why under it (for example "nps could not share the key: …"). Vault on a row means the runner reported that it opened the key; a runner that has the key but could not open it says Vault · not loaded, with the reason. yard runner status prints the key fingerprint of the machine's first organization and, under orgs, of each one added with add-org (each has its own key).
  • A runner without access answers "This runner has no vault access" for work that needs a secret. When no runner that holds the vault is online, bucket links, alert webhooks and transcription wait or fail with a message.
  • Revoke next to a runner under Settings, Vault (or deleting the runner, or rejecting its new machine) takes the access away. The machine may still know the old key, so choose Rotate vault under Settings, Vault: a runner that holds it makes a new key and seals every secret again.
  • If every runner that holds the vault loses its data folder, or none that is online can open the key, the secrets cannot be opened any more. The Runners page and Settings, Vault say so, and an admin can choose Reset vault there: an online runner makes a new vault, the runners approved for the old one get its key, and the secrets sealed to the old one are deleted, so you enter them again. Reset is refused while a runner that opens the key is online. Keep at least two runners with access, or back up the data folders, if that matters to you.

Rotating the token

In the runner's Settings, on the Machine and token tab, Rotate token gives it a new token and revokes the old one; the tab says when it was last rotated. An online runner receives the new token over its connection and stays connected; nothing has to be done on the machine, and the tab shows the new token in place (with Copy, for a runner that reads it from RUNNER_TOKEN). An offline runner is shown the command to reconnect it with a new setup token, and its Settings show that command until the machine has connected.

The other tabs: General (its status, what runs and waits, its CPU, memory and disk, its version with Update now, and removing it), Agents and load, Queue, Hosting and Network (its own address, below). Members who do not manage a runner see General and the Queue read only: the counts cover the whole runner, the list only their own turns.

A runner's own address

By default, terminals and file downloads travel through Yard's API. A runner can also serve them to browsers directly, on an https address of its own, which is faster when the runner is far from the API.

  1. On the machine, choose where the runner listens, then restart it:

    Shell
    # behind your own reverse proxy or tunnel that serves https
    yard runner direct set --listen 127.0.0.1:7443
    
    # or with your own certificate
    yard runner direct set --listen 0.0.0.0:443 --cert cert.pem --key key.pem
    
    yard runner service restart
    
  2. Open the runner's settings (from the menu behind the runner's name in a workspace's switcher, or Settings on the Runners page) and enter the address under Own address, for example https://runner-1.example.com. Yard checks that the address answers as this runner, and checks again every hour. Only a pinned runner can have an address.

--cert and --key go together. Without them, something in front of the runner must serve https.

When the address cannot be reached from a browser, that browser goes through the API instead. A terminal shows "direct" while it is connected directly. Uploads, screenshots and the live view always go through the API.

To stop:

Shell
yard runner direct off
yard runner service restart

Then remove the address in the runner's Settings.

Hosting apps on a runner

A runner can also run your projects' apps and give each a URL (see Apps). Turn it on in the runner's Settings → Hosting in Yard; the domain, TLS mode, max apps and the free subdomain on yrd.sh are set there. The machine needs Docker: the runner starts a Traefik proxy (yard-proxy-<id>, one per runner process, shared by every organization the runner serves) by itself.

Only a few settings stay on the machine. Set them, then restart the runner:

Shell
# a certificate of your own (TLS "manual")
yard runner hosting set --cert cert.pem --key key.pem

# a wildcard certificate through Cloudflare (TLS "dns01")
yard runner hosting set --dns-token-file /etc/yard/cloudflare-token --acme-email [email protected]

yard runner service restart
yard runner hosting doctor

yard runner hosting doctor checks DNS, the _yard-verify TXT record, Docker (and says why it does not answer), what the running runner itself last saw, the proxy image, ports 443 and 80 (naming a container that already holds one), and the tunnel to yrd.sh. yard runner hosting status shows what the runner last reported.

What the doctor prints

yard runner hosting doctor prints the proxy diagnosis first (the mode, and one line per check, ✓ fine, ! worth a look, ✗ broken, - skipped), then the host checks. A runner behind Coolify, healthy:

Code
Mode: coolify — runner runs in a container; proxy is coolify-proxy (Coolify) on 443

✓ Port 443 holder: coolify-proxy holds 443 (a container).
✓ Listen address: 172.17.0.1:8443 is a loopback or private address.
✓ Proxy reaches the runner: coolify-proxy shares the network coolify with the runner's container …
✓ Request from inside the proxy: 172.17.0.1:8443: answers.

✓ hosting.example.com → 203.0.113.10
✓ *.hosting.example.com (doctor-k3x9ab.hosting.example.com) → 203.0.113.10
✓ _yard-verify.hosting.example.com TXT "yard-verify=…"
✓ docker answers
✓ the runner last saw (2026-10-15T09:12:44Z): docker answers, proxy running
✓ traefik:v3.4 is present
✓ yard-proxy-rnr_… is running
  the proxy listens on 172.17.0.1:8443 (from RUNNER_HOSTING_LISTEN)
✓ port 8443 is the proxy's
! tls off: put an https proxy (or tunnel) in front of this port
Line What it checks
<domain> →, *.<domain> → The domain and a random name under it resolve, to the same address.
_yard-verify.<domain> TXT The ownership record from the runner's Hosting settings is published.
docker Docker answers, and why not when it does not (not on PATH, no permission on the socket, daemon not running).
the runner last saw What the running runner itself saw (Docker, proxy), which can differ from this shell's.
traefik:v3.4 is present The proxy image is pulled (turning hosting on pulls it).
yard-proxy-<id> and the port lines The proxy runs, where it listens and why, and that nothing else holds the port; another container holding it is named.
tls off is a reminder that an https proxy has to be in front.
tunnel to the edge With a free subdomain on yrd.sh in Tunnel mode: connected or not.
Addresses for app networks How many subnets of RUNNER_NETWORK_POOL are in use; ! above 80%, or when the pool is docker.

The exit code is non-zero when a line is ✗. When the proxy cannot reach the runner, the doctor proposes a change (a new listen address and the proxy's route file) as a diff and applies it only with --apply; add --json for the report as data.

Ports. With a domain of your own the proxy listens on 0.0.0.0:443 (--listen changes it), and on port 80 too with TLS http01. With only a free subdomain on yrd.sh in Tunnel mode, the runner connects out and needs no open port. A runner's own address and hosting cannot both use port 443: move one (yard runner direct set --listen … or yard runner hosting set --listen …).

A runner in a container, or behind Coolify. A runner started from docker-compose.runner.yml hosts apps too: it joins the proxy's network and each project's network by itself. On a server where another proxy already holds ports 80 and 443 (Coolify's coolify-proxy, Caddy, nginx), the runner notices it and goes behind that proxy by itself: it listens on 127.0.0.1:8443, with TLS off and no port 80, and the Hosting settings show a config to paste into the other proxy. If you set the address yourself, the settings name the holder ("Port 443 is held by coolify-proxy") and offer Run behind another proxy. Hosting behind another proxy explains it, with pages for nginx, Caddy, Traefik and a setup by hand; yard hosting doctor diagnoses it, including why wildcard certificates need DNS-01 there and why a domain such as useyard.app never appears in an app's address; Run a runner on Coolify walks through the install. RUNNER_HOSTING_LISTEN in the runner's environment does the same from the machine, and wins over the field:

YAML
# docker-compose.runner.yml, or the service's environment in Coolify
environment:
  RUNNER_HOSTING_LISTEN: 127.0.0.1:8443

Then either turn on Free subdomain on yrd.sh in Tunnel mode (no open port and no certificate on the server), or keep a domain of your own with TLS mode off and let the other proxy serve https for <domain> and *.<domain> and pass requests on to that address.

Network addresses

Each project's apps get a Docker network of their own (yard-net-<project>), and each workspace's boxes one too (yard-box-<workspace>). The runner gives each a small subnet, a /24, from 10.213.0.0/16: room for 256 networks. It skips any subnet another Docker network or one of the machine's routes already uses. A project's network is removed when its last app stops, and the runner removes its own networks that no app is on when it starts and regularly after that.

Change the range when 10.213.0.0/16 is used on your network (a LAN or a VPN the machine does not route itself), or when you need more networks:

YAML
environment:
  RUNNER_NETWORK_POOL: 10.88.0.0/16   # the range networks are taken from
  RUNNER_NETWORK_PREFIX: "25"         # the size of each, /20 to /28 (default 24)

RUNNER_NETWORK_POOL=docker leaves the choice to Docker, as runners did before: each network then takes one of Docker's default pools, about 31 per machine. When no address is left, an app's start fails with "The runner has no network addresses left for this project": stop the apps of finished projects, or widen the range. Networks that already exist keep their addresses.

Behind Coolify or Traefik

The usual shape on a server that already runs Coolify:

  1. The runner runs in a container (the compose file above). Coolify's proxy (Traefik) holds ports 80 and 443 on the host.

  2. The runner's own proxy, yard-proxy-<id>, listens on the Docker bridge address and not on loopback, because Coolify's proxy is a container and its 127.0.0.1 is its own:

    YAML
    environment:
      RUNNER_HOSTING_LISTEN: 172.17.0.1:8443
    
  3. In the runner's Hosting settings in Yard, set TLS to off: the other proxy terminates https.

  4. Coolify's Traefik serves https for <domain> and *.<domain> (a wildcard certificate, so DNS-01) and forwards to 172.17.0.1:8443. Run yard runner hosting doctor to get the route file for your proxy.

The step-by-step is in Run a runner on Coolify, and the Traefik route file in Traefik; this page does not repeat them. Firewall 8443 to the proxy: a bridge address is not reachable from outside, but a 0.0.0.0 listen address would be.

When hosting does not start. The runner's Hosting section and a refused start name the cause: Docker is not available, with the reason (not on PATH, no permission on the socket, the daemon not running, a timeout), or Hosting could not start, with the proxy's error. The runner tries again by itself, after 30 seconds and then up to every 5 minutes, and checks Docker again whenever an app is started, so you do not have to restart it once the cause is gone.

A separate machine for apps. Hosting puts a proxy that faces the internet on the runner's machine. To keep it away from your workspaces' files, register another runner on another machine, turn on hosting there and turn Use for workspaces off: it then runs only apps.

From a hoster. A machine that ran yard hoster becomes a hosting-only runner after yard update, with the same token: its settings move into the runner's on the first start, and yard hoster still works for one release, printing the new command.

Settings

The runner reads a few settings from its environment. Set them before yard runner up --service or yard runner service install, which copy them into the service.

Variable Default What it does
RUNNER_DATA_DIR ~/.yard, or /var/lib/yard as root on Linux Where the runner keeps its settings and workspaces; the same as --data-dir. The first runner to connect from it owns it; any other runner refuses to start there (yard runner adopt-data-dir --yes hands it over). Never share one between two runners.
RUNNER_BOX_IDLE_MINUTES 30 Stop a workspace container nobody has used for this long (0 = never).
RUNNER_AGENT_CONCURRENCY 4 How many agent turns may run at once. Agents at once in the runner's settings in the app takes precedence.

When the machine is busy

In the runner's settings in the app, Load says when new agent turns wait for the machine: above the CPU threshold or the memory threshold (90% each by default), new turns wait in the runner's queue and start one at a time once both are 10 points below. Turns already running finish. A spike of a few seconds does nothing. When the load is critical, the runner also pauses workspaces nobody is using and starts them again once it is back to normal; a workspace someone stopped stays stopped. Changes apply at once, without a restart. The same dialog lists the runner's queue, with Retry all failed. Organization admins and the owner of a personal runner can change these settings. Runners before 0.12.0 have no load gate: update them first. | RUNNER_TRASH_HOURS | 24 | How long a deleted project's files are kept on the machine (0 = keep). | | RUNNER_ARCHIVE_DAYS | 30 | How long an archived workspace's local copy is kept (0 = keep). | | RUNNER_HOUSEKEEPING_PING_URL | unset | The ping URL of a cron monitor. The runner calls it after each hourly clean-up of deleted and archived files, and <url>/fail when the clean-up failed. | | RUNNER_KEEP_AWAKE | on | macOS: keep the machine from idle sleep. 0 turns it off. | | RUNNER_AUTO_UPDATE | off | Install newer builds by itself, between jobs. | | RUNNER_HOSTING_LISTEN, RUNNER_HOSTING_CERT, RUNNER_HOSTING_KEY, RUNNER_HOSTING_ACME_EMAIL, RUNNER_HOSTING_DNS_TOKEN_FILE, RUNNER_HOSTING_WEB_URL, RUNNER_HOSTING_TUNNEL_PORT | see Hosting | The machine's hosting settings, as yard runner hosting set saves them. |

Was this page useful?
Edit this page