Self-hosted runner manager for GitHub (gh sr)

Self-hosted runner manager for GitHub is a GitHub CLI extension for managing self-hosted GitHub Actions runners across many machines from one place—usually your laptop. It connects over SSH (or runs locally with addr: local), installs and starts runners, and gives you a terminal UI for day-to-day operations.

Repository: github.com/an-lee/gh-sr
Go module: github.com/an-lee/gh-sr (used by go install and imports).

Features

• One set of commands for Linux, macOS, and Windows runners (setup, up, down, status, logs, service, …).
• Declarative YAML for hosts and runners; GitHub API auth via gh auth login only.
• Docker or native runners per row, with sensible OS defaults and overrides.
• Multi-host from a single config; optional TUI dashboard (gh sr or gh sr dashboard on a TTY).

Dashboard

  gh sr dashboard                              [r]efresh  [?]help  [q]uit

  INSTANCE      HOST         REPO                MODE    LOCAL    GITHUB
  ─────────────────────────────────────────────────────────────────────────
  runner-1      mac-mini     org/backend         native  running  online
  runner-2      linux-vps    org/frontend        docker  running  busy
  runner-3      win-pc       org/infra           native  stopped  offline

  [enter] runner actions  [g] global menu  [f] filter  [j/k] navigate

Documentation

Full documentation (user guide, architecture, config reference):
https://an-lee.github.io/gh-sr/

The Markdown sources live under docs/ in this repo and are built with Hugo (Hugo Book theme).

Install

Install as a GitHub CLI extension (recommended):

gh extension install an-lee/gh-sr

Then use gh sr (for example gh sr status). Requires GitHub CLI (gh) and a recent gh version.

From source with Go:

go install github.com/an-lee/gh-sr/cmd/gh-sr@latest

Pin a specific release (same v* tags as GitHub Releases):

gh extension install an-lee/gh-sr --pin v1.2.0
go install github.com/an-lee/gh-sr/cmd/gh-sr@v1.2.0

The resulting binary is named gh-sr. To invoke it as gh sr, install the extension as above, or run gh-sr directly if it is on your PATH.

Requires a recent Go toolchain when building from source (see go.mod / CI for the exact version).

Quick start

gh auth login           # required: gh sr uses the GitHub CLI token
gh sr init --quick        # interactive: prompts for repo + host, auto-detects everything else
gh sr up                  # auto-setup + start (all in one)
gh sr status

Or step by step:

gh sr init                            # create ~/.gh-sr with template config
gh sr add host my-vps root@10.0.0.1  # add a host (os/arch auto-detected)
gh sr add runner ci --repo owner/repo --host my-vps  # add a runner (labels auto-generated)
gh sr up                              # auto-setup + start

Then run gh sr on a terminal for the interactive dashboard, or use gh sr status, gh sr logs <name>, etc.

GitHub Agentic Workflows (gh-aw)

To run GitHub Agentic Workflows on your self-hosted runners, use the agentic profile:

runners:
  - name: aw-runner
    repo: owner/repo
    host: my-vps
    profile: agentic

This configures gh sr to install gh-aw on the host, set up the necessary tooling cache, and perform advanced Doctor checks.

Linux Docker DNS Requirement: gh-aw agents rely on host.docker.internal to reach the MCP gateway running on the host. On macOS and Windows Docker Desktop, this is automatic. On Linux, you must configure a local DNS resolver (e.g., dnsmasq) to resolve host.docker.internal to the docker0 bridge IP (usually 172.17.0.1), and instruct Docker to use it. The dnsmasq config must include upstream server= directives (e.g., server=127.0.0.53 and server=8.8.8.8), otherwise only static records are answered and all external DNS (model provider APIs, etc.) is refused from inside containers. Do not map it to 127.0.0.1 in your host's /etc/hosts, or the connection will be refused inside agent containers! Run gh sr doctor to automatically verify both internal and external DNS resolution from containers.

For detailed configuration instructions, see the Host Setup Documentation.

Development

make check    # vet + tests (same idea as CI)
# or: go vet ./... && go test ./... -race -count=1

Repository layout is described in docs/reference/file-structure.md.

Publishing documentation (maintainers)

Documentation deploys to GitHub Pages via GitHub Actions when changes land on main. In the GitHub repo, enable Settings → Pages → Build and deployment → Source: GitHub Actions once (no branch-based /docs hosting required for the built site).

Local preview:

# from the repository root:
git clone https://github.com/alex-shpak/hugo-book docs/themes/book --depth 1
cd docs && hugo server

Build (also run in CI):

cd docs && hugo --minify