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

Connectors

Connectors: a third-party account linked on the gateway's host so a brain tool works (WhatsApp, Gmail, the Dot, feeds, Apple Health, OBS); one row in the gateway's registry joins a setup census row (its state) with what it unlocks, its one action and the steps read from its README at build time; the Admin's Setup section draws them as a Connections card (AdminSetupCensus.connections) and the Glyph's welcome window as a Connections page from <state>/connections/connections.json; the menu says Connect accounts while one waits.

Living doc, checked against the code 2026-11-14

connector.v1 — a connector: an account linked on the gateway’s host, walked in the app

  • Status: landed, on by default.
  • Scope: a connector is a third-party account linked on the gateway’s host so a brain tool can work: WhatsApp paired with wacli, a Gmail sign-in, the Dot’s worker, the feed list, the Apple Health export, the OBS connection file. Setup happens in the app. Vulpine.app’s welcome window (a Connections page after the permissions) and the Gateway window’s Setup section (a Connections card) walk each one from its live state.
  • The plugin point: a connector registers one row in the gateway’s registry (crates/voice_gateway/src/connectors.rs REGISTRY) and joins one setup census row that says its state. Neither UI names a connector: both draw whatever rows the gateway sends.

The row

A registered connector says:

field what
id the setup census row it joins (whatsapp); that row carries label, state, why and next_step
unlocks what connecting it unlocks, in plain words
tools the brain tools it unlocks (pi_whatsapp)
action the one action, as its button says (Link WhatsApp): it opens the steps
guide the README that walks it, repo-relative (runtime/messages/README.md)
steps that README’s steps, in order

The steps are read from the README at build time (include_str! and vulpine_onboarding::connectors::guide_steps). The registry names the README and the headings of the sections that walk it. A section gives its list items, or its paragraphs when it has no list. An indented code block joins the step before it as a code span; emphasis and links read as words. There are at most 10 steps, each cut at a word within 480 characters. The README is the one source: an edit there reaches both pages at the next build. Every registered guide has at least one step and names a file that exists, and every held tool (crates/voice_gateway/src/held_tools.rs) has a registered connector.

Facts and the adapter’s status

A row may carry facts: labeled plain words that say what the connector does once connected. facts is optional on both wires; an empty list is left out. A row has at most six facts, a label within 48 characters and its words within 240. They come from two places, in this order:

  1. the registry row’s about (fixed: the feeds’ Reads aloud, Adds a feed and Cadence);
  2. the adapter’s own status file, which the held tool names (Status in crates/voice_gateway/src/held_tools.rs): a JSON object {schema: "vulpine.connector-status.v1", at_unix, fresh_at_unix?, facts: [{label, says}]}, at most 64 KiB, written owner-only by the adapter (tools/feeds/feedctl.py writes feeds-status.json beside the feed store at every list change and every refresh: Sources and Last fetched). The gateway reads it with vulpine_onboarding::connectors::read_status, which cuts each fact to its bounds and drops an empty one; a file of another schema is ignored.

The status file’s fresh_at_unix is the adapter’s last real run. A held tool may give a freshness rule (Fresh): how old that run may be, why when it is older, and the one next step. A row that is set up and on, whose last run is older, reads degraded (Not healthy) with that next step. The feeds’ rule is two hours, four of the refresh timer’s 30-minute passes. A status file with no run yet, or none at all, says nothing; readiness speaks for those. The bind never reads the status.

States are the census’s closed words. ok is Connected. not_set_up and degraded wait on the person and count in Vulpine.app’s menu and the pages’ summaries. off is a choice (switched off in the Admin’s Tools section, or no loadout lists the tool) and is drawn quiet.

Where the rows go

  • The Admin reads them in the setup census: AdminSetupCensus.connections (AdminSetupConnection, optional on the wire). A gateway without connector.v1 sends none and the card is not drawn. Each connection joins the row with the same id, once: validate_setup_census refuses a connection without its row or named twice. The Admin socket’s sanitizer takes unlocks and steps as prose: a path or an address inside a step hides only that word. The connectors’ rows are drawn in the card, not in the Setup section’s families.
  • Vulpine.app on the gateway’s Mac reads <state>/connections/connections.json (vulpine.connections.v1: at_unix and the joined rows). The folder is owner-only and the file is a staging file renamed over. The gateway rewrites it when a row changes and at least every minute; its publisher reads the held tools’ readiness every 10 s. The page is ConnectionsView: source (this_mac, stale after 180 s without a rewrite, elsewhere with no record), the rows, left (waiting), all_set and a summary. Vulpine.app on another Mac finds no record and says where connections are set up. The right-click menu says “Connect accounts…” while every grant is on and a connector waits (welcome_entry’s connections_left), and the window then opens on the page.

Wire names never contain token. Nothing here links, signs in or writes: the steps say where that happens (a terminal, a phone, ChatGPT), and the row turns Connected by itself on the next read.

Adding a connector

  1. Its readiness: a setup census row whose state says whether it is linked (a held tool’s checks in held_tools.rs, or any census row).
  2. Its README: a section with numbered steps, ending with what the person sees when it worked.
  3. One Connector row in REGISTRY: the census id, unlocks, tools, action and the Guide (the README’s path, include_str! of it, the section headings).

The record Vulpine.app reads carries only rows its publisher reads without the Admin service, which are the held tools’ rows. A connector that joins another census row shows in the Admin only.

Was this page helpful?