---
title: "Run the gateway"
description: "The Rust voice gateway: running it locally, where its config file lives, rolling a new version on the mini (overlay-status, overlay-roll-internal) and its build features."
type: "living"
source: "crates/voice_gateway/README.md"
verified: "2026-11-14"
group: "Install and operate"
---

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

The Rust runtime core for Vulpine voice sessions: the crate, lib and binary `vulpine-voice-gateway`. `just bootstrap`
and the roll install the binary on the gateway host at `<state>/bin/foxline-voice-gateway`. The install is
[docs/install.md](/docs/install-and-operate/install); one turn end to end is [ARCHITECTURE.md](/docs/the-voice-path/architecture).


Run locally:

```bash
just gateway-check
just gateway --bind 127.0.0.1:8780
```

Without `--config`, the gateway creates a config file on first run in the vulpine config root (the doctor's
`xdg:config` row), on macOS and Linux alike:

```text
~/.config/vulpine/config.toml    # or ~/.config/foxline/config.toml while only the old root exists (one release)
```

`--config <path>` (or `VULPINE_GATEWAY_CONFIG`) loads a different file, and no default file is written.


The gateway serves a WebSocket with JSON control and event frames and binary PCM. Pi RPC (the brain), STT and TTS
are adapter boundaries: the gateway never calls the brain's LLM server. The gateway answers a short list of verbs
itself, with no brain turn ([what you can say](/docs/install-and-operate/voice-commands)); everything else goes to the brain.

The decision model is optional and off by default (`[decision_shadow]`). When it is on, the gateway asks it
(decision.v1, through `decidectl`) beside the turn and never waits for it. The one answer it acts on: a follow-up
said without the callsign that the model reads as not meant for Vulpine is dropped (`[decision_gate]`). Every other
answer is only traced.

## Rolling it on the mini

The live gateway runs on the gateway host as the launchd agent `com.voidfab.fox9.gateway`. Every build gets the next
version integer; a roll swaps the running version for the new one. Run everything from your own checkout, not the
gateway host's. Releases, signing and rollback are [docs/release.md](/docs/install-and-operate/release):

```mermaid
flowchart LR
  status["just overlay-status<br/>running v&lt;old&gt;"] --> commit["commit"]
  commit --> build["overlay-roll-internal &lt;new&gt; &lt;old&gt;<br/>build, sign, copy"]
  build --> pre{"preflight"}
  pre -- "disk, listener or retired job" --> refuse["refused, nothing touched"]
  pre -- ok --> swap["stop &lt;old&gt;, start &lt;new&gt;"]
  swap --> ready{"listener on :8780<br/>within 15 s?"}
  ready -- yes --> check["read the binary identity line"]
  ready -- no --> kick["one kickstart"] --> check
```

1. `just overlay-status` prints the running version as `v<N>`, its pid and the `:8780` listener. That `N` is the
   old version.
2. Commit first. The roll runs from the binary it ships (its `overlay-stdio` subcommand, `crates/overlay_stdio`).
   `build.rs` stamps the binary with its commit (`-dirty` on an unclean tree).
3. `just overlay-roll-internal <new> <old>` builds, signs (`sign-gateway`), copies the binary to the gateway host
   and rolls, for example `just overlay-roll-internal 469 468`. Both arguments are version integers, never a pid.
   `just overlay-roll <new> <old>` does the same swap for a binary already on the gateway host's volume as
   `foxline-voice-gateway-stdio-v<new>`.
   Both rolls first ship the brain-tools bundle Pi loads (`just voice::deploy-brain-tools`: build, a Pi load test
   on the gateway host, install). Without its matching bundle, every brain tool can answer "unavailable". A failed deploy
   refuses the roll with `roll REFUSED: the brain-tools deploy failed (…)`. To roll without the bundle, name the
   host and add the flag: `just overlay-roll-internal 469 468 mini --skip-brain-tools`. The roll prints a loud
   warning.
