---
title: "What Vulpine is"
description: "Vulpine gives the agent you already run a voice, and keeps it in your house. You speak, and a Mac in your house hears you. Vulpine answers simple requests itself, at once."
type: "living"
source: "README.md"
verified: "2026-11-14"
group: "Install and operate"
---

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

It sends everything else to your agent, then speaks the
reply in a voice you chose. You host it yourself: there is no account, and your machines process the audio.

You start a request with the callsign "Fox Nine". [What you can say](/docs/install-and-operate/voice-commands) has the rest.

## The parts

- **The gateway** is the Vulpine program on your Mac. It is one Rust program, and it runs every turn: it hears you,
  decides when you have finished, answers or asks your agent, and speaks the reply. Every app and speaker connects
  to it over one WebSocket protocol.
- **Your agent** answers everything the gateway does not. The docs call it the brain. Today the supported agent
  runtime is Pi, installed on the same Mac. More runtimes are to come. The model your agent calls is usually a
  hosted one, and that call is the one step that can leave the house.
- **Speech** stays on your Mac. Speech recognition is Parakeet on the Neural Engine. The voice is Qwen3-TTS. The
  install downloads both.
- **The decision model** is a small model beside the turn. It is optional and off by default. The turn never waits
  for it.

## Two ways to answer

A turn is one request and its reply.

- **A verb turn.** A verb is a request the gateway can do by itself: "turn off the office lights", "say that
  again", "never mind". The gateway knows a short, fixed list of verbs. It does them at once, and your agent is not
  asked.
- **An agent turn.** Questions, plans and open requests go to your agent, and your agent uses its tools. Only these
  turns wait for a model. With [the early start](/docs/the-voice-path/speculation) switched on, the gateway starts your agent
  before you finish speaking. It is off by default.

[ARCHITECTURE.md](/docs/the-voice-path/architecture) follows one turn end to end. Each step of a turn has a budget in milliseconds:
[the turn budget](/docs/contracts/turn-budget.v1).

## Where you talk to it

| Surface | What it is | State |
|---|---|---|
| [Vulpine.app](/docs/frontends/desktop-app) | the desktop app for macOS: a face at the edge of the screen that listens, answers and shows its work | ships |
| Vulpine in a browser | a full-screen call in a browser tab, with a portrait and a running transcript | ships |
| [A room speaker](/docs/adapters-and-integrations/room-speaker-bridge) | a small speaker and microphone for a room; it hears the wake word itself | ships |
| [The terminal frontend](/docs/frontends/tui) | the conversation as text, from any SSH terminal | ships |
| [Vulpine on iPhone](/docs/frontends/phone) | hold a button to talk, or type; it pairs with the gateway at home | in development |
| [Vulpine Gateway.app](/docs/frontends/gateway-app) | the app that runs the gateway; [its window](/docs/frontends/admin) shows sessions, speech, your agent, the house and the approvals | ships |

[The frontends overview](/docs/frontends/overview) says how they share one protocol.

## What you need

- A Mac with Apple silicon and 16 GB of memory.
- Disk: a fresh install writes about 7 GB, plus the gateway's build folder. The doctor refuses under 3 GiB free on
  the home volume.
- Pi, installed on that Mac. Vulpine does not include an agent.
- Optional: a speaker for a room, and a screen for a face.

The install downloads speech recognition (about 630 MB) and the voice (about 1.3 GB). There is no server to stand up.

## Install

Clone the repository, then run these in the checkout:

```bash
mise install     # the pinned toolchain
just install     # build the gateway, create its config, fetch the voice
just doctor      # one OK / MISSING / WRONG line per check, with the fix
```

[The install guide](/docs/install-and-operate/install) has every step in order, with the checks each step satisfies. Three steps are
by hand: you install Pi, fetch the speech recognition model, and allow the macOS permissions. Run `just doctor`
again whenever something feels off.

After the install, [Run the gateway](/docs/install-and-operate/voice-gateway) covers its config file and how to roll a new
version, and [Release and rollback](/docs/install-and-operate/release) covers a release.

## Make it yours

Every part is a slot, called a hardpoint. Two slots take your own part today: speech to text and text to speech.
The other slots (the wake word, the decision model, the agent, the voice, the avatar, the visual panel, rooms,
memory and retrieval) have their names, and their swaps come next.

- [Hardpoints](/docs/contracts/hardpoint.v1): the slots, and how your part is bound and checked.
- [Tools](/docs/contracts/tool.v1): the shape of a tool your agent can call.
- [Integrations](/docs/adapters-and-integrations/overview): the adapters that connect a house, a room or a service.
- [Key decisions](/docs/install-and-operate/key-decisions): what was decided, why, and what it means for you.
- [The glossary](/docs/the-voice-path/glossary): the words the docs use.

## What runs on the Mac

| Piece | What it is | Where it lives |
|---|---|---|
| The gateway | the Rust gateway, a launchd agent that listens on `127.0.0.1:8780` | `crates/voice_gateway` |
| Speech recognition | Parakeet TDT v3 on CoreML and the Neural Engine | `crates/coreml_stt` |
| End of utterance | the Parakeet end-of-utterance worker, which the gateway starts | `services/parakeet_eou_native_worker.cpp` |
| The voice | the qwentts.cpp `tts-server` on port 8850 | `runtime/qwen3_tts_worker/qwen3_tts_worker.py` |
| The decision model | optional: a model server on port 8871 that speaks the decision contract | `docs/contracts/decision.v1.md` |
| Your agent | `pi --mode rpc`, with the model the loadout's `[pi] model` names | `catalog/agents/operator/.vulpine/` |
| Helpers | the adapter programs the gateway starts (home, room, fleet, vision, screen, calls) | `runtime-tools.toml` lists every one |

"Fox Nine" is the callsign. Code identifiers keep their `fox9` and `foxline` names.


## Attributions

Vulpine builds on and learns from these upstream projects:

- [Pi coding agent (pi.dev)](https://pi.dev) by Mario Zechner and contributors: the agent runtime, used in RPC mode
  as the brain.
- [PiBot / Pipi](https://github.com/badlogic/pibot) by Mario Zechner: the worker-based voice assistant design, the
  parakeet.cpp worker integration and the Qwen3-TTS worker design.
- [parakeet.cpp](https://github.com/mudler/parakeet.cpp) by Ettore Di Giacinto and contributors: C/C++ Parakeet
  inference, under the EOU worker.
- [qwen3_tts_rs](https://github.com/badlogic/qwen3_tts_rs) by Mario Zechner: origin of
  [spqx](https://github.com/byteowlz/spqx), the fork evaluated for the retired `rust-mlx` candidate.
