Guides on Self-hosted runner manager for GitHub

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.

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.

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.

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):