One-click GitHub Actions self-hosted runners for macOS, Windows & Linux

HomeRun replaces the manual GitHub self-hosted runner setup process with a unified desktop app and terminal UI. Authenticate with GitHub once, pick a repository, and launch runners with a single click. HomeRun handles download, registration, process management, log streaming, and resource monitoring — everything the official docs make you do by hand.

HomeRun runs on macOS, Windows, and Linux. Login startup is built in on macOS and Windows; Linux service integration is still manual.

• One-click runner setup — no shell scripts, no copy-pasting tokens
• Device Flow authentication — log in with your GitHub account via browser; no PAT required
• Batch runner creation — spin up multiple runners for the same repo in one step with live progress
• Unified dashboard — monitor all runners across all repos in one place
• Live log streaming — tail runner output in real time from the runner detail view
• Job tracking — current job progress with step-by-step status, estimated completion, and full job history per runner
• Runner metrics — CPU/RAM polling with WebSocket lifecycle events for immediate dashboard refresh
• Three execution modes — app-managed, persistent native (reattached after daemon crashes), or Docker container
• Auto-restart — crashed runners recover automatically (up to 3 attempts)
• Smart repo discovery — scan local workspace directories or your GitHub account for repos that use self-hosted runners
• Terminal UI — k9s-inspired TUI with info header, context-sensitive keybindings (F1-F4 tabs), repo search, and in-app login via Device Flow
• CLI mode — scriptable homerun --no-tui commands with colored output for automation
• Cross-platform — macOS (launchd), Windows (Registry Run + named-pipe IPC), and Linux; desktop notifications use the Tauri notification API
• Pre-commit hooks — enforces cargo fmt, cargo clippy, conventional commits, and Prettier on every commit

┌──────────────┐    ┌─────────┐
│  Tauri App   │    │   TUI   │     (thin clients)
└──────┬───────┘    └────┬────┘
       └────────┬────────┘
                │ IPC (REST + SSE + WebSocket)
       ┌────────┴────────┐
       │   homerund      │     (daemon — Unix socket or Windows named pipe)
       └────────┬────────┘
                │ spawns / monitors
      ┌─────────┼─────────┐
      │         │         │
   ┌──┴──┐   ┌──┴──┐   ┌──┴──┐
   │Run 1│   │Run 2│   │Run N│   (GitHub Actions runner processes)
   └─────┘   └─────┘   └─────┘

By default, runners are native child processes of the daemon. Each runner is an instance of the official GitHub Actions runner binary. Runners can also run inside a Docker container instead — see Docker Runners. All GitHub communication is outbound HTTPS. No inbound ports needed.

For the full architecture deep-dive (runner lifecycle, state machine, process management, auth flow), see docs/ARCHITECTURE.md.

New to self-hosted runners? See How Self-Hosted Runners Work for a primer on runner communication, permissions, security considerations, and what HomeRun automates.

1. Download the latest .dmg for your architecture from Releases:

   • Apple Silicon (M1/M2/M3/M4): HomeRun_<version>_aarch64.dmg
   • Intel: HomeRun_<version>_x86_64.dmg

2. Open the .dmg and drag HomeRun to Applications

3. Remove the macOS quarantine flag (required because the app is not yet code-signed):

   xattr -cr /Applications/HomeRun.app

4. Launch HomeRun — go to Settings > Startup > "Launch at login" to auto-start the daemon

The .dmg bundles the homerund daemon inside the app. Releases are automated via release-please — every merge to master with conventional commits triggers a Release PR with version bumps and changelog.

Homebrew publication is optional and only runs when the repository variable HOMEBREW_TAP_REPOSITORY and the TAP_GITHUB_TOKEN secret are configured. Until a tap is listed in the release notes, install the release assets above instead of assuming an upstream or third-party tap.

1. Download HomeRun_<version>_x64-setup.msi from Releases
2. Run the installer — it installs HomeRun and the homerund daemon
3. Launch HomeRun from the Start Menu — go to Settings > Startup > "Launch at login" to auto-start the daemon through the current user Registry Run entry

Download the latest .AppImage or .deb from Releases. The daemon and TUI are also published as an x86_64-unknown-linux-gnu tarball. Linux login startup is not installed automatically yet; launch homerund yourself or configure your preferred user service manager.

