---
title: "Developer install"
description: "Install Vulpine from the repository: clone, then just install. Installing with the signed apps instead is Install. It runs the steps below in order and ends with just doctor."
type: "living"
source: "docs/install-developer.md"
verified: "2026-11-14"
group: "Install and operate"
---

> **Living doc**, checked against the code 2026-11-14

The doctor is the judge. It prints one `OK`, `MISSING`, `WRONG` or `NOTE` line per check, with its fix. It exits 1
until no check is `MISSING` or `WRONG`. A `NOTE` is never a failure. The steps follow the doctor's order, so a
`MISSING` line names the step to rerun.

Every step is safe to rerun: it reports what exists and creates only what is missing. Bootstrap never overwrites a
file. No step prints or takes a secret on a command line.

## Before you start

- macOS on Apple silicon and 16 GB of memory. Below 16 GB the doctor's `memory:total` is a `NOTE`; less than 1 GiB
  available while it runs is `memory:available` `WRONG`.
- Disk: the doctor's floor is 3 GiB free on the home volume (`disk:home`), but the install itself writes more. A
  fresh install measured 5.7 GB before the TTS weights and before the gateway's own build: the clone (716 MB), the
  toolchain, cmake and ffmpeg without Homebrew (about 650 MB) and the Parakeet bundle
  (`benchmarks/results/fresh-install-20261106.md`). The TTS weights add 1.3 GB, and the release build adds its
  `target/` folder. That is about 7 GB with the TTS weights, before the build. The decision model, when you install
  it, adds its base model (1.8 GB) and a venv.
