Self-hosted runner manager for GitHub

Introduction

Mon, 01 Jan 0001 00:00:00 +0000

Introduction#

The Problem#

Self-hosted GitHub Actions runners give you more control over your CI/CD infrastructure — but managing them across multiple machines is tedious. To add a new runner you must SSH into each machine, download the runner software, configure it, start the process, and remember which machine has what. Monitoring, updating, and restarting runners means touching every machine individually. As the number of runners and machines grows, this overhead becomes unmanageable.

File Structure

Mon, 01 Jan 0001 00:00:00 +0000

File structure#

Layout of this repository (module github.com/an-lee/gh-sr):

gh-sr/ # repository root (GitHub: gh-sr)
 cmd/
 gh-sr/
 main.go # CLI entry point (binary name: gh-sr; command: gh sr)
 internal/
 config/
 config.go # YAML config parsing and validation
 envfile.go # ~/.gh-sr/env dotenv loader
 paths.go # Config path resolution, ~/.gh-sr helpers
 load.go # LoadFromPath with missing-file hints
 template.go # Embedded template for gh sr init
 runners.yml.template # Default runners.yml content
 editor/
 editor.go # $VISUAL / $EDITOR / platform default
 host/
 host.go # Host abstraction
 connection.go # SSH connection management (Executor interface)
 local.go # Local command execution (addr: local)
 doctor/
 doctor.go # gh sr doctor diagnostics
 ops/
 ops.go # Shared setup/up/down/restart/update/status/logs/cleanup (CLI + TUI)
 service.go # gh sr service install/uninstall/status
 autostart/
 autostart.go # systemd / launchd / Windows task install and Detect/Start/Stop
 active.go # Supervisor active check for gh sr status
 generate.go # Unit and plist text generation
 sanitize.go # Safe names for unit files and tasks
 runner/
 runner.go # Runner lifecycle orchestration
 native.go # Native runner management (mac/win/linux)
 docker.go # Docker runner management
 github.go # GitHub API client
 tui/
 dashboard.go # Interactive TUI dashboard (model + update)
 dashboard_view.go # TUI views and layout
 status.go # Status table rendering
 styles.go # Lipgloss styles
 config/
 runners.yml # Example YAML (not auto-loaded; use GH_SR_CONFIG or -c)
 docs/ # Hugo source (this site)
 go.mod
 go.sum

Installation

Mon, 01 Jan 0001 00:00:00 +0000

Installation#

Install as a GitHub CLI extension (recommended)#

Requires GitHub CLI (gh).

gh extension install an-lee/gh-sr

After installing, you invoke the tool as gh sr. Create config with gh sr init (see below).

Install with Go#

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

This installs a binary named gh-sr on your PATH. Use gh sr by installing the extension as above, or run gh-sr directly.

go install does not create config files. After installing, run:

gh sr init

This creates ~/.gh-sr/runners.yml from a template and ~/.gh-sr/env (optional dotenv for other tooling). Then edit the config (or use gh sr config edit), run gh auth login, then gh sr doctor. gh sr uses the GitHub CLI token only; see Authentication.

Workflows

Mon, 01 Jan 0001 00:00:00 +0000

Using runners in workflows#

Reference runners by label in your workflow files:

jobs:
 build-linux:
 runs-on: [self-hosted, Linux, X64]

 build-mac:
 runs-on: [self-hosted, macOS, ARM64]

 build-win:
 runs-on: [self-hosted, Windows, X64]

Labels must match what you configure under runners[].labels in Configuration.

GitHub Agentic Workflows (gh-aw)#

gh sr has first-class support for GitHub Agentic Workflows. Use profile: agentic to configure a runner with all the prerequisites gh-aw needs:

runners:
 - name: aw-runner
 repo: owner/repo
 host: vps-1
 profile: agentic
 count: 2

This automatically sets docker mode, host networking, NET_ADMIN capability, installs iptables in the container for the Agent Workflow Firewall, and adds an agentic label. See the host setup docs for details.

Agentic Workflows

Mon, 01 Jan 0001 00:00:00 +0000

Agentic Workflows#

GitHub Agentic Workflows (gh-aw) run AI agents inside sandboxed Docker containers on self-hosted runners. Unlike normal Actions jobs that execute a fixed script, agentic workflows run a live AI model that decides what steps to take, what tools to call, and how to respond to errors.

How it differs from normal Actions workflows#

	Normal workflow	Agentic workflow
Execution model	Fixed step sequence defined in YAML	AI agent decides steps dynamically
Environment	Runs directly on the runner	Runs inside an isolated Docker container (sandbox)
Tool access	Via action steps	Via MCP (Model Context Protocol) servers
Network	Runner’s network namespace	Separate `awf-net` bridge; egress via Squid proxy
State	Persistent runner filesystem	chroot into host filesystem

Architecture#

