Skip to content
Vulpine
Esc
↑↓navigate↵open⌘Jpreview
On this page

Developer install

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.

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: 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) 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:

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).
  • 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):

    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.

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

Was this page helpful?