- Xcode Command Line Tools: `xcode-select --install`. They bring git, clang and codesign, which build the gateway.
- mise. Install it one of two ways, then open a new terminal so `just` is on `PATH`:
  - With [Homebrew](https://brew.sh): `brew install mise`, then `echo 'eval "$(mise activate zsh)"' >> ~/.zshrc`.
    Homebrew's installer needs an admin account and prints the `brew shellenv` line to add to `~/.zprofile`.
  - Without Homebrew, admin or `sudo`: `curl -fsSL https://mise.run | sh` installs `~/.local/bin/mise`. Then
    `echo 'eval "$(~/.local/bin/mise activate zsh)"' >> ~/.zshrc`.

  `mise install` in the checkout then installs the toolset, including Rust 1.91.0 and cargo-nextest 0.9.146. A
  non-interactive runner needs mise and its tools on its own `PATH`.
- The brain runs on Pi, the `pi` command on `PATH`. Install Pi yourself: Vulpine does not bundle it yet. After
  step 2, in the checkout, run
  `npm install -g @earendil-works/pi-coding-agent@1.4.0` (the `package.json` peer pin). mise's node puts it on mise's
  shims, which the gateway's LaunchAgent has on its `PATH`. The state config's `[brain] pi_command` names the command
  (default `pi`; a path is used as it is). The doctor's `command:pi` row prints its `--version`; a version other than
  the pin is a `NOTE`.

## The sequence

| # | step | the doctor's checks it satisfies |
|---|---|---|
| 1 | `git clone <the repository URL> ~/src/vulpine` and `cd` there (any path works; pass `--repo` to the doctor when it is not the current directory) | `checkout` |
| 2 | `mise trust && mise install`: the pinned toolchain and the Git hooks | `mise:*`, `command:python3` |
| 3 | `brew install ffmpeg cmake`, or without Homebrew `mise use -g cmake@4.1.2 ffmpeg@8.0.1` (Kitware's prebuilt cmake and conda-forge's ffmpeg, into your home). cmake builds the TTS server in step 8; the doctor does not check it | `command:ffmpeg` (`command:git` came with the Command Line Tools) |
| 4 | `just install`: runs steps 5, 6, 8, 9 and 10 (step 7 is by hand) | — |
| 5 | `mise exec -- bun install`, then `just build-gateway` (the release build, unsigned). Under `just install` it compiles here (`VULPINE_REMOTE_RELEASE=0`). A bare `just build-gateway` first asks the roll's build host, and compiles here when that host does not resolve | — (the next step needs the binary) |
| 6 | `just bootstrap` | `xdg:config`, `xdg:state`, `config:state`, `config:key:*`, `config:dir`, `config:file:*`, the gateway binary, the gateway LaunchAgent's plist |
| 7 | the Parakeet CoreML bundle (pinned file by file in `tools/install/models.toml` `[[parakeet.models]]`: 20 files, 632,169,729 bytes, about 630 MB). `vulpine models fetch parakeet --layout manifest` fetches every file into the doctor's folder under the local names. By hand: `FluidInference/parakeet-tdt-0.6b-v3-coreml` at the revision the doctor prints, straight into `~/Library/Application Support/Foxline/models/parakeet-v3-coreml/` (the four folders and the vocab sit directly in it) under the names `crates/coreml_stt/README.md` gives: `uvx --from huggingface_hub==0.36.0 hf download <repo> --revision <rev> --include 'Preprocessor.mlmodelc/*' 'Encoder_v2.mlmodelc/*' 'Decoder.mlmodelc/*' 'JointDecisionv3.mlmodelc/*' parakeet_vocab.json --local-dir <tmp>` (one `--include` with every pattern: a second `--include` replaces the first), then rename `Preprocessor`, `Encoder_v2`, `Decoder` and `JointDecisionv3` to `preprocessor`, `encoder`, `decoder` and `joint-decision.mlmodelc`. The doctor checks presence only. The pins are the bundle the reference gateway runs: upstream `Encoder_v2` (the int8 encoder, no `metadata.json`) and `JointDecisionv3`, with the base `Preprocessor`, `Decoder` and vocab | `model:parakeet-coreml`, `config:path:shadow_stt.bundle_dir` |
| 8 | `just models` (the TTS server and the decision model at their pinned digests; `--dry-run` first; about 1.3 GB of TTS weights). The decision model's run tarball defaults to a path on the operator's archive volume. Where it is absent, `just models` prints `SKIP  decision` and installs the TTS server alone: the decision model is optional, runs beside the turn, and `[decision_shadow]` is off by default. `just models --only decision --decision-run-source=<url or path>` installs it later (through `just install`, `--decision-run-source=<url>`: a `file://` URL, spaces as `%20`). A download that stops short is resumed (three tries) | `model:daf-weights` (in the checkout; `just aec-weights --fetch` if it is not), `model:tts-talker`, `model:tts-codec`, and the decision model when `[decision_shadow]` is enabled |
| 9 | `just secrets`, then put each value in the file it names. The time machine's password and the satellite's noise key are `IF` lines: their doctor rows are a `NOTE` until the time machine's tailer agent (or moraine) or a satellite bridge agent is installed | `secret:*` |
| 10 | `just doctor`. Before step 11 it is red on exactly the rows step 11 clears: `launchd:gateway`, `port:gateway`, `launchd:tts`, `port:tts` and the approval key the gateway mints at its first start | all of them |
| 11 | load the agents: `just bootstrap --load` (the gateway) and `just models --bootstrap` (the TTS server, the decision model); or run `just install --load` from the start | `launchd:gateway`, `port:gateway`, `launchd:tts`, `port:tts` |
| 12 | the grants holder, in the GUI login session: a signing identity once, `just adapters::install-grants`, then one Allow per grant ([the grants holder](/docs/install-and-operate/install#the-grants-holder)) | `grants:holder`, `grants:access` |

`vulpine models` (`crates/vulpine_cli`) fetches weights over the same pins:

- `vulpine models list` shows every pinned model with its size, state and license line.
- `vulpine models fetch` downloads the weights at their sha256. It resumes a partial download, refuses under a
  free-space floor and reuses a file already in the Hugging Face cache.
- `vulpine models verify` re-hashes them.

It fetches weights only. `just models` builds the TTS server, the decision model's venv and the LaunchAgents.
The default folder is `~/Library/Application Support/Vulpine/models`; `--layout manifest` writes into the folders
`just models` uses.

It reads `models.toml` and `staged-models.toml`. Each row says whether a fresh install needs it (`requires`:
`required`, `optional`, or `shadow` for the decision model) and whether it may be redistributed:

- `vulpine models fetch --requires required --dry-run --json` lists what a fresh install would download, file by
  file, with the bytes left, the free space and whether the disk floor passes. It moves nothing.
- `vulpine models fetch --requires required --json` downloads it. Progress goes to stderr, one JSON object per
  line: `model`, `file`, `bytes_done`, `bytes_total`, `state` (`queued`, `downloading`, `verifying`, `done`, `failed`)
  and `error` in words on failure. The summary is the one JSON object on stdout.
- `--source folder <path>` reads every file from a local folder (a drive, or another gateway's models folder in
  either layout). A file is accepted only at its pinned sha256.
- A row it cannot fetch is listed as `held` with the reason. A row whose sha256 is not yet pinned is
  `TODO-operator`, and the fetch exits 1 while such a row is selected. A model that may not be redistributed is
  converted locally: the sound detector with `tools/ambient/sound_detector_export.py`.

The small models the gateway opens in-process (CueLight-Nano first) are not part of `just models`. They are pinned
by sha256 in `tools/install/staged-models.toml`. `just ops::models-stage <name> <host> --source <file>` stages one,
verifies the bytes on the host and refuses a mismatch.

The same path as a flow, with the doctor's check ids each step clears:

```mermaid
flowchart TD
    S1["1 clone: checkout"] --> S2["2 mise trust, mise install: mise:*, command:python3"]
    S2 --> S3["3 ffmpeg and cmake, by brew or mise: command:ffmpeg"]
    S3 --> S5["5 bun install, just build-gateway"]
    S5 --> S6["6 just bootstrap: xdg:config, xdg:state, config:*, gateway binary, gateway plist"]
    S6 --> S7["7 Parakeet CoreML bundle, by hand: model:parakeet-coreml"]
    S7 --> S8["8 just models: model:daf-weights, model:tts-talker, model:tts-codec"]
    S8 --> S9["9 just secrets: secret:*"]
    S9 --> S10{"10 just doctor"}
    S10 -- "MISSING or WRONG beyond the loading rows: rerun the step it names" --> S6
    S10 -- "only the loading rows and the approval key left" --> S11["11 load the agents: launchd:gateway, port:gateway, launchd:tts, port:tts"]
    S11 --> S10b{"just doctor again: exit 0"}
    S10b --> S12["12 the grants holder, in the GUI session: grants:holder, grants:access"]
```

Steps 1 to 3, 7 and 12 and the Pi install are by hand. `just install --load` also runs step 11, which takes the
doctor to green. `just install --dry-run` prints the bootstrap and model plans and writes nothing.
`just bootstrap --home <dir>` puts everything under a scratch home; `--load` refuses a scratch home.

## What bootstrap creates

In the doctor's order, each reported `CREATE`, `LINK` or `EXISTS`:

- The XDG roots: `~/.local/state/vulpine/`, `~/.config/vulpine/` and `~/.cache/vulpine/` (0700). Where nothing
  exists at an older name, bootstrap links it to the vulpine root: `~/.local/state/foxline` and
  `~/.local/state/fox9` → `vulpine`, `~/.config/foxline` → `vulpine`, `~/.cache/foxline` and `~/.cache/fox9` →
  `vulpine`. A tool that names an old path writes into the vulpine root. `~/.config/fox9/codesign` holds the signing
  identity; it is not a root and is never touched. Below, `<state>` and `<config>` are the state and config roots.
- `<state>/bin/` (0700).
- `<state>/gateway.toml` (0600): the state config, generated from the gateway's config structs
  (`tools/install/skeletons/`). It lists every section and key `config.rs` has, in struct order, with the first
  paragraph of each doc comment and its default. A default under an XDG root is spelled with the vulpine root. The
  keys the doctor requires are set: `bind`, `[brain] pi_command`, `[loadouts] default_name`,
  `[shadow_stt] mode = "authority"`, `backend = "coreml-parakeet-v3"` and `bundle_dir`. Every other key is
  commented; remove the one `#` to set it.
- `<config>/fox9.toml` (0600): hosts and paths for the tools (`tools/repo/paths.py`), every line commented.
- `<state>/bin/foxline-voice-gateway`, copied from `target/release` when it is built.
- `<state>/gateway.env` (0600) and `~/Library/LaunchAgents/com.voidfab.fox9.gateway.plist`
  (`tools/install/launch_agent.py`, the same shape the roll writes). The plist runs the binary with `--config` and
  `--env-file` and sets only `HOME` and `PATH`. A plist is world-readable, so secrets go in the env file. The agent
  is loaded only with `--load`.
- The secrets' places: `<state>/approvals/` (0700), `~/.config/fox9-time-machine/env` and
  `<config>/satellite-kitchen.env` (0600), each with a commented `KEY=` line saying what to put there.


The gateway's default config file is `~/.config/vulpine/config.toml` on every platform, the directory the doctor's
`xdg:config` row names. A gateway started with an explicit `--config` (as the LaunchAgent does) writes no default
file. `~/Library/Application Support/Foxline` holds model assets (the Parakeet CoreML bundle, the emobank voices),
not config. Leave it where it is.

Bootstrap does not create the model servers (`just models`), the Parakeet bundle, the secrets' values or the docs
site. The docs site (`launchd:docs`, `port:docs`) is the nix host configuration's `fox9-docs` module: its rows are
`MISSING` on a nix-darwin host and a `NOTE` anywhere else.


## The six secrets

`just secrets` lists them in the doctor's order with the file, the mode and what is still missing. It reads presence
and modes only.

| secret | where | when |
|---|---|---|
| `VULPINE_GATEWAY_MUTATION_TOKEN` | nowhere | minted per brain by the gateway |
| `VULPINE_APPROVAL_KEY_FILE` | `<state>/approvals/key` (0600) | minted by the gateway at its first start |
| `VULPINE_RECEIVER_ACCESS_CLIENT_SECRET` | `<state>/gateway.env` | only when `VULPINE_RECEIVER_MCP_URL` is not loopback |
| `VULPINE_TM_CH_PASSWORD` | `~/.config/fox9-time-machine/env` (or moraine's `~/.moraine/config.toml`) | always |
| `VULPINE_STT_NATIVE_ADMISSION_TOKEN` | `<state>/gateway.env` | only with `VULPINE_STT_NATIVE_WORKER` |
| `ESPHOME_NOISE_KEY` | `<config>/satellite-<room>.env` (`tools/satellite/satellite.env.example`) | always |

**Secret files.** At start the gateway also reads `<config>/secrets/<NAME>`, one file per secret row of
`vulpine-env.toml` (not the minted mutation token). The file holds the value and one newline, mode 0600, in a 0700
folder. A file wins over the environment. A file the group or the world can read, a symlink, or a folder others can
write stops the start with the `chmod` to run. The doctor's `secret-files` row is `WRONG` until it is fixed. A roll
writes these files from `overlay.env`, because a plist inside a signed app cannot carry secrets.

**Every secret the roll carries.** The secret rows include the ntfy tokens (`VULPINE_NTFY_TOKEN`,
`VULPINE_NTFY_FLEET_TOKEN`). The `[[family]]` `VULPINE_WEBHOOK_?*_SECRET` covers each webhook source's secret: the
gateway reads any file in the folder named for one. `just ops::env-set <host> <KEY>` writes a secret key's file
directly. The roll says how many secrets it wrote to files, and names any plist key that looks like a secret but is
not a row (key names only, never a value). The doctor's `secret-files:plist` row is `OK` when the gateway plist on
disk holds no secret, and `WRONG` naming each one it carries. The gateway's start line `secret files read` gives
`launch_env=`, the secrets its launch environment held.


**Where the helpers come from.** The doctor's `runtime:helper:<name>` and `runtime:resource:<name>` rows say where
each core helper (vulpine-provider, vulpine-fleet, vulpine-audio, vulpine-call, vulpine-screen) and each resource
(the catalog root, the bundled extensions) resolved:

- `bundle`: Vulpine Gateway.app's `Contents/Helpers` or `Contents/Resources`;
- `tool_root`: `~/Library/Application Support/Vulpine/tools/<name>/current/bin/<name>`;
- `installed`: `<state>/bin/<name>`, `<state>/runtime-root`;
- `runtime_root_env`: `VULPINE_RUNTIME_ROOT`, which wins for resources;
- `checkout`.

A missing helper is a `NOTE` (`helper_missing`), and the config's own path still runs. With the grants holder
installed, the screen helper is the holder's own executable
(`~/Applications/VulpineGrants.app/Contents/MacOS/fox9grants`, run as `fox9grants screen`).

## The doctor as data: `--json` and `--profile app`

`vulpine-voice-gateway doctor --json` prints a typed report, `DoctorReport` in
`crates/protocol/src/doctor_report.rs`. Vulpine Gateway.app's first-run
window decodes it. The report has `ok`, `missing`, `wrong` and `note`; each row has `name`, `status`, `detail` and
`fix`. It also has these fields:

- `profile` (`repo` or `app`) and `version` (1) on the report;
- `family` on each row: `this_mac`, `runtime`, `models`, `services`, `secrets`, `grants`, `brain` or
  `worth_knowing`, the group the window shows it under;
- `words`: one plain sentence for a person on every row that is not `OK` (no paths, no commands; `fix` keeps those);
- `action`: what the app may do without asking, from a closed set: `{"kind": "open_settings", "pane": ...}` (the
  app's `brain`, `models` or `secrets` section, or System Settings' `login_items`, `privacy` or `storage`),
  `{"kind": "run_fix", "fix": {"verb": ...}}` (`register_agent` or `start_agent` with an `agent`, `request_grant`,
  `sign_in_brain`, `rerun`), `{"kind": "fetch_models", "ids": [...]}` (section names of `tools/install/models.toml`) or
  `{"kind": "none"}`. Nothing that writes config, touches a secret or deletes is an action: those rows carry words;
- `depends_on`: rows that must turn green first (`port:gateway` on `launchd:gateway`, `brain:provider` on
  `command:pi`, the approval key on `port:gateway`). A failing row whose dependency also fails is waiting, not a
  second fault.

`--profile app` is the view of someone who installed the app and has no checkout. The doctor picks it when it runs
from inside a `.app` bundle; `--profile repo` forces the developer view. Under `app`:

- no checkout is read (one found by walking up is ignored), and `checkout`, `mise:*`, `hook_offline` and
  `command:git` are absent;
- `command:ffmpeg` and `command:python3` are a `NOTE`: the gateway spawns neither, and each Python helper a config
  turns on has its own `helper:<section>` row;
- `command:pi` reads the configured `[brain] pi_command`, as the gateway does. The app does not bundle Pi yet.

`model:daf-weights` reads the copy inside the bundle (`Contents/Resources/aec_daf/localvqe-daf-v2xp-2.7k-f32.bin`),
else the checkout's. Under `app` with neither it is `OK`: the weights are compiled into the gateway, and
`crates/aec_daf/build.rs` refuses any other size or digest.

`brain:provider` asks whether Pi's sign-in names at least one model provider. It reads the keys of `auth.json` and
of `models.json`'s `providers` in Pi's agent folder (the gateway LaunchAgent's `PI_CODING_AGENT_DIR`, else
`~/.pi/agent`), and the provider key names in the gateway's env. It reads names only, never a value. It prints an
id only when it is a short lowercase word, and counts the others. No provider is `MISSING` with the `sign_in_brain`
action: the first turn fails until there is one.

## The signature row's host markers

The doctor's `gateway:signature` row reads the gateway LaunchAgent's binary with `codesign`. A gateway built on
your own Mac is ad-hoc signed: a `NOTE`, never a failure, and it runs as it is. A Developer ID build keeps the macOS
privacy grants across rebuilds. Two hand-written marker files under `~/.config/vulpine/` make the row strict, so an
ad-hoc or unsigned gateway reads `WRONG`. Each counts only when its first word is not empty:

- `sign-host` holds the host label of the Mac that signs releases. The release recipes read it
  too ([release](/docs/install-and-operate/release)).
- `release-only` marks a Mac that runs only rolled Developer ID builds, such as the gateway host. The fix on
  `WRONG` is to roll a signed build there.

Another team's signature reads `WRONG` on every host. There is no environment variable for either marker.

## After the doctor is green

`just bootstrap` writes `VULPINE_TTS_HTTP_URL=http://127.0.0.1:8850` into a new `<state>/gateway.env`: the TTS server
`just models` installs. With it set the gateway runs its own TTS worker, which needs nothing else. Bootstrap never
edits an existing env file; it prints a `NEXT env:VULPINE_TTS_HTTP_URL` line when the file lacks the setting.

One setting only for the Python TTS worker, which runs when no TTS server is set or with
`VULPINE_TTS_NATIVE_WORKER=0`:

- `VULPINE_QWEN_UV`. That worker refuses to start without it, and refuses a `uv` the user can write to (the
  Homebrew one on `PATH`). Install an immutable copy and name it (the doctor's `runtime:qwen-uv` row checks it):

  ```bash
  sudo install -d -o root -g wheel -m 0755 /Library/Fox9 /Library/Fox9/bin
  sudo install -o root -g wheel -m 0555 "$(command -v uv)" /Library/Fox9/bin/uv
  echo 'VULPINE_QWEN_UV=/Library/Fox9/bin/uv' >> ~/.local/state/vulpine/gateway.env
  ```

  Without a TTS server the Python worker loads Qwen3-TTS through MLX itself.

Restart the gateway agent after a change (`launchctl kickstart -k gui/$(id -u)/com.voidfab.fox9.gateway`).
Releases and rolls: [release and rollback](/docs/install-and-operate/release).


## Optional: the Wyoming fallback TTS

`just install` leaves this step out. When Vulpine's Wyoming TTS server (`tools/wyoming_tts/server.py`, the voice Home
Assistant uses) refuses a request as `busy` or fails it, it can hand that announcement to a second Wyoming engine
instead of dropping it: kokoro-onnx with the `af_heart` voice on `127.0.0.1:10210`
(runtime/wyoming-kokoro). It takes about 0.55 GB on disk and 578 MB peak
RAM.

1. `just models --only wyoming-kokoro --dry-run` prints the two model fetches with their sha256 and writes nothing.
2. `just models --only wyoming-kokoro --bootstrap` writes the venv, the models and the LaunchAgent
   `com.voidfab.vulpine.wyoming-kokoro` under `<state>/wyoming-kokoro`, then loads the agent.
3. `/usr/bin/python3 runtime/wyoming-kokoro/check.py` renders one line and prints its duration and RTF. It plays
   nothing.
4. Add `--fallback 127.0.0.1:10210` to the Wyoming TTS server's command line. On a nix-darwin host that is the
   host configuration's `fox9-wyoming-tts` module.

The doctor's `wyoming:kokoro` row is a `NOTE` while the agent is absent. It is `OK` once the agent is loaded and the
port answers a Wyoming `describe`. Rollback: `launchctl bootout gui/$(id -u)/com.voidfab.vulpine.wyoming-kokoro`,
remove the plist and `<state>/wyoming-kokoro`, and drop the `--fallback` flag.


## See also

- [README](/docs/install-and-operate/what-vulpine-is) - what Vulpine is.
- [Architecture](/docs/the-voice-path/architecture) - one turn end to end.
- [release and rollback](/docs/install-and-operate/release) - releases and rolls after the install.
- ADR 0041 and ADR 0042 - the install path and the roots.
