# kunchenguid/runner-up architecture

> Architecture diagram of the GitHub repository kunchenguid/runner-up, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kunchenguid/runner-up
- Repository: https://github.com/kunchenguid/runner-up

## Overview

runner-up self-hosts GitHub Actions jobs across machines, giving each job a fresh container, VM, or account, with host execution also available. Administrators initialize setup and add machines; during service, the coordinator receives queued work through GitHub runner scale sets, applies ordering and resource rules, and launches a one-job runner through the machine’s agent. The agent provisions the configured execution environment and starts GitHub’s runner, which then works with GitHub directly. The graph preserves documented provider, recovery, setup-reload, and update capabilities. Some subsystem links are based on README descriptions because their implementation excerpts were not shown.

Main entry points: [`internal/coordinator/service.go`](https://github.com/kunchenguid/runner-up/blob/main/internal/coordinator/service.go) (Coordinator service), [`internal/agent/jobhost.go`](https://github.com/kunchenguid/runner-up/blob/main/internal/agent/jobhost.go) (One-job host), [`internal/config/config.go`](https://github.com/kunchenguid/runner-up/blob/main/internal/config/config.go) (Setup configuration), [`internal/agent/agent.go`](https://github.com/kunchenguid/runner-up/blob/main/internal/agent/agent.go) (Remote agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_admin["Setup and control"]
  node_cli["CLI commands<br/>[main.go]"]
  node_init["Setup and machines<br/>[init.go]"]
  node_config["Setup configuration<br/>[config.go]"]
end

subgraph group_coord["Coordinator"]
  node_sessions["GitHub sessions<br/>[github.go]"]
  node_service["Coordinator service<br/>[service.go]"]
  node_queue[("Waiting job state<br/>[queue.go]")]
  node_order["Order rules<br/>[rules.go]"]
  node_planner["Resource planner<br/>[plan.go]"]
  node_place_runner["Place runner<br/>[place.go]"]
end

subgraph group_execution["Machine execution"]
  node_agent["Remote agent<br/>[agent.go]"]
  node_job_server["One-job host<br/>[jobhost.go]"]
  node_linux_hosts["Linux providers<br/>[kvm_linux.go]"]
  node_mac_hosts["Mac providers<br/>[tart.go]"]
  node_windows_hosts["Windows providers<br/>[jobhost_windows.go]"]
  node_windows_service["Windows service<br/>[service_windows.go]"]
end

subgraph group_operations["Resilience and updates"]
  node_recovery["Restart recovery<br/>[snapshot.go]"]
  node_reload["Setup reload<br/>[reload.go]"]
  node_updates["Program updates<br/>[update.go]"]
end

node_admin(("Administrator"))
node_github(("GitHub Actions"))
node_scalesets["Runner scale sets"]
node_runner["GitHub job runner"]

node_admin -->|"runs commands"| node_cli
node_cli -->|"initializes setup"| node_init
node_init -->|"writes setup"| node_config
node_github -->|"queues jobs"| node_scalesets
node_scalesets -->|"delivers job messages"| node_sessions
node_sessions -->|"feeds coordination"| node_service
node_config -->|"configures coordinator"| node_service
node_service -->|"tracks waiting jobs"| node_queue
node_service -->|"parses order rules"| node_order
node_service -->|"plans assignments"| node_planner
node_service -->|"launches place runner"| node_place_runner
node_place_runner -->|"runs agent over SSH"| node_agent
node_agent -->|"starts one-job host"| node_job_server
node_job_server -.->|"provisions job environment"| node_linux_hosts
node_job_server -.->|"provisions job environment"| node_mac_hosts
node_job_server -.->|"provisions job environment"| node_windows_hosts
node_windows_hosts -.->|"requests privileged work"| node_windows_service
node_agent -->|"starts runner"| node_runner
node_runner -->|"works with GitHub"| node_github
node_service -.->|"restores running state"| node_recovery
node_config -->|"triggers setup changes"| node_reload
node_service -.->|"checks configured release"| node_updates

click node_cli "https://github.com/kunchenguid/runner-up/blob/main/cmd/main.go"
click node_init "https://github.com/kunchenguid/runner-up/blob/main/cmd/init.go"
click node_config "https://github.com/kunchenguid/runner-up/blob/main/internal/config/config.go"
click node_sessions "https://github.com/kunchenguid/runner-up/blob/main/internal/coordinator/github.go"
click node_service "https://github.com/kunchenguid/runner-up/blob/main/internal/coordinator/service.go"
click node_queue "https://github.com/kunchenguid/runner-up/blob/main/internal/coordinator/queue.go"
click node_order "https://github.com/kunchenguid/runner-up/blob/main/internal/plan/rules.go"
click node_planner "https://github.com/kunchenguid/runner-up/blob/main/internal/plan/plan.go"
click node_place_runner "https://github.com/kunchenguid/runner-up/blob/main/internal/coordinator/place.go"
click node_agent "https://github.com/kunchenguid/runner-up/blob/main/internal/agent/agent.go"
click node_job_server "https://github.com/kunchenguid/runner-up/blob/main/internal/agent/jobhost.go"
click node_linux_hosts "https://github.com/kunchenguid/runner-up/blob/main/internal/agent/kvm_linux.go"
click node_mac_hosts "https://github.com/kunchenguid/runner-up/blob/main/internal/agent/tart.go"
click node_windows_hosts "https://github.com/kunchenguid/runner-up/blob/main/internal/agent/jobhost_windows.go"
click node_windows_service "https://github.com/kunchenguid/runner-up/blob/main/internal/agent/service_windows.go"
click node_recovery "https://github.com/kunchenguid/runner-up/blob/main/internal/coordinator/snapshot.go"
click node_reload "https://github.com/kunchenguid/runner-up/blob/main/internal/coordinator/reload.go"
click node_updates "https://github.com/kunchenguid/runner-up/blob/main/internal/coordinator/update.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_init,node_config toneBlue
class node_sessions,node_service,node_queue,node_order,node_planner,node_place_runner toneAmber
class node_agent,node_job_server,node_linux_hosts,node_mac_hosts,node_windows_hosts,node_windows_service toneMint
class node_recovery,node_reload,node_updates toneRose
class node_admin,node_github,node_scalesets,node_runner toneIndigo
```

## Components

### Setup and control

- [CLI commands](https://github.com/kunchenguid/runner-up/blob/main/cmd/main.go): `cmd/main.go`
- [Setup and machines](https://github.com/kunchenguid/runner-up/blob/main/cmd/init.go): `cmd/init.go`
- [Setup configuration](https://github.com/kunchenguid/runner-up/blob/main/internal/config/config.go): `internal/config/config.go`

### Coordinator

- [GitHub sessions](https://github.com/kunchenguid/runner-up/blob/main/internal/coordinator/github.go): `internal/coordinator/github.go`
- [Coordinator service](https://github.com/kunchenguid/runner-up/blob/main/internal/coordinator/service.go): `internal/coordinator/service.go`
- [Waiting job state](https://github.com/kunchenguid/runner-up/blob/main/internal/coordinator/queue.go): `internal/coordinator/queue.go`
- [Order rules](https://github.com/kunchenguid/runner-up/blob/main/internal/plan/rules.go): `internal/plan/rules.go`
- [Resource planner](https://github.com/kunchenguid/runner-up/blob/main/internal/plan/plan.go): `internal/plan/plan.go`
- [Place runner](https://github.com/kunchenguid/runner-up/blob/main/internal/coordinator/place.go): `internal/coordinator/place.go`

### Machine execution

- [Remote agent](https://github.com/kunchenguid/runner-up/blob/main/internal/agent/agent.go): `internal/agent/agent.go`
- [One-job host](https://github.com/kunchenguid/runner-up/blob/main/internal/agent/jobhost.go): `internal/agent/jobhost.go`
- [Linux providers](https://github.com/kunchenguid/runner-up/blob/main/internal/agent/kvm_linux.go): `internal/agent/kvm_linux.go`
- [Mac providers](https://github.com/kunchenguid/runner-up/blob/main/internal/agent/tart.go): `internal/agent/tart.go`
- [Windows providers](https://github.com/kunchenguid/runner-up/blob/main/internal/agent/jobhost_windows.go): `internal/agent/jobhost_windows.go`
- [Windows service](https://github.com/kunchenguid/runner-up/blob/main/internal/agent/service_windows.go): `internal/agent/service_windows.go`

### Resilience and updates

- [Restart recovery](https://github.com/kunchenguid/runner-up/blob/main/internal/coordinator/snapshot.go): `internal/coordinator/snapshot.go`
- [Setup reload](https://github.com/kunchenguid/runner-up/blob/main/internal/coordinator/reload.go): `internal/coordinator/reload.go`
- [Program updates](https://github.com/kunchenguid/runner-up/blob/main/internal/coordinator/update.go): `internal/coordinator/update.go`

### Other components

- **Administrator**
- **GitHub Actions**
- **Runner scale sets**
- **GitHub job runner**

## Connections

- Administrator → CLI commands: runs commands (evidence: `README.md`)
- CLI commands → Setup and machines: initializes setup (evidence: `cmd/main.go`)
- Setup and machines → Setup configuration: writes setup (evidence: `cmd/init.go`)
- GitHub Actions → Runner scale sets: queues jobs (evidence: `README.md`)
- Runner scale sets → GitHub sessions: delivers job messages (evidence: `README.md`)
- GitHub sessions → Coordinator service: feeds coordination (evidence: `internal/coordinator/service.go`)
- Setup configuration → Coordinator service: configures coordinator (evidence: `README.md`)
- Coordinator service → Waiting job state: tracks waiting jobs (evidence: `internal/coordinator/service.go`)
- Coordinator service → Order rules: parses order rules (evidence: `internal/coordinator/service.go`)
- Coordinator service → Resource planner: plans assignments (evidence: `internal/coordinator/service.go`)
- Coordinator service → Place runner: launches place runner (evidence: `README.md`)
- Place runner → Remote agent: runs agent over SSH (evidence: `README.md`)
- Remote agent → One-job host: starts one-job host (evidence: `README.md`)
- One-job host → Linux providers: provisions job environment
- One-job host → Mac providers: provisions job environment
- One-job host → Windows providers: provisions job environment
- Windows providers → Windows service: requests privileged work
- Remote agent → GitHub job runner: starts runner (evidence: `README.md`)
- GitHub job runner → GitHub Actions: works with GitHub (evidence: `README.md`)
- Coordinator service → Restart recovery: restores running state
- Setup configuration → Setup reload: triggers setup changes (evidence: `README.md`)
- Coordinator service → Program updates: checks configured release
