Doctor and troubleshooting
ushr doctor checks everything between a host and a working runner. Run it first when jobs do not start.
ushr doctor
ushr doctor --config /path/to/agent.yamlEach check prints ✓ or ✗. A failed check prints a fix on the next line. The command exits non-zero when a check fails.
What it checks
| config | The agent config loads. Default ~/.config/ushr/agent.yaml. |
| driver | Tart and the runner VM image, Docker or Podman and the buildx plugin, or lume, for the configured driver. |
| disk space | Free space on the image store is above min_free_gb. |
| GitHub App | Each org or repo has a readable key, and the App is installed on that scope. |
| agent | The ushr-agent binary exists and the service runs. |
| control plane | The agent's controller_url answers on /healthz. |
If GitHub cannot be reached, doctor prints ? for the App install check. It does not count that as a failure.
Common problems
| Jobs never start | Run ushr doctor. Check that the job's runs-on labels are all in the host's labels. Check free disk space: under the floor, the host takes no jobs. |
| Disk too small for the floor | Doctor fails when the disk is smaller than three times min_free_gb. Lower driver.min_free_gb. |
| App not installed | Install the App on the org or repo from GitHub → Settings → Developer settings → GitHub Apps. Or fix a mistyped scope. |
| "enrollment token does not cover" error | An org or repo in agent.yaml is not in this host's enrollment. Remove it, or run ushr login and change the host's GitHub access. |
| Personal account | User accounts have no org-level runners. Use ushr setup --repo OWNER/REPO. |
| Builds run uncached on Linux | Install the buildx plugin, for example sudo apt-get install docker-buildx. Or set build_cache: false. |
| Control plane unreachable | Check the URL and the network. On a self-hosted setup, check that ushr-controller runs. |
Logs
# macOS
tail -f ~/Library/Logs/ushr/agent.log
tail -f ~/Library/Logs/ushr/controller.log
# Linux
journalctl --user -u ushr-agent -f
journalctl --user -u ushr-controller -fnext Billing and plans →