Set up by hand

On the machine that will run jobs, signed in to GitHub with gh or with a token in GITHUB_TOKEN:

npx buildhound runner add --org <owner> --label macos --yes

Use --label linux on a Linux machine, or --label macos,linux on a Mac that should take both. The command registers the machine, writes ~/.buildhound/agent.json, installs the agent and starts it. If GitHub needs the App installed first, the command prints one URL and stops; install the App, then run the same command again.

On a personal account you can limit the machine to some repositories with --repositories owner/name,owner/other. By default a job's VM reaches the internet and nothing on your network (--vm-network isolated).

Replace the hosted label with the routing expression. On a private repository, for macOS jobs:

runs-on: ${{ vars.BUILDHOUND_MACOS || 'macos-latest' }}

For Linux jobs:

runs-on: ${{ vars.BUILDHOUND_LINUX || 'ubuntu-latest' }}

Open it as a pull request. The control plane sets the variable while a machine can take jobs and clears it when none can, so the hosted default takes over on its own. On a public repository use the longer expression in Workflows instead, so pull requests from forks and jobs anyone on GitHub can start stay on GitHub-hosted.

The next job in that repository runs on your machine. To see machines, heartbeats and running jobs:

npx buildhound runner status --org <owner>

On the machine itself, npx buildhound runner status --local asks the agent directly.