Prerequisites: Rust 1.75+ (rustup.rs), Node.js 20+. On macOS: Xcode Command Line Tools (xcode-select --install). On Windows: Visual Studio Build Tools with C++ workload.

git clone https://github.com/lgg/homerun.git
cd homerun

macOS:

make setup        # checks prerequisites, builds daemon + TUI, installs frontend deps

Windows:

# Daemon + TUI (release binaries)
cargo build --release -p homerund -p homerun

# MSI installer (copies the daemon sidecar, builds the frontend, and packages the MSI)
copy target\release\homerund.exe apps\desktop\src-tauri\binaries\homerund-x86_64-pc-windows-msvc.exe
cd apps\desktop
npm install
npx tauri build
# Output: apps\desktop\src-tauri\target\release\bundle\msi\HomeRun_<version>_x64_en-US.msi

Any platform (manual build):

# Daemon + TUI
cargo build --release -p homerund -p homerun

# Desktop app (requires Node.js — builds DMG on macOS, MSI + NSIS on Windows)
cargo build --release -p homerund
cp target/release/homerund$(rustc -vV | grep host | cut -d' ' -f2 | sed 's/^/-/') apps/desktop/src-tauri/binaries/
cd apps/desktop && npm install && npx tauri build

# Start the daemon (required by both the TUI and desktop app)
make dev                # or: ./target/release/homerund

# Launch the TUI (in another terminal)
make tui                # or: ./target/release/homerun

# Launch the desktop app (in another terminal)
make desktop            # or: cd apps/desktop && npm run tauri dev

# CLI mode (no interactive UI — useful for scripts)
homerun --no-tui list

On Windows (PowerShell):

.\target\release\homerund.exe         # start daemon
.\target\release\homerun.exe          # launch TUI
.\target\release\homerun.exe --no-tui list   # CLI mode

Note: The desktop app release bundles the daemon inside the app (DMG on macOS, MSI on Windows). When building from source, start the daemon separately before launching the desktop app.

Run make help (macOS) to see all available commands.

Runners dashboard — live status, CPU usage, and job progress at a glance

Repository scanning — find repos that use self-hosted runners across local and remote sources

Runner detail — live job steps, log streaming, and full job history

Daemon view — child processes, resource usage, and live daemon logs

Menu bar with runner status  |  Mini view for quick monitoring

TUI — k9s-inspired keyboard-driven interface with runner details and job history

The --no-tui flag disables the interactive terminal UI and prints plain text output instead. This is useful for scripting, automation, and quick status checks.

# List all runners with status, mode, and CPU usage
homerun --no-tui list

# Show overall status (daemon, auth, runner counts, system metrics)
homerun --no-tui status

# Scan a local workspace for repos using self-hosted runners
homerun --no-tui scan ~/workspace

# Scan your GitHub repos remotely (requires authentication)
homerun --no-tui scan --remote

# Combine local and remote scanning
homerun --no-tui scan ~/workspace --remote

# Authenticate and manage runners
homerun --no-tui login
homerun --no-tui add build-1 --repo owner/repo
homerun --no-tui add build --repo owner/repo --count 3
homerun --no-tui start build-1
homerun --no-tui stop build-1
homerun --no-tui restart build-1
homerun --no-tui set-mode build-1 app
homerun --no-tui remove build-1
homerun --no-tui logout

# Manage the daemon and login startup
homerun --no-tui daemon start
homerun --no-tui daemon stop
homerun --no-tui daemon restart
homerun --no-tui daemon autostart status
homerun --no-tui daemon autostart enable
homerun --no-tui daemon autostart disable

Priorities depend on user interest and verified platform demand.

macOS:

• macOS 13+ (Ventura or later)
• ARM64 or Intel Mac

Windows:

• Windows 10 or later
• x64

Linux:

• A modern x86_64 distribution with WebKitGTK 4.1 for the desktop app
• Manual daemon startup or a user-managed service

All platforms:

• A GitHub account

rm ~/.homerun/daemon.sock
homerund

homerund

See CONTRIBUTING.md for how to set up the dev environment, coding standards, and the PR process.

MIT © 2026 aGallea