You are reading the docs for v0.0.1-beta-7. Latest (main) →

Configuration

View .mdEdit on GitHub

~/Library/Application Support/Kinhin/config.yaml — write the commented starter file with kinhin config init. Key fields:

FieldMeaning
versionConfig schema version (optional, absent = 1). Unknown keys are an error at version 1; see Validation
accountsThe forges this fleet serves, each with its own token: name, forge (github, gitlab, gitea, forgejo; azuredevops is experimental; buildkite and bitbucket are planned and not supported yet), scope (owner/name for one repo, or a bare org name for org-level runners that serve every repo in the organization; PAT needs org runner-admin permission), and instance for self-hosted forges — see Forges. There is no top-level repo: key
labelsJobs must request all of these to be picked up
min_runners / max_runnersScaling bounds (in VMs). Defaults 0 / 2. min_runners is one floor for the whole fleet: busy instances count toward it and the instances it adds run on runtimes.default (see Scaling)
image_min_idle / min_idleRegistered, idle runners kept at all times so the forge always lists one: image_min_idle for the top-level image:, min_idle on each images: entry, on container: and on docker:. A busy runner does not count, so a replacement starts as soon as one takes a job. Default 0 (off); see Idle runners per pool and image
containerLinux jobs in Apple container microVMs: image, base_image, cpus (4), memory_gb (8), labels, fleet_labels, min_idle, docker (false; true runs Docker inside each runner, pulling Docker Hub images through kinhin's cache, { cache: false } runs Docker without the Docker Hub cache, and { build_cache: true } keeps each runner's Docker images and build cache between jobs, see Docker build cache), registry_cache_ttl_hours (336; how long the Docker Hub cache keeps a layer, 0 = never expires, see Expiry and broken entries), flags (extra container run arguments), platform (linux/arm64; linux/amd64 runs x86_64 runners under Rosetta, registered with x64) and pools (named pools: each takes those keys plus max, the top-level ones are their defaults). See apple/container and Several container pools
enabled (on container, container.pools.NAME, docker) / runtimes.tart.enabledtrue. false keeps the pool's settings but takes it out of routing, scheduling and the Fleet page; running instances drain. The default pool and pools a route names cannot be disabled. See Turning a pool off
warm_pool / warm_max_age_minutesPre-booted, unregistered Tart VMs kept for instant pickup (per image: also warm_pool on each images: entry), and when to recycle them. Defaults 0 (off) / 60
runners_per_vmRunner processes per VM — many-to-one job density (1–8; 1 = one job per VM, most isolated)
poll_intervalSeconds between forge polls (≥ 5, default 20)
vm.cpu / vm.memory_gb / vm.ephemeralPer-VM shape
imageTart image cloned per runner (tahoe-base after prepare)
base_imageWhat image prepare starts from: a pre-configured tart image (ghcr.io/cirruslabs/…, macOS or Linux), digest-pinned (ref@sha256:… — see kinhin image digest), or a local VM name (e.g. one made with image prepare --linux); absent = the default macOS base. A Linux base turns the Tart pool into Tart Linux VMs
provision_scriptHost script baked into the image by image prepare (your toolchains; see Toolchains)
projectsPer-repo rules (pattern, repo_file, toolchains, share_cache): repo_file: true lets a repo's .kinhin/config.yml (or older .kinhin.yml) choose its toolchains; toolchains declares them here instead. There is no global toolchains: (see Per-project toolchains)
toolchain_cacheHost download-cache expiry: auto_prune, max_age_days (30), max_gb (50). max_project_images (8) caps derived images
tart_home / container_app_root / registry_cache_path / toolchain_cache_pathWhere the large trees live: Tart's home (TART_HOME, default ~/.tart), Apple container's app root (container system start --app-root), the Docker Hub cache and the toolchain cache. Absolute paths, all optional; a missing key keeps the default. kinhin checks the volume before it starts anything there. See Storage on another volume
reserve.cpu / reserve.memory_gbHost headroom kept free
reserve.disk_gbHost disk (GB) kept free (default 10)
healingThe healing agent: enabled (true), auto (safe, or none to approve every fix), ai (auto or off), max_attempts (3, 1–10). See The healing agent
alertsOpt-in outbound alerts, off by default: enabled, webhooks (list of name, url, format (generic, slack, discord, ntfy), headers_keychain, min_severity, events (disk, credentials, queue, spawn-backoff, orphans, startup; omitted = all), notify_on_resolve), min_severity (warning), cooldown_seconds (3600), notify_on_resolve (true). The old single webhook: is read as one webhook named default. See Alerts
telemetryOpt-in observability, off by default: enabled, endpoint, protocol (http/protobuf or grpc), export_interval_seconds (60), signals, resource_attributes, prometheus_listen, job_attributes, log_format (text or json), sampling_ratio (1), log_level (info), headers_keychain, ca_file, persist (false). Standard OTEL_* variables override it. See Telemetry

