runpool.conf.example

# runpool configuration: copy to ~/.config/runpool/config
#
# Everything here has a working default, so an empty file is a valid config.
# This lives outside the repository because it is the only place installation
# specifics belong; a checkout should carry none of them.
#
# Keep it mode 0600. RUNPOOL_WEBHOOK_TOKEN below is a secret, and the default
# umask would otherwise leave this readable by every user on the machine:
#   chmod 600 ~/.config/runpool/config

# Required state: runner installations and credentials, pool definitions,
# pause state and generated launch agents. Defaults to macOS Application
# Support. Keep it off any synced or shared volume.
# RUNPOOL_BASE="${HOME}/Library/Application Support/runpool"

# Regenerable data: job work trees, downloaded actions and tools, per-runner
# package caches, temp directories and runner archives. Defaults to Caches.
# RUNPOOL_CACHE_DIR="${HOME}/Library/Caches/runpool"

# The pools `runpool apply` reconciles this machine to. Defaults to
# ~/.config/runpool/pools; see runpool.pools.example. Unlike everything else
# here it holds no secrets and nothing machine-specific, so it is the one file
# worth carrying to a second machine. `runpool apply --file PATH` overrides it
# for a single run.
#
# Derived from XDG_CONFIG_HOME rather than from this file's own directory, so
# pointing RUNPOOL_CONFIG at /dev/null does not also lose the pools file. The
# corollary is that neither RUNPOOL_CONFIG nor RUNPOOL_BASE isolates this one.
# RUNPOOL_POOLS_FILE="${HOME}/.config/runpool/pools"

# Prefix for every launch-agent label this installation owns. Change it only if
# two installations must coexist on one machine.
# RUNPOOL_LABEL_NS="runpool"

# Stand a pool down after this many seconds with nothing running anywhere.
# Restarting a runner takes seconds and needs no re-registration, so a short
# grace only avoids churn between rapid pushes in one working session.
# RUNPOOL_IDLE_SECS=1200

# How long after a pool starts before its runners are expected to have reached
# GitHub. A runner opens its connection a second or two after launchd starts
# it, and inside that window a healthy pool looks exactly like a broken one:
# agents running locally, nothing online at GitHub. Reachability is not judged
# until the window passes. Raise it if this machine starts runners slowly.
# RUNPOOL_SETTLE_SECS=120

# How many fruitless wake cycles a queued run is given before it stops counting
# as work. A run can sit `queued` for ever with no jobs attached, and without
# this the pool wakes for it, finds nothing, idles out and wakes again for as
# long as the run exists. `doctor` names any run this is holding down, and
# `status` says how many there are. Set to 0 to disable the guard.
# RUNPOOL_STUCK_WAKES=3

# Load threshold exposed in structured status. It does not send an alert.
# Defaults to six times core count, which sits clear of ordinary work.
# Raise this as the pool grows: a busy pool of N runners reaches about N times
# core count on its own, so the default may stop distinguishing exceptional
# contention once a pool passes six runners.
# RUNPOOL_LOAD_WARN=84

# Stamp machine state into every job, so a contended failure and a real defect
# stop looking identical in the log. Absolute path; unset means no hook.
# RUNPOOL_JOB_HOOK="${HOME}/src/runpool/contrib/job-hook.sh"

# Record one line per job to <base>/telemetry/jobs.jsonl, so `runpool stats` can
# answer how many runners this machine should actually have. Timings and machine
# state only, nothing about the code, and it never leaves the machine.
# Needs RUNPOOL_JOB_HOOK set as well.
# RUNPOOL_TELEMETRY=1

# Where to send anything worth reporting. A command reading one JSON object on
# stdin. Unset means runpool reports nothing and works exactly as well.
# RUNPOOL_NOTIFY_CMD="${HOME}/src/runpool/contrib/notify-webhook.sh"
# RUNPOOL_WEBHOOK_URL="https://example.com/alert"
# RUNPOOL_WEBHOOK_TOKEN="..."