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

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:total row is a NOTE.
  • About 5 GB free on the home volume: setup downloads 1.9 GB of models and keeps 3 GiB free (the doctor’s disk:home floor).
  • The two apps from the release page, dragged into Applications: Vulpine.app (the client you talk to) and Vulpine 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

  1. Moving the apps into Applications: only you move an app there.
  2. The Login Items switch: macOS asks you before anything runs in the background; an app cannot approve itself.
  3. Each privacy prompt: macOS asks you, once per permission.
  4. 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 codesigning lists them. Name one by its name or SHA-1, with export VULPINE_CODESIGN_IDENTITY='<name or SHA-1>' or under [signing] in ~/.config/vulpine/fox9.toml (identity = "<name or SHA-1>"; just bootstrap writes the commented line).

  • To make a self-signed one, use macOS’s own /usr/bin/openssl (LibreSSL). A .p12 file from OpenSSL 3 needs -legacy before security import reads 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 pkcs12 step asks for an export password, and security import asks for the same one. The certificate is listed as CSSMERR_TP_NOT_TRUSTED; codesign signs with it anyway. When nothing else names an identity, the resolver reads the CN from ~/.config/fox9/codesign/*.cnf, so no more configuration is needed.

  • Check: python3 tools/install/codesign_identity.py --explain prints 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-grants runs the holder’s selftest, then builds, signs, verifies and installs the holder in ~/Applications. The last copy is kept as VulpineGrants.app.prev.
  • Another Mac holds the key: build-grants on 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:
    1. On the signing Mac, run just adapters::pack-grants. It prints a zip path and its sha256.
    2. Copy the zip to the gateway’s Mac (scp).
    3. 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.

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 is WRONG). With [calendar] off, a missing holder is a NOTE. With it on, a missing holder is MISSING.
  • grants:access: the contract and the state of each permission. With [calendar] on, a Calendars permission that is not full is MISSING. Reminders or Contacts that are not full give a NOTE with the line or the Settings pane that fixes them. A holder that cannot be asked (no GUI session) is a NOTE that names just 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

Was this page helpful?