# Configuration

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

| Field                                      | Meaning                                                                                                                                                                                                                                                                                                                                                      |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `version` | Config schema version (optional, absent = `1`). Unknown keys are an error at version 1; see [Validation](#validation-and-defaults) |
| `accounts` | The 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](https://kinhin.dev/guide/forges.md#multiple-accounts). There is no top-level `repo:` key |
| `labels`                                   | Jobs must request _all_ of these to be picked up                                                                                                                                                                                                                                                                                                             |
| `min_runners` / `max_runners` | Scaling 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](https://kinhin.dev/guide/scaling.md#min_runners-a-fleet-wide-floor-not-an-idle-one)) |
| `image_min_idle` / `min_idle` | Registered, 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](https://kinhin.dev/guide/scaling.md#idle-runners-per-pool-and-image) |
| `container` | Linux 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](https://kinhin.dev/guide/runtimes.md#docker-hub-cache), and `{ build_cache: true }` keeps each runner's Docker images and build cache between jobs, see [Docker build cache](https://kinhin.dev/guide/runtimes.md#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](https://kinhin.dev/guide/runtimes.md#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](https://kinhin.dev/guide/runtimes.md#applecontainer) and [Several container pools](https://kinhin.dev/guide/runtimes.md#several-container-pools) |
| `enabled` (on `container`, `container.pools.NAME`, `docker`) / `runtimes.tart.enabled` | `true`. `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](https://kinhin.dev/guide/runtimes.md#turning-a-pool-off) |
| `warm_pool` / `warm_max_age_minutes` | Pre-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_vm`                           | Runner processes per VM — many-to-one job density (1–8; 1 = one job per VM, most isolated)                                                                                                                                                                                                                                                                   |
| `poll_interval` | Seconds between forge polls (≥ 5, default 20) |
| `vm.cpu` / `vm.memory_gb` / `vm.ephemeral` | Per-VM shape                                                                                                                                                                                                                                                                                                                                                 |
| `image`                                    | Tart image cloned per runner (`tahoe-base` after prepare)                                                                                                                                                                                                                                                                                                    |
| `base_image`                               | What `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](https://kinhin.dev/guide/runtimes.md#tart-linux-vms) |
| `provision_script`                         | Host script baked into the image by `image prepare` (your toolchains; see [Toolchains](https://kinhin.dev/guide/toolchains.md))                                                                                                                                                                                                                                                   |
| `projects`                                 | Per-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](https://kinhin.dev/guide/toolchains.md#per-project-toolchains))                                                                |
| `toolchain_cache`                          | Host 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_path` | Where 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](#storage-on-another-volume) |
| `reserve.cpu` / `reserve.memory_gb`        | Host headroom kept free                                                                                                                                                                                                                                                                                                                                      |
| `reserve.disk_gb`                          | Host disk (GB) kept free (default 10)                                                                                                                                                                                                                                                                                                                        |
| `healing`                                  | The 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](https://kinhin.dev/guide/healing.md)                                                                                                                                                                              |
| `alerts`                                   | Opt-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](https://kinhin.dev/guide/alerts.md) |
| `telemetry`                                | Opt-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](https://kinhin.dev/guide/telemetry.md) |

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](https://kinhin.dev/guide/forges/github.md#scale-set-mode-in-kinhin) and
[Troubleshooting scale sets](https://kinhin.dev/guide/forges/github.md#scale-set-troubleshooting-kinhin-side).

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:

```yaml
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](https://kinhin.dev/guide/troubleshooting.md).
- **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](https://kinhin.dev/guide/runtimes.md#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](https://kinhin.dev/guide/runtimes.md#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:

```bash
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:

```bash
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.