4. Read the roll's output. `listener ready on :8780 (v<new>)` means the new gateway is up, and the `binary:
   identity=` line must name the commit you built. If the listener is not back within 15 s, the roll kickstarts the
   agent once and prints the agent log. `gateway is DOWN` means that kickstart failed too. The last line is
   `roll summary: v<new> gateway=vulpine-voice-gateway@0.1.0+<commit> brain-tools=<commit> sha256:<12>`
   (`brain-tools=skipped` after the flag). The bundle's stamp sits beside it on the gateway host as
   `runtime-root/extensions/brain-tools/index.js.stamp`.

Before it touches anything, the roll refuses when:

- a volume the gateway writes to has less than 1 GiB free (a full disk refuses every client bind);
- a Vulpine process the stack does not own holds a TCP listener (`adapter_listener_refused`);
- one of the retired gateway jobs (`org.nixos.foxline-gateway`, `org.fox9.gateway-native-stt`) is running or
  enabled again.

A normal `overlay-roll` restages the gateway config from the gateway host's volume copy; `overlay-roll-internal` keeps the
staged copy. `just overlay-config-check` (`overlay-stdio config-sync --check`) reads both over ssh, read-only. It
lists by section what a normal roll would drop (`+`), add (`-`) or change (`~`), exits 2 on drift and 0 when clean,
and never prints a secret-shaped value. It has no write mode: sync the volume copy from the staged one by hand, and
run a normal roll only when the check is clean.

Vulpine.app may stay open during a roll. On the gateway host it is nudged with `glyphctl reconnect`; on another Mac
it reconnects on its own within about a second. `glyphctl status` on that Mac shows the new session. A brain, tool
or pi-config change that needs no new binary goes out with `just mini-sync-checkout`: it pulls the gateway host's
checkout and kickstarts the gateway, so Pi restarts with it.

## When clients are refused after a roll

**Every client refused at hello** (`unsupported_protocol_version`, or `protocol_handshake_failed` on the client):
the clients were built at a different protocol version from the gateway. Master is protocol 5. A roll that changes
the version ships Vulpine.app, Vigil and the room speakers' bridge together. See
[`docs/release.md`](/docs/install-and-operate/release), "Every client refused after a roll from master: protocol lockstep".

### Every bind refused `tts_adapter_failed`: the gateway host's disk is full

**Symptom.** Right after a roll, the clients negotiate hello, but every bind is refused
`session_bind_refused {code: tts_adapter_failed}` while the TTS server is up. The gateway log says `create unlinked
Persona voice reference … snapshot`.

**Cause.** The first write of every bind is the Persona voice-reference snapshot: the TTS adapter copies the
reference WAV and transcript into unlinked temp files (`snapshot_voice_reference` in
`crates/voice_gateway/src/ws/persona.rs`). On a full data volume that copy fails, and the bind reports a TTS adapter
failure. Nothing in the trace says "disk".

**Check first.** `ssh <gateway host> df -h /System/Volumes/Data`.

**Safe to free.** The gateway host checkout's `target/` directory: nothing runs from it, since the live gateway runs from
the state root's `bin/`. Then reconnect the clients (`glyphctl reconnect`). Do not delete the Hugging Face cache
(live models), the workbenches or uv's cache without asking the operator.

The roll's preflight (`disk_preflight` in `crates/overlay_stdio/src/preflight.rs`) refuses a roll under 1 GiB free,
but the disk can fill after the roll.

### Text turns refused `brain_operation_in_progress`

**Symptom.** Typed turns (`glyphctl send`, the client's text box) get `error {code: brain_operation_in_progress}`, "wait
for the active Brain operation to finish or interrupt it", sometimes for minutes.

**Cause.** This session already has a brain operation open (`brain_operation_pending` in
`crates/voice_gateway/src/ws/state/announce.rs`), a turn or a model query:

- A turn: text sent during a turn is steered into it, and is refused only when the steer does not land within 3 s.
- A model query: the models list asked at every bind, or a model switch.

The trace row `text_utterance_refused {turn_requests, model_queries}` says which one is open. An operation older
than 120 s is aborted and the brain restarted (`brain_operation_timeout`).

**Fix.** `glyphctl interrupt`, then ask again. If the refusals continue, `glyphctl reconnect`.

**A second frontend.** The brain pool keys each Pi process by its identity, which includes the client's owner
(`BrainIdentity.owner` in `crates/voice_gateway/src/brain/launch.rs`). A second frontend on the same gateway, such
as Vulpine.app on a second Mac beside the one on the gateway host, gets its own Pi process and does not hold this
session's turn gate. Still, run only one Vulpine.app on the gateway host itself: a second one is a second Pi process
and a second session hearing the same voice.

## Build features

| feature | default | what it adds |
|---|---|---|
| `enroll-wespeaker` | off | WeSpeaker enrolment through `polyvoice` (ONNX). |
| `swift-bridge` | off | Apple frameworks through a static Swift archive. |

### `swift-bridge`

```bash
MACOSX_DEPLOYMENT_TARGET=13.0 cargo build -p vulpine-voice-gateway --release --features swift-bridge
MACOSX_DEPLOYMENT_TARGET=13.0 cargo test -p vulpine-voice-gateway --release --features swift-bridge --lib -- apple
```

With the feature on a macOS target, `build.rs` compiles `swift/*.swift` into a static archive and links every
framework the sources import with `-weak_framework`, so a missing framework cannot stop the gateway from launching.
Export one `MACOSX_DEPLOYMENT_TARGET` (default 13.0) for the whole build so rustc and swiftc agree. Any other build
compiles `apple_stub.rs`, which has the same API, answers `Err(Unavailable::NotCompiledIn)` and never runs swiftc.

The one capability is `apple::dominant_language(text) -> Result<String, Unavailable>` (NaturalLanguage). No live path
uses it. Admin health shows it as the `gateway.swift-bridge` row: `swift-bridge: available`,
`swift-bridge: unavailable (not compiled in)` (Healthy: left out on purpose), or
`unavailable (NaturalLanguage framework absent)` (Degraded). Keep TCC-gated frameworks (camera, mic, screen,
contacts, calendars) out of this bridge: a bare CLI cannot hold a TCC grant.