graph TB
 subgraph HostNetwork ["Host Network Namespace (--network host)"]
 Runner["GitHub Actions Runner<br/>process / container"]
 MCPGateway["MCP Gateway<br/>ghcr.io/github/gh-aw-mcpg<br/>listens on :80"]
 end

 subgraph AWFNet ["awf-net (Docker bridge 172.30.0.0/16)"]
 AgentSandbox["Agent Sandbox<br/>ghcr.io/github/gh-aw-firewall/agent<br/>chroot into host /"]
 SquidProxy["Squid Proxy<br/>172.30.0.10:3128<br/>whitelisted domains only"]
 APIProxy["Anthropic API Proxy<br/>172.30.0.30:10001"]
 end

 Runner -->|"1. Launch"| AgentSandbox
 Runner -->|"2. Start MCP gateway"| MCPGateway
 AgentSandbox -->|"3. MCP calls via<br/>host.docker.internal:80"| MCPGateway
 AgentSandbox -->|"4. All HTTP/HTTPS<br/>via HTTPS_PROXY"| SquidProxy
 AgentSandbox -->|"5. Model API calls<br/>via HTTPS_PROXY"| APIProxy
 SquidProxy -->|"allowed domains only"| Internet["External APIs<br/>github.com<br/>api.minimaxi.com"]
 APIProxy -->|"upstream API"| Internet

Components#

Runner – The GitHub Actions runner process. It registers with GitHub, receives job assignments, and orchestrates the workflow. For agentic workflows it is responsible for starting the MCP Gateway and Agent Sandbox containers.

Common Tasks

Mon, 01 Jan 0001 00:00:00 +0000

Common tasks#

Add a new host#

Add an entry under hosts in your resolved config file (~/.gh-sr/runners.yml by default)
Ensure SSH key-based access works: ssh user@host true
Add runner entries referencing the new host
Run gh sr setup && gh sr up

Scale up#

Change count in your runners YAML, then:

gh sr setup # configures new instances
gh sr up # starts them

Update runner version#

gh sr update

This removes existing runners, downloads the latest runner binary, reconfigures, and starts them.

Configuration

Mon, 01 Jan 0001 00:00:00 +0000

Configuration#

Config file location#

When you do not pass --config / -c, the config file is chosen in this order:

GH_SR_CONFIG — path to a YAML file (absolute or relative to the current working directory).
~/.gh-sr/runners.yml — default after gh sr init.

There is no automatic discovery of ./config/runners.yml in the current directory; use GH_SR_CONFIG or -c if your file lives elsewhere.

If you pass -c /path/to/runners.yml, that path is always used (and GH_SR_CONFIG is ignored).

Authentication

Mon, 01 Jan 0001 00:00:00 +0000

Authentication#

gh sr uses the GitHub CLI for GitHub API authentication only. Install gh and sign in:

gh auth login

gh sr reads the token from gh’s stored credentials (via the same mechanism as other gh extensions). This also handles token refresh. For GitHub Enterprise Server, use gh auth login --hostname enterprise.example.com (API hostname support in gh sr follows gh; the default is github.com).

Do not set github.pat in runners.yml or GITHUB_PAT / GITHUB_TOKEN for gh sr — those paths are removed. If your config still contains github.pat, loading will fail with an error until you remove it.

Local Host

Mon, 01 Jan 0001 00:00:00 +0000

Local host runners#

You can set up runners on the same machine where gh sr runs, without SSH. Set addr: local on a host and gh sr will execute commands directly via os/exec instead of dialing an SSH connection.

When addr is local, the os and arch fields are auto-detected from the Go runtime (runtime.GOOS / runtime.GOARCH) and can be omitted. You can still set them explicitly to override.

hosts:
 my-laptop:
 addr: local

runners:
 - name: my-local-runner
 repo: owner/repo
 host: my-laptop
 count: 1
 labels: [self-hosted, Linux, X64]
 mode: native

Both native and docker modes work with local hosts. Docker mode requires Docker to be installed and accessible to the current user.

Host Setup

Mon, 01 Jan 0001 00:00:00 +0000

Host setup (manual steps)#

gh sr automates runner installation and lifecycle over SSH, but some host preparation is still manual. After you edit config, run gh sr doctor from your laptop to verify config paths, GitHub API access, SSH connectivity, and per-host tools (Docker vs native). By default the command exits with a non-zero status only when a check is FAIL; use gh sr doctor --strict if you also want WARN lines to fail (for example in CI).

Linux on Windows

Mon, 01 Jan 0001 00:00:00 +0000

Linux runners on a Windows host#

You can run Linux container runners on a Windows machine without a separate SSH endpoint into WSL2. Set mode: docker on a runner that targets an os: windows host and gh sr will manage the Docker container over the same SSH connection (Docker CLI invoked through the same encoded PowerShell path as native Windows runners).

