Self-hosted runners run GitHub Actions jobs on infrastructure you operate, such as a local Mac mini, instead of on GitHub-hosted runners.
Self-hosted runners are a good fit when you want:
- faster runs by avoiding repeated environment setup
- more control over security and network boundaries
- lower cost at larger scale
- extra flexibility, including richer local tooling or agent capabilities
Local runner setup
For the maintained setup scripts and step-by-step instructions, use .agent/tools/local-runner. That folder contains the host requirement check, bootstrap, setup, start, stop, cleanup, and cleanup scheduling files for running local macOS or Linux self-hosted runners. Scheduled cleanup uses launchd on macOS and cron on Linux.
Keep this setup page focused on the decision to use self-hosted runners; keep machine-specific setup details in the local runner tool folder.
Runner requirements
At a high level, the runner host needs Node support compatible with .github/actions/setup-agent-runtime, git, gh, jq, curl, bash, and network access. It also needs either repository secrets for the selected agent providers or local provider authentication available to the same user that runs the GitHub runner. Docker is optional unless your workflows require it.
Provider auth note
On self-hosted runners, an explicit AGENT_DEFAULT_PROVIDER=codex, AGENT_DEFAULT_PROVIDER=claude, or route-specific AGENT_MODEL_POLICY provider override is treated as an operator choice. The provider resolver will select that provider even if the matching repository secret is absent, so single-agent runs and review synthesis can use local Codex or Claude authentication already configured on the machine. In auto mode, provider detection still relies on repository secrets and chooses Codex when OPENAI_API_KEY is configured; otherwise it chooses Claude when either CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY is configured. Sepo passes a pinned built-in model for the selected provider by default, and AGENT_MODEL_POLICY can override that with a provider-specific or route-specific model. Sepo’s built-in Claude default is claude-opus-4-8, which requires Claude Code v2.1.154 or later; run claude update on self-hosted runners with a preinstalled Claude CLI because setup-agent-runtime installs the current CLI only when claude is missing. The review workflow still attempts explicit Claude and Codex reviewer lanes; those lanes resolve pinned/provider-specific models with fixed providers, while AGENT_DEFAULT_PROVIDER controls only synthesis and other defaulted runs.
Continuity note
Repositories with sticky self-hosted runners can choose to set AGENT_SESSION_BUNDLE_MODE=never to prefer local session state over artifact bundles. For the trade-offs behind that setting, see Session continuity.