ushr documentation
ushr runs GitHub Actions jobs on Macs and Linux machines that you own. One scheduler shares those machines across your GitHub organisations.
The three binaries
The installer puts three binaries on each host.
| ushr | The CLI. It sets up hosts, checks health and rewrites workflow targets. |
| ushr-agent | Runs on each runner host. It holds your GitHub App key, watches GitHub for queued jobs and starts one ephemeral runner per job. |
| ushr-controller | The scheduler. It ranks queued jobs and sends each one to an agent. ushr.io runs it for you, or you run it yourself. |
Two ways to run it
Hosted: the agent connects to the control plane at ushr.io. You get scheduling across machines and a dashboard. Start with Hosted setup.
Self-hosted: the controller runs on the same machine as the agent. The controller and the agent send no data to ushr.io. The installer still downloads releases through get.ushr.io by default. Hosts also download tools and images from Homebrew and Docker Hub. Start with Self-host a single host.
Where your keys live
The agent holds the GitHub App private key. The control plane receives queue metadata from agents and returns dispatch decisions. It never receives a GitHub credential. For each job, the agent mints a single-use just-in-time runner registration. The runner connects directly to GitHub and removes itself when the job ends.