Requirements on the Windows host:

OpenSSH Server enabled (see Host setup — Windows)
Docker Desktop installed and running with the default Linux containers mode

hosts:
 win-pc:
 addr: user@192.168.1.51
 os: windows
 arch: amd64

runners:
 # Native Windows runner
 - name: myapp-win
 repo: owner/repo
 host: win-pc
 labels: [self-hosted, Windows, X64]

 # Linux runner via Docker Desktop on the same Windows host
 - name: myapp-linux
 repo: owner/repo
 host: win-pc
 mode: docker
 labels: [self-hosted, Linux, X64]

 # Same Linux runner, tuned for GitHub Agentic Workflows (MCP gateway + awf firewall)
 - name: myapp-linux-agentic
 repo: owner/repo
 host: win-pc
 mode: docker
 docker_network_mode: host
 docker_cap_add: [NET_ADMIN]
 labels: [self-hosted, Linux, X64]

Both runners share a single SSH connection to Windows. The native runner starts run.cmd via PowerShell; the Docker runner calls docker run the same way, which talks to Docker Desktop’s Linux engine.

Commands

Mon, 01 Jan 0001 00:00:00 +0000

Commands#

Running gh sr with no subcommand opens the interactive dashboard on a TTY (same as gh sr dashboard). If stdout is not a terminal (for example in a pipe or CI), gh sr prints a short hint to stderr and exits successfully; use gh sr status or gh sr --help in those environments.

gh sr # Open dashboard (TTY only; see above)
gh sr init [--force] # Create ~/.gh-sr with template runners.yml and env file
gh sr doctor [--strict] # Check config, GitHub API, and host prerequisites
gh sr setup [names...] # Install runner binary and configure on hosts
gh sr up [names...] # Start runners
gh sr down [names...] # Stop runners
gh sr restart [names...] # Stop then start
gh sr status # Show status table
gh sr hosts # Show host resource usage (CPU, memory, disk, load, uptime)
gh sr logs <name> # Show recent logs from a runner
gh sr cleanup # Remove offline/ghost runners from GitHub
gh sr update [names...] # Update runner binary (remove + setup + start)
gh sr service install [--system] [names...] # Native: OS autostart (systemd / launchd / task)
gh sr service uninstall [names...] # Remove gh sr-installed autostart
gh sr service status [names...] # Autostart + unit state (docker: policy note)
gh sr config path # Print resolved config and ~/.gh-sr/env paths
gh sr config show # Print resolved configuration (token source summarized)
gh sr config edit # Edit resolved runners.yml in $VISUAL / $EDITOR
gh sr config edit-env # Edit ~/.gh-sr/env in $VISUAL / $EDITOR
gh sr config validate # Validate config (exit 0 if OK)
gh sr dashboard # Same as bare gh sr: launch interactive TUI dashboard

The dashboard includes live status, per-runner actions (setup, up, down, restart, update, logs), global actions (doctor, cleanup, show/validate/edit config and env), and host/repo filters. Press h to open the host metrics panel (CPU, memory, disk, load, uptime) or ? for the full key map.

Linux on macOS

Mon, 01 Jan 0001 00:00:00 +0000

Linux runners on a macOS host#

Set mode: docker on a runner that targets an os: darwin host to run the same Linux container image as on Linux. gh sr does not run the Linux Docker install script on macOS; install a Docker runtime yourself.

Requirements on the Mac:

Docker Desktop, OrbStack, or Colima installed, with docker working in the environment where gh sr runs commands (for example the same user over SSH).

Docker socket permissions: macOS runtimes (Docker Desktop, OrbStack, Colima) expose a socket that is accessible to all processes — there is no host docker group GID issue. gh sr skips --group-add on macOS hosts. gh sr bind-mounts the Docker socket into the container at /var/run/docker.sock so jobs can reach the Docker daemon. If docker_socket is unset, gh sr picks /var/run/docker.sock when present, otherwise the unix:// path from your default Docker context (typical for Colima), otherwise ~/.colima/default/docker.sock on macOS. Colima + virtiofs: when the resolved path is under ~/.colima/…, gh sr uses /var/run/docker.sock as the bind-mount source for the runner container (VM path), not the macOS host socket file, to avoid docker run failing with operation not supported (Colima #997); you can also use colima start --mount-type sshfs if needed. Set docker_socket only when the default Docker context does not match the engine you want (e.g. a named Colima profile):

Architecture

Mon, 01 Jan 0001 00:00:00 +0000

Architecture#

This page explains where runners run, how gh sr reaches each host, and how status, dashboard, and logs collect information.

Control plane vs execution plane#

gh sr is a control plane only: it runs on your machine and issues commands. The GitHub Actions runner (native process or Docker container) always runs on the target host from your config—either the same machine as gh sr when addr: local, or a remote machine over SSH.