Scale-set mode (GitHub, opt-in): an accounts: entry may carry scale_set: with name (the scale set's name — what workflows put in runs-on:; kinhin adds -container, -docker and -<image> sets for the other pools and named images) and runner_group (where the scale set lives; GitHub's built-in group is Default, spelled exactly that way, and kinhin's lookup is case-sensitive). It swaps that account's demand from the REST poll to the message API — see Forge support and Troubleshooting scale sets.

The effective concurrency cap is min(max_runners, (cores − reserve.cpu) / vm.cpu, (RAM − reserve.memory_gb) / vm.memory_gb, free_disk / disk_per_vm) — disk_per_vm is your disk_gb when set, else a runtime default (50 GB for Tart VMs, 8 GB for Linux container slots). The scaler re-checks free disk before every spawn and holds new VMs when the disk would dip below reserve.disk_gb plus one instance's footprint. kinhin doctor prints the result and the binding constraint.

Storage on another volume#

Tart VMs, Apple container's images and kernels, the Docker Hub cache and the toolchain cache are large. On a Mac whose internal disk is tight, move them to an external volume with four optional keys:

tart_home: /Volumes/Storage/tart                          # TART_HOME (default ~/.tart)
container_app_root: /Volumes/Storage/container            # container system start --app-root
registry_cache_path: /Volumes/Storage/kinhin/registry-cache
toolchain_cache_path: /Volumes/Storage/kinhin/toolchain-cache
  • Every start path uses them. kinhin exports TART_HOME for every tart it runs and writes it into the daemon's LaunchAgent (kinhin daemon install); a reinstall keeps the LaunchAgent's other variables. Every container system start (setup, healing, image builds) passes --app-root, and kinhin looks for the container kernel under that root. No symlinks or hand-edited LaunchAgents are needed.
  • The volume is checked first. Before the daemon starts, and before Tart, the container system or either cache starts, kinhin checks that each configured path's volume is mounted (a path under /Volumes/<name> needs that volume) and that the volume has ownership enabled. If not, it starts nothing and says which volume and what to do. It never falls back to the internal default path. Under launchd the daemon retries, so it starts once the volume is mounted.
  • Ownership must be on. External APFS volumes often ship with ownership ignored, and launchd then rejects the container service files under the app root (bad ownership/permissions). Run sudo diskutil enableOwnership /Volumes/Storage. Files copied there before you enabled ownership can still be rejected even with the right owner and mode; copy them again afterwards. See Troubleshooting.
  • Moving existing data. Stop the fleet (kinhin stop, or quit the app), stop the container system (container system stop), enable ownership on the volume, then copy each tree to its new path (for example ditto ~/.tart /Volumes/Storage/tart). Set the keys, then start again. Remove a leftover symlink or a hand-added TART_HOME first, so only the config decides.
  • Keep a link at Apple container's old app root. Apple container records absolute paths under the app root it unpacked an image in, so a copied image still points at ~/Library/Application Support/com.apple.container/…. Without that path, every container start fails with Code=260 … "snapshot" … no such file. After copying the app root, leave a symlink at the old path pointing at the new root (for example ~/Library/Application Support/com.apple.container → /Volumes/Storage/container) until every image has been pulled or baked again on the new root.
  • Already running elsewhere. A container system that is already running keeps the app root it started with, so kinhin starts no container while that root is not container_app_root:; run container system stop once no runner is busy (it stops every container). A running Docker Hub cache keeps its old directory until it stops; a stopped one is recreated on registry_cache_path:.
  • kinhin config validate rejects an empty, relative (~/… included), or nested path, and a path that names a file. kinhin doctor lists each configured path, its volume and the preflight result; a path that fails makes the report not ready.
  • The config decides TART_HOME in the LaunchAgent: after you remove tart_home:, the next kinhin daemon install removes it too (also one added by hand). If the config does not load, the install keeps the LaunchAgent's variables as they are.

Validation and defaults#

config.yaml is validated when it loads, and errors name the key as written in the file (vm.memory_gb, not an internal name).

  • Unknown keys are an error. A typo such as max_runner: is rejected with a suggestion (did you mean 'max_runners'?) instead of silently falling back to the default. The check covers the top level and the nested sections (vm, reserve, container, docker, runtimes, images, accounts, projects, toolchain_cache, healing, telemetry, alerts). Top-level keys that start with x- are ignored, so you can keep notes or YAML anchors there.
  • version is optional and defaults to 1. A file that declares a newer version than your kinhin understands is still read: keys it does not know are logged and ignored, and the keys it does know are validated as usual. That lets an older build run a config written for a newer one.
  • Ranges. vm_boot_timeout must be 30–3600 seconds and token_ttl 60–3600 seconds, on top of the bounds on poll_interval, runners_per_vm and the resource keys.
  • container.flags must not set what kinhin sets itself (--name, --rm, --detach, --cpus, --memory, --platform and --arch (both come from platform), --os, --help, --version and a bare --, in long, --flag=value and short forms), and each element must be non-empty with the first one a flag. See Extra container run flags.
  • container.pools. Pool names are lowercase letters, digits and inner - (at most 32 characters); every pool needs an image (its own or container.image); no two pools may have the same labels and the same platform, and pools that share an image must share its base_image and platform; platform is linux/arm64 or linux/amd64; max must be at least 1 and the pool's min_idle; each pool's keys are checked like the same keys on container:. See Several container pools.
  • min_idle. Every min_idle (and image_min_idle) must be 0 or more and fit in max_runners, each image's together with its warm_pool, and all of them together too; docker.min_idle must also fit in docker.max_slots. The values on macOS Tart images may add up to at most 2, Apple's limit of macOS VMs per Mac. All of them apply on reload without restarting the engine.
  • Defaults come from one place, so omitting a key and the starter template agree: min_runners: 0, max_runners: 2, runners_per_vm: 1, poll_interval: 20, vm: {cpu: 4, memory_gb: 8}, reserve: {cpu: 2, memory_gb: 4, disk_gb: 10}.
  • Runtime names in runtimes: (default, budget, routes[].runtime) are tart, appleContainer, docker and host; anything else is rejected with a suggestion.

Older configs#

The top-level repo:, gitea: and forgejo: keys and the global toolchains: section no longer load; the error names the replacement (an accounts: entry, a projects: entry, toolchain_cache:). ConfigMigrator in KinhinKit translates them as text without writing the file, keeping comments elsewhere in it.

Moving to another Mac#

Copy a working setup to a second Mac (or a new one) with one command per side:

kinhin config export kinhin-config.yaml          # on the Mac that has the config
kinhin config import kinhin-config.yaml          # on the new Mac

Or in one step over SSH: kinhin config export | ssh other-mac kinhin config import - --yes.

  • Tokens are not copied. They stay in each Mac's Keychain. The import lists every account that has no token on the new Mac, with the kinhin auth set --account NAME command to store it.
  • Images are not copied. Each Mac bakes its own; kinhin setup status shows which to prepare.
  • Nothing is written until the file validates. With no config yet the import writes it; an existing config is only replaced with --yes, and the old one is kept as config.yaml.bak.
  • The export starts with three # kinhin export: comment lines naming the source Mac; the import drops them. A tart_path that does not exist on the new Mac is reported as a warning.
  • A running fleet picks up the new config after you restart the app or the daemon.

Live reload#

Config edits made from the app's Advanced → Routing tab (routes, budget split, labels) reach a running fleet live via reload_config — no restart; a running fleet simply re-buckets demand on its next poll. Routes can also be edited from the terminal:

kinhin runtimes route add acme/api appleContainer
kinhin runtimes route remove acme/api

Every pane edit rewrites only the relevant section of config.yaml — comments elsewhere are preserved — and lands only if the updated file still passes the engine's full config validation.