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

Run the gateway

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.

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; one turn end to end is ARCHITECTURE.md.

Run locally:

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:

~/.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); 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:

  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, “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

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.

Was this page helpful?