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

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

Was this page helpful?