---
title: "Install"
description: "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."
type: "living"
source: "docs/install.md"
verified: "2026-11-14"
group: "Install and operate"
---

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

Building from the repository instead (a clone, `mise`, `just install`) is the
[developer install](/docs/install-and-operate/install-developer). 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](/docs/install-and-operate/install-developer); 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.

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

```bash
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:


```bash
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](/docs/install-and-operate/install-developer) - the clone-and-just path, what bootstrap creates, the secrets, the doctor as data.
- [README](/docs/install-and-operate/what-vulpine-is) - what Vulpine is.
- [release and rollback](/docs/install-and-operate/release) - releases and rolls after the install.
