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:totalis aNOTE; less than 1 GiB available while it runs ismemory:availableWRONG. -
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 itstarget/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
justis onPATH:- With Homebrew:
brew install mise, thenecho 'eval "$(mise activate zsh)"' >> ~/.zshrc. Homebrew’s installer needs an admin account and prints thebrew shellenvline to add to~/.zprofile. - Without Homebrew, admin or
sudo:curl -fsSL https://mise.run | shinstalls~/.local/bin/mise. Thenecho 'eval "$(~/.local/bin/mise activate zsh)"' >> ~/.zshrc.
mise installin 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 ownPATH. - With Homebrew:
-
The brain runs on Pi, the
picommand onPATH. Install Pi yourself: Vulpine does not bundle it yet. After step 2, in the checkout, runnpm install -g @earendil-works/pi-coding-agent@1.4.0(thepackage.jsonpeer pin). mise’s node puts it on mise’s shims, which the gateway’s LaunchAgent has on itsPATH. The state config’s[brain] pi_commandnames the command (defaultpi; a path is used as it is). The doctor’scommand:pirow prints its--version; a version other than the pin is aNOTE.
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 listshows every pinned model with its size, state and license line.vulpine models fetchdownloads 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 verifyre-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 --jsonlists 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 --jsondownloads it. Progress goes to stderr, one JSON object per line:model,file,bytes_done,bytes_total,state(queued,downloading,verifying,done,failed) anderrorin 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
heldwith the reason. A row whose sha256 is not yet pinned isTODO-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 withtools/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/foxlineand~/.local/state/fox9→vulpine,~/.config/foxline→vulpine,~/.cache/foxlineand~/.cache/fox9→vulpine. A tool that names an old path writes into the vulpine root.~/.config/fox9/codesignholds 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 keyconfig.rshas, 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"andbundle_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 fromtarget/releasewhen 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--configand--env-fileand sets onlyHOMEandPATH. 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/envand<config>/satellite-kitchen.env(0600), each with a commentedKEY=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’sContents/HelpersorContents/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(repoorapp) andversion(1) on the report;familyon each row:this_mac,runtime,models,services,secrets,grants,brainorworth_knowing, the group the window shows it under;words: one plain sentence for a person on every row that is notOK(no paths, no commands;fixkeeps those);action: what the app may do without asking, from a closed set:{"kind": "open_settings", "pane": ...}(the app’sbrain,modelsorsecretssection, or System Settings’login_items,privacyorstorage),{"kind": "run_fix", "fix": {"verb": ...}}(register_agentorstart_agentwith anagent,request_grant,sign_in_brain,rerun),{"kind": "fetch_models", "ids": [...]}(section names oftools/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:gatewayonlaunchd:gateway,brain:provideroncommand:pi, the approval key onport: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_offlineandcommand:gitare absent; command:ffmpegandcommand:python3are aNOTE: the gateway spawns neither, and each Python helper a config turns on has its ownhelper:<section>row;command:pireads 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-hostholds the host label of the Mac that signs releases. The release recipes read it too (release).release-onlymarks a Mac that runs only rolled Developer ID builds, such as the gateway host. The fix onWRONGis 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 auvthe user can write to (the Homebrew one onPATH). Install an immutable copy and name it (the doctor’sruntime:qwen-uvrow 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.envWithout 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.
just models --only wyoming-kokoro --dry-runprints the two model fetches with their sha256 and writes nothing.just models --only wyoming-kokoro --bootstrapwrites the venv, the models and the LaunchAgentcom.voidfab.vulpine.wyoming-kokorounder<state>/wyoming-kokoro, then loads the agent./usr/bin/python3 runtime/wyoming-kokoro/check.pyrenders one line and prints its duration and RTF. It plays nothing.- Add
--fallback 127.0.0.1:10210to the Wyoming TTS server’s command line. On a nix-darwin host that is the host configuration’sfox9-wyoming-ttsmodule.
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 - what Vulpine is.
- Architecture - one turn end to end.
- release and rollback - releases and rolls after the install.
- ADR 0041 and ADR 0042 - the install path and the roots.