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

Key decisions

The design decisions that shape how you install, run and extend Vulpine. Each entry says what was decided, why, and what it means for you.

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

The shape of the system

One Rust gateway runs every turn

  • Decided: The Voice Gateway is one Rust process. Audio, transcripts, brain replies and speech move through it as frames on a streaming pipeline.
  • Why: One process owns the turn, so latency is measured in one place and a slow step is visible.
  • For you: You run one gateway. Every frontend, satellite and tool connects to it.

A small decision model sits beside the turn; the brain is the fallback

  • Decided: An optional typed decision model reads the first words of a spoken turn, beside the turn: the turn never waits for it. It is off by default. Today it acts on one thing: after a reply, a follow-up without the wake word that it reads as not meant for the assistant is dropped. It is meant to settle more turns before the brain in time.
  • Why: The check answers in under a second on the gateway host. A full model call for every overheard sentence is slow and costly.
  • For you: With it on, the assistant stays quiet when you talk to someone else after a reply. With it off, every follow-up goes to the brain. Either way, the commands the gateway settles itself never wait for a model.

Typed contracts are fixed; what sits behind them is replaceable

  • Decided: Every seam is a versioned contract with typed messages. The decision model, the speech engines and the brain are implementations behind those contracts.
  • Why: A model can be swapped without changing the tools, the tests or the frontends that depend on its output.
  • For you: You can change a model or a provider and keep the rest of your setup. A contract change is versioned and announced.

Agent and persona are separate

  • Decided: An agent is what does the work. A persona is how it sounds and looks. They are configured apart.
  • Why: The same agent can speak through different voices and faces, and a persona can move between agents.
  • For you: Change the voice or the avatar without touching the agent’s tools or memory.

Speech and conversation

Bring your own speech

  • Decided: Speech-to-text and text-to-speech are hardpoints. A client may also declare that it does its own speech, and the gateway negotiates that at connect.
  • Why: Users have different hardware, voices and providers. No single engine fits every room.
  • For you: Plug in the STT provider, the TTS model and the voice you choose. The self-hosted path needs no cloud account.

Speech stays home; the model sees only text

  • Decided: Speech recognition and the voice run on your own Mac, and the gateway listens on loopback only. Audio and transcripts stay on your machines. The one thing that leaves is the text of a turn that goes to your agent, and only when the model your agent calls is a hosted one.
  • Why: Household audio is the most private thing the system touches, and speech on your own Mac is also the fastest path.
  • For you: Your audio never leaves the house. Choose the model your agent calls, and you choose where a turn’s text goes.

Spoken commands are a closed table in the gateway

  • Decided: After the wake word, the gateway matches the request against a closed table of commands before the brain sees it. Text that is not a command stays an ordinary request.
  • Why: A command must act at once and the same way every time. It never waits for a model.
  • For you: “Over and out” hangs up when the brain is slow or offline. “Over” ends your request when you say it. The full list is what you can say.

Interrupting needs two signals

  • Decided: A wake word heard while the assistant is speaking interrupts it only when the frontend confirms that the operator is speaking over the playback.
  • Why: A speaker that hears itself otherwise cuts its own reply.
  • For you: The assistant does not interrupt itself. You can still cut in by speaking.

Your mood may change how it behaves, never what it says about you

  • Decided: Signals about the operator’s state may shape pacing and tone. The assistant never states them aloud.
  • Why: Being told how you sound is intrusive.
  • For you: No commentary on your voice or mood.
  • Decided: The meeting adapters record nothing until consent is given, and one transcript is the record.
  • Why: Other people are in the call.
  • For you: Meeting capture starts only after consent.

Frontends and visuals

Frontends are skins over one protocol

  • Decided: The protocol is the source of truth. A shared client core speaks it, and each frontend (Vulpine.app, Vulpine in a browser, the terminal skin, Vulpine on iPhone in development, room speakers) is a skin on top.
  • Why: A new frontend needs no gateway change, and no frontend’s needs bend the protocol.
  • For you: Use any mix of frontends against one gateway. Write your own against the same contract.

The desktop app goes native

  • Decided: Every surface of Vulpine.app’s Glyph look is to be drawn natively with GPUI, and the web view retires. The move is under way, one surface at a time; the app still ships in its web-view shell.
  • Why: A native window draws no frame at rest and uses less memory than a web view.
  • For you: A lighter app as each surface moves. The looks (dither, ASCII, CRT, dot matrix, pixel, wide-gamut HDR) are choices in the app.

