---
title: "API surfaces"
description: "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."
type: "generated"
source: "docs/reference/api-surfaces.md"
---

> **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 `.v1` contract, 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/1` and `vulpine/voice/1` are 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`](/docs/contracts/reach-pair.v1) |
| `vulpine/ws/1` | `public` | client rows | the frontend protocol's WebSocket bytes, bridged to the gateway | [`reach-ws.v1`](/docs/contracts/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`](/docs/contracts/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`](/docs/contracts/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`](/docs/contracts/adapter-degradation.v1) | `public` | Frontend protocol | what one client is told when its speech adapters fail | live on protocol 5, additive |
| [`admin.v6`](/docs/contracts/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`](/docs/contracts/answer-card.v1) | `experimental` | Frontend protocol | what the desktop app shows beside a spoken answer | draft, design only |
| [`avatar-action.v1`](/docs/contracts/avatar-action.v1) | `public` | Frontend protocol | the five avatar verbs, their closed arguments and the rig's vocabulary | live |
| [`avatar-puppet.v1`](/docs/contracts/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`](/docs/contracts/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`](/docs/contracts/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`](/docs/contracts/decision.v1) | `public` | decision.v1 | the typed-decision wire the gateway asks a local scorer over | live, off by default |
| [`dictation.v1`](/docs/contracts/dictation.v1) | `public` | Frontend protocol | hold-to-talk, the typed words, and "scratch that" | live on protocol 5, additive |
| [`extension-pack.v1`](/docs/contracts/extension-pack.v1) | `public` | Extension contracts | one installable unit over the existing carriers: the manifest, its record and the one validator | accepted |
| [`file.v1`](/docs/contracts/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`](/docs/contracts/frontend.v5) | `public` | Frontend protocol | the frontend WebSocket: the hello, owner admission, features as the minor, and every frame | accepted |
| [`hardpoint.v1`](/docs/contracts/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`](/docs/contracts/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`](/docs/contracts/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`](/docs/contracts/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`](/docs/contracts/meeting.v1) | `experimental` | Frontend protocol | typed meeting events into the Gateway's store | gateway half built, off by default |
| [`links.v1`](/docs/contracts/links.v1) | `experimental` | Frontend protocol | an operator-activated list of web links |  |
| [`page.v1`](/docs/contracts/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`](/docs/contracts/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`](/docs/contracts/proactive-card.v1) | `public` | Frontend protocol | what Vulpine may say unprompted, and what the operator may answer | live. |
| [`reading.v1`](/docs/contracts/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`](/docs/contracts/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`](/docs/contracts/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`](/docs/contracts/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`](/docs/contracts/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`](/docs/contracts/satellite-controls.v1) | `public` | Frontend protocol | a satellite's button, dial and mute switch on the wire |  |
| [`sidecar-envelope.v1`](/docs/contracts/sidecar-envelope.v1) | `experimental` | Sidecar envelope | the bounded tree a sidecar window draws: one snapshot, then revisioned patches | draft |
| [`skill.v1`](/docs/contracts/skill.v1) | `public` | Extension contracts | a skill: a procedure in words over catalog tools |  |
| [`tool.v1`](/docs/contracts/tool.v1) | `public` | Extension contracts | a catalog tool: one call shape, eight shared actions, one manifest, any handler | accepted |
| [`tool-index.v1`](/docs/contracts/tool-index.v1) | `public` | Extension contracts | the one list of registered tools, each with its provenance record | accepted |
| [`tool-pack.v1`](/docs/contracts/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`](/docs/contracts/turn-budget.v1) | `internal` | Admin owner socket | each turn leg's millisecond budget |  |
| [`utterance.v1`](/docs/contracts/utterance.v1) | `owner` | Admin owner socket | one typed record per committed spoken utterance | built, off by default |
| [`visual.v1`](/docs/contracts/visual.v1) | `public` | Frontend protocol | a script visual: a sandboxed Luau program a frontend runs and draws |  |
| [`voice-profile-manifest.v1`](/docs/contracts/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`](/docs/contracts/acp-integration.v1) | `experimental` | Opt-in ACP agent boundary | the opt-in boundary between operator pi and ACP agents |  |
| [`acp-provider-registry.v1`](/docs/contracts/acp-provider-registry.v1) | `experimental` | Opt-in ACP agent boundary | bounded operator declarations before ACP provider admission |  |
| [`hc-terminal-rpc.v1`](/docs/contracts/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.
