buildhound
Dashboard

Get started

Set up with your agent

One prompt. The agent does the rest and asks you only when GitHub needs a person.

The prompt#

Paste this into Claude Code, Codex or Cursor, in the repository you want to run on this machine. It is the same prompt the button on the home page copies.

Prompt
Set up Buildhound (https://buildhound.sh) so this repository's GitHub Actions jobs run on this machine.

1. Run `npx buildhound setup` to install the Buildhound skill and MCP server for you.
2. Connect this machine: `npx buildhound runner add --org <owner of this repository> --label macos --yes` (use `--label linux` on Linux). If it returns needs_human, give me the link and wait until I say it is done.
3. Once the machine is connected, on a new branch change `runs-on: macos-latest` in this repository's workflows to `runs-on: ${{ vars.BUILDHOUND_MACOS || 'macos-latest' }}`, and `runs-on: ubuntu-latest` to `runs-on: ${{ vars.BUILDHOUND_LINUX || 'ubuntu-latest' }}`, then open a pull request. If the repository is public, use `runs-on: ${{ ((github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository) || github.event_name == 'push' || github.event_name == 'schedule' || github.event_name == 'workflow_dispatch' || github.event_name == 'merge_group' || github.event_name == 'release') && vars.BUILDHOUND_MACOS || 'macos-latest' }}` and `runs-on: ${{ ((github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository) || github.event_name == 'push' || github.event_name == 'schedule' || github.event_name == 'workflow_dispatch' || github.event_name == 'merge_group' || github.event_name == 'release') && vars.BUILDHOUND_LINUX || 'ubuntu-latest' }}` instead, so pull requests from forks and jobs anyone on GitHub can start stay on GitHub-hosted.

Docs: https://buildhound.sh/docs

What the agent does#

  1. Runs npx buildhound setup, which installs the Buildhound skill and MCP server for the agents it finds on the machine.
  2. Runs npx buildhound runner add for your account, which registers this machine and starts the agent that takes jobs.
  3. On a new branch, changes runs-on in your workflows to the routing expression and opens a pull request. Nothing is committed to your default branch.

The one step that needs you#

GitHub asks a person to install the GitHub App. When that is needed the command returns needs_human with one URL; the agent hands it to you, you click through, and the agent carries on. Joining a pool, marking a machine as trusted and routing jobs that use secrets also need a person, by design.

Check it worked#

Linux jobs in that repository run on your machine within minutes of the prompt. macOS jobs follow once the Mac has built its image, a one-time step that takes a while. To see the machine and its jobs:

npx buildhound runner status --org <owner>