Panels are typed data, drawn by the frontend

  • Decided: A tool sends typed data for a panel. Curated panels are templates the gateway compiles to SVG. Script visuals run in a sandbox and are dry-run by the gateway before any frontend draws them.
  • Why: A panel must render the same on every frontend, and a script must not reach outside its sandbox.
  • For you: A reply can show a chart or a card beside the spoken answer. A custom visual cannot touch your files.

A shown file is fetched by its hash, from allowed folders only

  • Decided: When the assistant shows a file, the render names it and the frontend fetches it by hash. Only folders you allow are readable.
  • Why: A file path in a reply must not become a way to read anything on the host.
  • For you: You choose the folders. Nothing outside them is shown.

Tools, extensions and integrations

Every tool speaks one call shape

  • Decided: Catalog tools share one call shape with a small set of common actions and a manifest. One registry serves the gateway, a standalone agent, the CLI and MCP.
  • Why: A model learns the shape once. A tool written once works at every door.
  • For you: Add a tool in one place and call it by voice, from the terminal or from another agent.

Integrations come in two tiers

  • Decided: An adapter is a small program outside the gateway that speaks a typed contract. A first-party integration lives in the gateway. New integrations start as adapters.
  • Why: An adapter can fail, restart or be replaced without touching a live turn.
  • For you: Write an adapter in any language. The gateway treats a missing adapter as a degraded feature, not an outage.

The extension API is versioned, with a promise

  • Decided: Hardpoints, observe-only hooks and plugins are versioned contracts under semantic versioning. A conformance suite checks the promise.
  • Why: An extension you write should keep working across releases.
  • For you: Run the conformance suite against your extension. A breaking change comes with a new contract version.

Packs are signed and checked before anything installs

  • Decided: A tool pack or extension pack is one archive with a manifest of per-file hashes, listed in a signed index. One verifier checks it before install.
  • Why: Installing a tool is running someone’s code.
  • For you: A pack that fails the check is not installed.

Agent protocols are opt-in and separate from voice

  • Decided: ACP is an agent boundary you turn on in either direction. It is not the voice transport.
  • Why: Voice has its own latency budget and contracts.
  • For you: Connect an ACP agent, or expose Vulpine as one, without changing how voice works.

Safety and operations

An approval shows the real program

  • Decided: When an agent asks to run something, the approval shows the program that will run. A dangerous request asks the operator every time.
  • Why: An approval of a description is not an approval of a command.
  • For you: You see what will execute before you say yes. A standing approval never covers a dangerous command.

Webhooks enter through a loopback intake

  • Decided: Inbound webhooks arrive at a loopback listener in the gateway, reached through a tunnel. Each source signs with its own secret.
  • Why: The gateway opens no public port, and one leaked secret exposes one source.
  • For you: Add a source with its own secret. Revoke one without touching the others.

The Admin writes config through one overlay

  • Decided: The gateway owns one config overlay beside the installed config file. Only the gateway writes it, only for editable fields, and only when [admin] config_writes is on.
  • Why: An install or an update never fights a setting you changed in the app.
  • For you: Change settings in the Admin. Your config file stays as you wrote it.

Fleet hosts join one self-hosted overlay

  • Decided: Every host in a fleet joins one overlay network you host. Each link is measured in both directions, and a broken link is reported and repaired in steps.
  • Why: A house has laptops, a server and phones on changing networks.
  • For you: Your devices reach the gateway from anywhere without a third-party relay you do not control.

Names and languages

Vulpine is the product

  • Decided: Vulpine is the product name and “Fox Nine” is the callsign. Older fox9 and foxline identifiers stay as compatibility names until each family migrates.
  • Why: Renaming every identifier at once would break installed setups.
  • For you: You will see fox9 and foxline in some commands, paths and config keys. They are current.

Runtime code is Rust

  • Decided: New runtime code is Rust, with Swift or Objective-C at the Apple seams. TypeScript is used where the surface is the web or the agent runtime. Python stays for offline tooling.
  • Why: The turn path has a millisecond budget.
  • For you: The helpers the gateway runs are binaries.

Was this page helpful?