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

Loadouts

Loadouts, the voice-session configuration under .vulpine/: how to give the brain a tool (the loadout's extensions and its allowed_pi list), the frontend tools it requires, and the Pi model and thinking settings.

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

The Voice Gateway owns the .vulpine/ voice-session configuration. Pi reads its own defaults from .pi/; the gateway does not. The gateway reads .vulpine/ only. Rename an older workspace: mv .foxline .vulpine.

Directory layout

<workspace>/
  .vulpine/
    loadout.toml
    loadouts/
      default.toml
      field.toml
    mcp/
      default.json
    extensions/
      project-tools/

Loadout selection order:

  1. .vulpine/loadouts/<name>.toml
  2. .vulpine/loadout.toml when <name> is default
  3. Built-in gateway defaults when no file exists

Loadout schema

Every section is closed. An unknown section or key, such as a misspelt [lifecyle], refuses the loadout with unknown field, and the bind fails.

extensions = ["builtin:frontend-tools", "local:project-tools"]

[pi]
profile = "voice"
config = ".pi/config.toml"
session_dir = ".pi/sessions"
model = "anthropic/claude-sonnet-4"
models = "anthropic/*,github-copilot/*,openai-codex/*,xai/*"
thinking = "minimal"

[lifecycle]
prewarm = true
keep_warm_ms = 600000
# On prewarm and at a new conversation, also run one ephemeral
# `pi --mode json --print --no-session` with the launch's request-shaping args,
# env and session id, so the provider loads the model and caches the prompt
# prefix under the real cache key before the first real turn (measured: 10.2s ->
# 0.8s first audio on a cold local model). Writes no session history; never
# spoken; killed at a tool call, after 180 s or when the owner retires.
warmup_prompt = true

[adapters]
stt = "parakeet-silero"
tts = "qwen3-worker"

[tools]
required_frontend = ["vigil.display"]
optional_frontend = ["vigil.avatar"]
allowed_pi = ["read", "write"]
herdr_attention_project_root = "../.."

warmup_prompt (on by default) warms the provider’s prompt cache. The provider caches by prompt prefix and, for the Codex API, by Pi’s session id: a bind and a rotation (a new id) each fire one warm-up, and a brain restart on the same conversation fires none. The warm-up sends the real launch’s request-shaping args in order, with its user message after the cached prefix. The Admin’s Brain section counts warm-ups in its warmup lane.

The connected frontend must advertise every required_frontend name, or session startup fails. optional_frontend names are enabled only when advertised. The gateway passes allowed_pi to Pi as the Brain’s tool allowlist.

Other keys:

  • [pi] command replaces the gateway’s Pi command for the foreground Brain (a scripted provider such as runtime/k-brain).
  • [tools] background_toolset (none, herdr-readonly or research-readonly) sets the background-attempt tier. research-readonly adds Vulpine’s docs and code search to the web and file reads, and is on in the operator’s default, laptop and vigil loadouts. A completed job’s sources show as one card beside its spoken line; the Admin’s gateway.background_research row shows the tier and the hosts the last job reached.
  • [tools] max_risk caps the tool risk tier the loadout admits.
  • [invocation] overrides per-route turn settings such as follow_up_window_ms and dialogue_mode.
  • [dictation] sets hold-to-talk dictation for the loadout’s sessions: hold_to_talk (on by default; hold_to_talk = false turns it off), stream (off by default) and a [dictation.styles] table.
  • [ambient] room_note lets a committed turn carry the ambient room note (VULPINE_ROOM_NOTE) when the gateway’s [ambient] inform_brain is on too. It is off by default.

herdr_attention_project_root is a Gateway-only relative path, required exactly when allowed_pi contains brain_herdr_attention. The Gateway resolves it from the selected Agent workspace, with no upward root discovery, and admits only that exact committed Git worktree. Pi, the frontend and the Herdr pane cwd cannot set it. A missing, absolute, symlinked, non-repository or drifting root fails closed. The attention collector exposes only bounded changed relative paths and numeric metadata: never the root, file or diff content, comments, pane output or transcripts.

model and thinking are optional Pi launch settings. Agent workspace prompts own mission, runtime, tool and safety policy and stay presentation-neutral. Character, fictional counterpart, address terms and speaking style belong only to the selected Persona package.

A [pi] model change does not take: the frontend pins the model

Symptom. You change [pi] model in the loadout, kickstart the gateway and reconnect the client, and the brain still answers on the old model.

Cause. At bind the gateway prefers the model the frontend sends in start_session over the loadout’s. Client Core (packages/voice-client, used by Glyph and Vigil) learns the model from the gateway’s session_started, models_available and model_changed events and sends it back on the next start_session, so every reconnect, vulpine-glyphctl reconnect included, re-asserts the old model. The Glyph also reads its loadout from config.toml only at launch.

Fix. Quit the client and launch it again (for the Glyph: quit Vulpine.app and open it); a fresh client has no model to echo, so the bind takes the loadout’s. Or change the model where the frontend binds it (the Glyph’s model picker, Vigil’s startup model). To check, read the session trace’s loadout_resolved row: model and model_source (frontend, loadout or pi-default) say which one won.

Persona packages

start_session takes an agent for the Pi-backed Brain and an optional persona for voice and presentation. When persona is omitted, it defaults to [frontend] default_persona in the gateway config, and without one to agent.

A Persona is a package directory with a persona.toml manifest, holding prompt files, voice references and frontend-specific config or assets. The gateway reads only id, display_name, prompt_file and the [voice] references and variants; it ignores other sections, such as [frontend.codec], and does not route them to frontends.

Example:

id = "radio-operator"
display_name = "Radio Operator"
prompt_file = "SYSTEM.md"

[voice]
reference_audio = "voice/reference_audio/radio-operator-a.wav"
reference_text = "voice/reference_audio/reference.txt"

[[voice.variants]]
id = "operator-a"
label = "Operator A"
reference_audio = "voice/reference_audio/radio-operator-a.wav"
reference_text = "voice/reference_audio/reference.txt"
default = true

[frontend.codec]
config = "vigil/persona.toml"
portrait = "vigil/portrait.png"

voice.reference_audio and voice.reference_text define the gateway’s default TTS reference. voice.variants lists more references for clients or installers that offer voice choices. Session admission rejects malformed or empty WAV streams and empty or non-UTF-8 transcripts. Qwen workers read snapshots of the admitted files, so replacing a Persona path after admission cannot change the launched voice.

The gateway looks a Persona up in one place: <runtime root>/catalog/personas/<persona>, where the runtime root is the checkout or VULPINE_RUNTIME_ROOT. The directory must hold a persona.toml whose id matches, or selection fails.

The repo ships one Persona package, catalog/personas/cunningham (the Operator), and the install’s gateway config names it as [frontend] default_persona = "cunningham" (tools/install/skeletons/gateway.toml). The others (abigail and the CC0 demo packages alex-grant and mira-chen) are parked under catalog/personas/_parked/ and do not resolve. A Persona package may include generated Vigil portraits and Koko/Kokoro-generated reference voices, never copyrighted extracted runtime assets.

Personas do not live in a workspace. At bind the gateway refuses a Brain workspace that holds .vulpine/personas/, .foxline/personas/ or a personas/ folder with a package in it, in one line naming the folder and the Catalog path to move it to. just doctor shows the same as the persona:catalog-only row (WRONG, naming every stale folder under catalog/agents/*). A runtime root with only a <runtime root>/personas/ layout is refused at startup.

Agent-side voice directories are not selectable Personas: install a persona.toml package that declares its prompt and voice references. That keeps Persona selection fail-closed, so a UI can keep one Agent active while it changes presentation identity.

Extension references

  • builtin:<name> resolves to a bundled gateway extension under crates/voice_gateway/extensions/<name>.
  • local:<name> resolves to .vulpine/extensions/<name> inside the selected workspace.
  • A relative path such as extensions/project-tools resolves under .vulpine/.
  • Absolute extension paths are rejected.

The gateway passes resolved voice-only extensions to Pi with explicit --extension flags.

Was this page helpful?