API surfaces
Every interface something outside one vulpine process can speak to, with its stability label and its auth (the gap analysis is docs/design/developer-experience-gap-analysis-2026-11-08.md). The source is docs/contracts/api-surfaces.toml.
Generated from the code
docs-check’s api_catalog rule fails a reach ALPN, a protocol version constant or a docs/contracts/*.v<N>.md file the catalog has no row for, so a new wire cannot ship unlabeled.
Labels (the rulings):
- public: a third party may build on it. Versioned: a breaking change is a new contract file, a new ALPN version or a new protocol number, and an extension contract keeps ADR 0059 §5’s deprecation window.
- owner: the operator’s own tools and machines. It may change in any release; no promise to a third party.
- internal: plumbing between vulpine’s own parts. Never built on from outside.
- experimental: draft or off by default. It may change shape or go away; a ruling moves it to another label.
Nothing is published to crates.io or npm until the operator names a release; public is a promise about shape, not a package.
Surfaces
| surface | stability | transport | schema source | version | auth |
|---|---|---|---|---|---|
| Frontend protocol | public |
WebSocket on 127.0.0.1:8780: JSON control and event frames, binary PCM | Rust types ClientControl and ServerEvent in crates/protocol; TypeScript by ts-rs (just protocol-generate); JSON Schema docs/contracts/schema/frontend.v5.schema.json (DX4) |
protocol 5 (PROTOCOL_VERSION = MIN_PROTOCOL_VERSION = 5); additive inside 5, with features negotiation in the hello |
loopback bind; an Origin guard (a page off loopback must be in [frontend] allowed_origins; a native client sends no Origin); owner admission receipts; off the host only through the relay or reach |
| Admin owner socket | owner |
Unix socket <state>/admin/<socket_name>, one JSON request and answer |
AdminRequest and AdminResponse in crates/protocol, bounded by admin_markers::bounds; JSON Schema docs/contracts/schema/admin.v6.schema.json (DX4) |
ADMIN_PROTOCOL_VERSION = 6, repeated inside each projection |
file ownership markers on the socket; the headless dispatcher needs a token off loopback |
| decision.v1 | public |
one HTTP POST to an endpoint the operator configures under [decision] |
docs/contracts/decision.v1.md and its types in crates/protocol, with goldens; JSON Schema docs/contracts/schema/decision.v1.schema.json (DX4) | the file’s v1; the Jev typed-decision body is the fixed point | none: a loopback or LAN endpoint the operator runs |
| Extension contracts | public |
files, stdio, loopback sockets and HTTP, per contract | one docs/contracts file per contract; tool-index.v1.schema.json is the only extension contract with a JSON Schema so far | major.minor per contract, a deprecation window of two minors or 90 days (ADR 0059 §5); the build’s table is THIS_BUILD_SPEAKS in crates/extension_pack |
declared capabilities within the loadout and the guard; user code runs out of process |
| Hardpoint worker wires | public |
the STT worker wire and Wyoming (TTS), on loopback | docs/contracts/hardpoint.stt.v1.md and hardpoint.tts.v1.md | contract 1.0; Wyoming’s own version in the event header | loopback; the implementation runs out of process |
| Reach, client ALPNs | public |
QUIC over iroh =1.4.1, behind [reach] enabled = false |
one contract per public ALPN: docs/contracts/reach-pair.v1.md, reach-ws.v1.md and reach-voice.v1.md (JSON Schema reach-voice.v1.schema.json), lifted from crates/reach_iroh as built (DX11); the rest in ADR 0053’s addenda | in the ALPN name (vulpine/<name>/<n>); a protocol change takes a new ALPN |
dial by key; the paired list, roles and per-row grants; signed delegations for agents |
| Reach, fleet ALPNs | owner |
QUIC over iroh, between the operator’s own machines, brains and agents | Rust in crates/reach_iroh; ADR 0053’s addenda | in the ALPN name | dial by key; roles (client, brain, agent-signer); grants; attestation where the row asks for it |
| Opt-in ACP agent boundary | experimental |
bounded stable-v1 stdio; independent outbound and inbound roles, both off | docs/contracts/acp-integration.v1.md and acp-provider-registry.v1.md; crates/acp_boundary | ACP stable v1; local integration and registry contracts v1 | original admitted allocation and separately authenticated initiating-human route; peer labels and provider declarations grant nothing |
| Relay frame protocol | internal |
one stream of frames H P Q A O D F X S, over the ssh hop or vulpine/relay/1 |
crates/vulpine_relay/src/frame.rs | none: the bridge hello names its frame set | the ssh hop, or reach |
Agent connector (vulpine-agent-link) |
public |
MCP Streamable HTTP on 127.0.0.1:8797, behind a tunnel the operator runs | runtime/agent_link (src/mcp.rs, src/tools.rs); results in tool.v1 shape |
the MCP spec revision; seven named tools | OAuth 2.1 with PKCE and dynamic client registration; scopes per agent |
| Inbound webhooks | owner |
HTTP intake on loopback behind a tunnel | ADR 0051 | Standard Webhooks | the Standard Webhooks signature |
| Sidecar envelope | experimental |
stdin lines to a sidecar window | docs/contracts/sidecar-envelope.v1.md | v1 | a local child process |
| Brain (pi RPC) | internal |
pi’s RPC line protocol over stdio | pi’s own | pi’s version (pi 1.4 in THIS_BUILD_SPEAKS) |
the process boundary |
| herdr mutation dispatch | internal |
a gateway Unix socket the brain’s herdr tools write to | crates/voice_gateway/src/herdr_mutation.rs | DISPATCH_PROTOCOL_VERSION = 1 |
a per-launch token in the brain’s environment |
| Gateway config | owner |
config.toml |
GatewayConfig derives JsonSchema (GatewayConfig::schema_json()) |
additive keys | the file |
| CLIs | owner |
argv and stdout | vulpine (families tool, pack, models), vulpine-glyphctl, vulpine-reach, the vulpine-<noun> adapters |
rename shims for one release (ADR 0063 §6) | the local user |
Notes:
- Frontend protocol: Contract docs/contracts/frontend.v5.md: the hello, owner admission, features as the minor and every frame. The additive frame families each have a
.v1contract, listed below as riding on this surface. - Admin owner socket: The owner’s control plane; it changes with every Admin slice. Third parties use the frontend protocol, the agent connector, hooks or the CLIs.
- Extension contracts: Packs install behind
[packs] enabled = false; only vulpine’s CI publishes an index in v1. - Reach, client ALPNs: Only
vulpine/pair/1,vulpine/ws/1andvulpine/voice/1are public; every other ALPN is labeled on its own row. - Opt-in ACP agent boundary: No production readiness or activation claim. ACP is not the gateway voice transport.
- Brain (pi RPC): pi’s protocol, not vulpine’s: a brain plugs in through pi or the brain hardpoint slot when it opens.
- Gateway config: Every key is in docs/reference/config.md.
- CLIs: Every command is in docs/reference/cli.md.
Reach ALPNs
QUIC over iroh, behind [reach] enabled = false (ADR 0053). The version is in the name: a protocol change takes a new ALPN. Every public ALPN has a contract file of its own (the rule fails one without); for the rest ADR 0053’s addenda are the specification.
| ALPN | stability | who opens it | what it carries | contract |
|---|---|---|---|---|
vulpine/pair/1 |
public |
an unpaired key holding an invitation | the pairing exchange: the invitation code in, a paired row and its grants out | reach-pair.v1 |
vulpine/ws/1 |
public |
client rows | the frontend protocol’s WebSocket bytes, bridged to the gateway | reach-ws.v1 |
vulpine/voice/1 |
public |
client rows, never delegated | a protocol 5 session as a control stream plus media datagrams (Opus), the phone’s route | reach-voice.v1 |
vulpine/relay/1 |
internal |
client rows | the relay frame protocol (the Admin relay’s frames and stream kinds) | |
vulpine/quic/1 |
owner |
client rows | native QUIC streams for a Rust client, each naming one service from a closed list | |
vulpine/tcp/1 |
owner |
client rows | one stream per TCP connection (ssh first), forwarded to a service’s loopback port from a fixed allow-list | |
vulpine/brain/1 |
owner |
brain rows | the gateway driving a brain endpoint on another machine | |
vulpine/delegate/1 |
owner |
agent-signer keys and the ephemeral keys they sign | an ephemeral key presents its signed delegation; a signer revokes one of its own | |
vulpine/blobs/1 |
owner |
client rows, by explicit grant only | iroh-blobs fetches of a shared voice or avatar pack | |
vulpine/presence/1 |
internal |
the operator’s paired machines | iroh-gossip presence beats between machines | |
vulpine/acp/1 |
experimental |
client rows | ACP sessions, served once the ACP transport lands | |
vulpine/avatar/1 |
experimental |
client rows, never delegated | the avatar side channel, served once its slice lands | |
vulpine/mcp/1 |
experimental |
delegated keys only, never a row’s grant | an agent session over reach, behind [reach] mcp = false |
reach-mcp.v1 |
Protocol version constants
Every *PROTOCOL_VERSION constant in non-test Rust, and the surface whose version it is.
| constant | stability | surface | what |
|---|---|---|---|
PROTOCOL_VERSION in crates/protocol/src/lib.rs |
public |
Frontend protocol | the frontend protocol’s version, 5 |
MIN_PROTOCOL_VERSION in crates/protocol/src/lib.rs |
public |
Frontend protocol | the oldest frontend protocol a gateway accepts, 5 |
ADMIN_PROTOCOL_VERSION in crates/protocol/src/lib.rs |
owner |
Admin owner socket | the Admin socket’s version, 6 |
PROTOCOL_VERSION in crates/phone_core/src/link.rs |
public |
Reach, client ALPNs | the protocol a gateway’s hello must name over voice/1: a copy of the frontend’s 5 in the detached crate |
PROTOCOL_VERSION in crates/voice_gateway/src/hardpoint/wyoming.rs |
public |
Hardpoint worker wires | the Wyoming version the gateway’s TTS client sends |
PROTOCOL_VERSION in crates/openai_speech_shim/src/wyoming.rs |
public |
Hardpoint worker wires | the same Wyoming version, on the shim’s server side |
DISPATCH_PROTOCOL_VERSION in crates/voice_gateway/src/herdr_mutation.rs |
internal |
herdr mutation dispatch | the herdr mutation socket’s version |
Contracts
Every file under docs/contracts/ named <name>.v<N>.md. The title and status are read from the file itself.
| contract | stability | rides on | what crosses | its status |
|---|---|---|---|---|
adapter-degradation.v1 |
public |
Frontend protocol | what one client is told when its speech adapters fail | live on protocol 5, additive |
admin.v6 |
owner |
Admin owner socket | the Admin owner socket: one request, one answer, every request and projection | accepted (2026-11-08) |
answer-card.v1 |
experimental |
Frontend protocol | what the desktop app shows beside a spoken answer | draft, design only |
avatar-action.v1 |
public |
Frontend protocol | the five avatar verbs, their closed arguments and the rig’s vocabulary | live |
avatar-puppet.v1 |
internal |
Frontend protocol | what a rig draws from typed picks: overrides, gaze, clips, the director and the gate | live in the native kit |
capture.v1 |
public |
Frontend protocol | a capture: annotated keyframes, marks, narration and OCR, from a frontend to the brain | landed on protocol 5, additive |
connector.v1 |
public |
Extension contracts | a connector: an account linked on the gateway’s host, walked in the app | landed, on by default |
decision.v1 |
public |
decision.v1 | the typed-decision wire the gateway asks a local scorer over | live, off by default |
dictation.v1 |
public |
Frontend protocol | hold-to-talk, the typed words, and “scratch that” | live on protocol 5, additive |
extension-pack.v1 |
public |
Extension contracts | one installable unit over the existing carriers: the manifest, its record and the one validator | accepted |
file.v1 |
public |
Frontend protocol | a file the gateway shows from its own disk: named on the render, fetched by its hash | landed on protocol 5, additive |
frontend.v5 |
public |
Frontend protocol | the frontend WebSocket: the hello, owner admission, features as the minor, and every frame | accepted |
hardpoint.v1 |
public |
Extension contracts | a typed runtime slot, the implementation a user binds into it, and the qualification before ready | accepted; 1.0 built for stt and tts |
hardpoint.stt.v1 |
public |
Hardpoint worker wires | the stt slot: what a speech-recognition implementation must do to hear a session |
1.0, built |
hardpoint.tts.v1 |
public |
Hardpoint worker wires | the tts slot: what a speech-output implementation must do to carry a session’s voice |
1.0, built |
hooks.v1 |
public |
Extension contracts | a lifecycle boundary’s typed event, from the subsystem that commits it to a consumer the user supplies | accepted |
meeting.v1 |
experimental |
Frontend protocol | typed meeting events into the Gateway’s store | gateway half built, off by default |
links.v1 |
experimental |
Frontend protocol | an operator-activated list of web links | |
page.v1 |
public |
Frontend protocol | a named web page from the gateway’s registry, shown in the render panel | landed on protocol 5, additive |
panel-card.v1 |
public |
Frontend protocol | the panel the brain or a tool fills, drawn in the conversation | landed on protocol 5, additive |
proactive-card.v1 |
public |
Frontend protocol | what Vulpine may say unprompted, and what the operator may answer | live. |
reading.v1 |
public |
Frontend protocol | the read verb on the wire: start_read, reading_control, reading_progress |
live on protocol 5, additive |
reach-mcp.v1 |
experimental |
Reach, fleet ALPNs | one agent session over reach: a delegated key, a hello, then MCP JSON-RPC both ways | accepted; experimental, built |
reach-pair.v1 |
public |
Reach, client ALPNs | pairing a new key with a gateway over reach: the invitation, one stream, one answer line | accepted; public, built |
reach-voice.v1 |
public |
Reach, client ALPNs | one protocol 5 session over reach as a control stream and Opus datagrams | accepted; public, built |
reach-ws.v1 |
public |
Reach, client ALPNs | the frontend protocol’s WebSocket carried over reach, one QUIC stream per WebSocket | accepted; public, built |
satellite-controls.v1 |
public |
Frontend protocol | a satellite’s button, dial and mute switch on the wire | |
sidecar-envelope.v1 |
experimental |
Sidecar envelope | the bounded tree a sidecar window draws: one snapshot, then revisioned patches | draft |
skill.v1 |
public |
Extension contracts | a skill: a procedure in words over catalog tools | |
tool.v1 |
public |
Extension contracts | a catalog tool: one call shape, eight shared actions, one manifest, any handler | accepted |
tool-index.v1 |
public |
Extension contracts | the one list of registered tools, each with its provenance record | accepted |
tool-pack.v1 |
public |
Extension contracts | the unit a user downloads: one strict tar.gz, its pack.json, and the signed tools index | accepted |
turn-budget.v1 |
internal |
Admin owner socket | each turn leg’s millisecond budget | |
utterance.v1 |
owner |
Admin owner socket | one typed record per committed spoken utterance | built, off by default |
visual.v1 |
public |
Frontend protocol | a script visual: a sandboxed Luau program a frontend runs and draws | |
voice-profile-manifest.v1 |
experimental |
Extension contracts | the consent and provenance a Voice Profile candidate must carry | draft, checker landed 2026-10-25 |
acp-integration.v1 |
experimental |
Opt-in ACP agent boundary | the opt-in boundary between operator pi and ACP agents | |
acp-provider-registry.v1 |
experimental |
Opt-in ACP agent boundary | bounded operator declarations before ACP provider admission | |
hc-terminal-rpc.v1 |
experimental |
Opt-in ACP agent boundary | proposed dependency contract for ACP attachment |
Counts
16 surfaces, 13 ALPNs, 7 version constants, 39 contracts; by label: public 40, owner 13, internal 8, experimental 14.