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:
.vulpine/loadouts/<name>.toml.vulpine/loadout.tomlwhen<name>isdefault- 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] commandreplaces the gateway’s Pi command for the foreground Brain (a scripted provider such asruntime/k-brain).[tools] background_toolset(none,herdr-readonlyorresearch-readonly) sets the background-attempt tier.research-readonlyadds Vulpine’s docs and code search to the web and file reads, and is on in the operator’s default,laptopandvigilloadouts. A completed job’s sources show as one card beside its spoken line; the Admin’sgateway.background_researchrow shows the tier and the hosts the last job reached.[tools] max_riskcaps the tool risk tier the loadout admits.[invocation]overrides per-route turn settings such asfollow_up_window_msanddialogue_mode.[dictation]sets hold-to-talk dictation for the loadout’s sessions:hold_to_talk(on by default;hold_to_talk = falseturns it off),stream(off by default) and a[dictation.styles]table.[ambient] room_notelets a committed turn carry the ambient room note (VULPINE_ROOM_NOTE) when the gateway’s[ambient] inform_brainis 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 undercrates/voice_gateway/extensions/<name>.local:<name>resolves to.vulpine/extensions/<name>inside the selected workspace.- A relative path such as
extensions/project-toolsresolves under.vulpine/. - Absolute extension paths are rejected.
The gateway passes resolved voice-only extensions to Pi with explicit --extension flags.