Install
Install Vulpine on a Mac with its two signed apps. Open Vulpine Gateway.app: its setup window does the rest, in order, and ends when the doctor is green. Nothing is built on your Mac and you need no terminal.
Living doc, checked against the code 2026-11-14
Building from the repository instead (a clone, mise, just install) is the
developer install. It still works, and the doctor judges both the same way.
Before you start
- A Mac with Apple silicon. 16 GB of memory is the target; below it the gateway still runs and the doctor’s
memory:totalrow is aNOTE. - About 5 GB free on the home volume: setup downloads 1.9 GB of models and keeps 3 GiB free (the doctor’s
disk:homefloor). - The two apps from the release page, dragged into Applications:
Vulpine.app(the client you talk to) andVulpine Gateway.app(the host that runs the gateway). - An account with one model provider for Pi, the agent runtime the brain runs on. Setup installs Pi; you sign in.
The sequence
The first launch of Vulpine Gateway.app opens its setup window by itself. A finished setup never opens it again;
the app menu’s Set Up Vulpine Gateway… opens it whenever you want, and Setup’s Run setup again walks it
from the start (what is installed stays).
The window shows its steps in a rail. The core steps run themselves in this order and save their progress after each one, so you can quit at any point and the next launch carries on. Each step lists the doctor’s checks it turns green.
| # | step | what setup does | download | who finishes it | the doctor’s checks |
|---|---|---|---|---|---|
| 1 | This Mac | reads the chip, memory, free disk, macOS and the ports 8780 and 8850 | none | setup | disk:home, memory:total, memory:available |
| 2 | Folders and settings | the state, config and cache folders (yours only) and the gateway’s settings file from the app’s template; it never overwrites one that exists | none | setup | xdg:state, xdg:config, config:* |
| 3 | Gateway environment | the gateway’s environment file, written only with variables the gateway declares (vulpine-env.toml), each checked against its type, never a secret: the voice server’s address, and the immutable uv when this Mac has one. A line you already wrote is kept |
none | setup | runtime:qwen-uv, secret-files |
| 4 | Speech and voice models | downloads the required models, each file checked against its pinned sha256; a stopped download resumes | Parakeet speech recognition 632 MB, the Qwen3 voice 1.28 GB, CueLight end-of-speech 3 MB: 1.9 GB | setup | model:* |
| 5 | Gateway service | registers the gateway from inside the app as a login item | none | you: turn on Vulpine Gateway in System Settings, Login Items (the step’s button opens it) | launchd:gateway, port:gateway |
| 6 | Voice server | the voice server, the same way, from its pack | the voice server’s pack | you (the same switch) | launchd:tts, port:tts |
| 7 | Permissions | one card at a time: the microphone when this Mac hears the room, then the optional folders | none | you: one Allow per prompt | grants:* |
| 8 | Pi | asks you first: “Install Pi 1.4.0 (about 25 MB from the npm registry)?” Then installs it with the JavaScript runtime inside the app, keeps it only if it matches its pinned checksum, and points the gateway at it | Pi, about 25 MB | you: the yes | command:pi |
| 9 | Sign in | opens Pi’s own sign-in; the app reads only which providers are signed in, never a key | none | you: your account | brain:provider |
| 10 | Checks | runs the doctor every few seconds while something changes, then once more with every model file hashed | none | setup | every row |
Then the First turn step (“say hello”, or type it; the reply is spoken) and Done.
What needs your hands, and why
- Moving the apps into Applications: only you move an app there.
- The Login Items switch: macOS asks you before anything runs in the background; an app cannot approve itself.
- Each privacy prompt: macOS asks you, once per permission.
- The yes to Pi, and Pi’s sign-in: the account and its bill are yours.
Until a release carries them, the voice server’s pack and the JavaScript runtime are not inside the app: those steps say so in words and wait for the update.
Expansions
After the core, the Done page offers expansions. None is needed.
- Packs: the house (lights, rooms, room speakers), cameras, sound watches, the agent fleet, reach.
- Bring your own speech: your own speech recognizer or voice, from the hardpoints Vulpine qualifies.
- House adapters: Home Assistant, a room speaker.
The list comes from a registry, catalog/expansions/registry.toml. Your own rows go in
~/Library/Application Support/Vulpine/expansions.d/ as *.toml files of the same shape; a row of yours never
replaces a built-in one.
When something fails, and removing it
- A failed step says what happened and what to do, in one sentence, and offers Try again. It never prints a secret, a path in your home folder or a command.
- Remove what setup installed undoes, last step first, only what setup itself made: the gateway’s login item, Pi and its launcher, the environment lines it added. Your models and settings stay. Permissions and Pi’s sign-in are yours and are never revoked.
The doctor and the steps are one list
Every setup step names the doctor checks it turns green (crates/protocol/src/setup_steps.rs). A test in the gateway
holds the two equal: a check the doctor reports belongs to one step or is named, with its reason, as one setup leaves
alone (the fleet’s docs site, the shadow decision model, the secrets of an expansion you have not added).
The grants holder
Step 12 of the developer install; an app install needs it only for the calendar, reminders and contacts tools. What it is. VulpineGrants.app (runtime/grants) is a small app with no
window and no Dock icon. It holds the Calendars, Reminders and Contacts permissions for Vulpine. macOS grants these
to an app (its bundle id com.voidfab.vulpine.gateway.grants and its signature), not to the gateway binary, so
they survive every gateway roll. Without the holder, “what’s on today”, the reminders verbs and the names of message
senders are refused. The gateway and the brain launch the holder through LaunchServices (open -n -b). Without
-n, macOS hands the request to a running holder (the screen agent) and it gets no answer. The holder answers one
command at a time.
Why it must be signed. macOS keys each permission to the app’s code signature. An ad-hoc signature (-) is new
on every build, so every rebuild loses the permissions. The recipes refuse ad-hoc signing. Any stable certificate
works; a self-signed one is enough on your own Macs.
1. A signing identity, once, on the Mac that builds. That Mac holds the private key.
-
To use an identity you have:
security find-identity -p codesigninglists them. Name one by its name or SHA-1, withexport VULPINE_CODESIGN_IDENTITY='<name or SHA-1>'or under[signing]in~/.config/vulpine/fox9.toml(identity = "<name or SHA-1>";just bootstrapwrites the commented line). -
To make a self-signed one, use macOS’s own
/usr/bin/openssl(LibreSSL). A.p12file from OpenSSL 3 needs-legacybeforesecurity importreads it.mkdir -p ~/.config/fox9/codesign && chmod 700 ~/.config/fox9/codesign && cd ~/.config/fox9/codesign printf '[req]\ndistinguished_name = dn\nx509_extensions = ext\nprompt = no\n[dn]\nCN = vulpine local signing\n[ext]\nkeyUsage = critical, digitalSignature\nextendedKeyUsage = critical, codeSigning\nbasicConstraints = critical, CA:false\n' > vulpine-codesign.cnf /usr/bin/openssl req -x509 -newkey rsa:2048 -nodes -days 3650 -config vulpine-codesign.cnf -keyout vulpine-codesign.key -out vulpine-codesign.crt /usr/bin/openssl pkcs12 -export -inkey vulpine-codesign.key -in vulpine-codesign.crt -out vulpine-codesign.p12 security import vulpine-codesign.p12 -k ~/Library/Keychains/login.keychain-db -T /usr/bin/codesign chmod 600 ~/.config/fox9/codesign/*The
pkcs12step asks for an export password, andsecurity importasks for the same one. The certificate is listed asCSSMERR_TP_NOT_TRUSTED; codesign signs with it anyway. When nothing else names an identity, the resolver reads theCNfrom~/.config/fox9/codesign/*.cnf, so no more configuration is needed. -
Check:
python3 tools/install/codesign_identity.py --explainprints the identity every signing recipe will use and where that name came from, or why it found none.
2. Install, on the gateway’s Mac, in its GUI login session (at the Mac, or over Screen Sharing):
- The gateway’s Mac holds the key:
just adapters::install-grantsruns the holder’s selftest, then builds, signs, verifies and installs the holder in~/Applications. The last copy is kept asVulpineGrants.app.prev. - Another Mac holds the key:
build-grantson the gateway’s Mac refuses with “certificate is in a keychain, but no private key for it is usable here”. Keep the key on the signing Mac:- On the signing Mac, run
just adapters::pack-grants. It prints a zip path and its sha256. - Copy the zip to the gateway’s Mac (
scp). - There, run
just adapters::install-grants <zip>. This step refuses a zip with another bundle id, an ad-hoc signature or a signature that does not verify.
- On the signing Mac, run
Over ssh the login keychain is locked, so a signing step finds no identity. Run
security unlock-keychain ~/Library/Keychains/login.keychain-db first, or use the GUI session. The permission
dialogs in step 3 appear only in the GUI session.
3. The first-run consent. In the GUI session, run each line once. Each opens one macOS dialog (“Vulpine Grants would like to access your calendar”, and so on). Click Allow (full access):
open -n -b com.voidfab.vulpine.gateway.grants --args calendar grant
open -n -b com.voidfab.vulpine.gateway.grants --args reminders grant
open -n -b com.voidfab.vulpine.gateway.grants --args contacts grant
macOS asks only once. If you clicked Don’t Allow, turn the permission on in System Settings > Privacy & Security > Calendars (or Reminders, or Contacts) > Vulpine Grants. A replacement signed by the same identity keeps every permission. A new identity or bundle id is a new app to macOS, which asks for each permission again.
4. Verify. just adapters::grants-status prints the holder’s own receipt through LaunchServices. Look for
"contract":2 and "calendars":"full" (and reminders, contacts). not_determined (never asked), write_only
(limited), denied and restricted mean the permission is not full. Do not run the binary over ssh to read it:
macOS would answer for sshd. just doctor shows the same facts as two rows:
grants:holder: the holder is installed, has the configured bundle id, and has a certificate signature (an ad-hoc signature isWRONG). With[calendar]off, a missing holder is aNOTE. With it on, a missing holder isMISSING.grants:access: the contract and the state of each permission. With[calendar]on, a Calendars permission that is not full isMISSING. Reminders or Contacts that are not full give aNOTEwith the line or the Settings pane that fixes them. A holder that cannot be asked (no GUI session) is aNOTEthat namesjust adapters::grants-status.
5. The screen agent, on a Mac whose screen Vulpine reads. The screen agent lives in the same app:
fox9grants screen serve is the launchd job com.voidfab.fox9.screen-agent, so Screen Recording and Accessibility
are Vulpine Grants’ permissions too. Install the job in the GUI session, after step 2:
launchctl bootout gui/$(id -u)/com.voidfab.fox9.screen-agent
python3 tools/repo/paths.py render-plist runtime/screen/com.voidfab.fox9.screen-agent.plist ~/Library/LaunchAgents/com.voidfab.fox9.screen-agent.plist
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.voidfab.fox9.screen-agent.plist
Then turn on Vulpine Grants in System Settings > Privacy & Security > Screen & System Audio Recording, and again
under Accessibility (macOS lists the app after its first capture). Restart the agent once:
launchctl kickstart -k gui/$(id -u)/com.voidfab.fox9.screen-agent. Check, read-only: just adapters::grants-status
shows "screen_recording":"full" and "accessibility":"full", and with [screen] enabled the doctor’s
grants:access row names both.
A gateway whose [screen] screenctl is unset runs the holder’s executable as fox9grants screen. One that reads
another Mac’s screen sets screenctl = "~/Applications/VulpineGrants.app/Contents/MacOS/fox9grants" beside
[screen] host. Rollback: render the plist from the release before and bootstrap it again.
Vulpine.app’s welcome window does not run this step; do it by hand.
See also
- Developer install - the clone-and-just path, what bootstrap creates, the secrets, the doctor as data.
- README - what Vulpine is.
- release and rollback - releases and rolls after the install.