---
title: "Loadouts"
description: "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."
type: "living"
source: "docs/foxline-loadouts.md"
verified: "2026-11-14"
group: "The voice path"
---

> **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

```text
<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.

```toml
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:

```toml
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.
