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

Home adapter

homectl, the events-in adapter (ADR 0034) outside the gateway through which fox9 controls the lights and devices in the house: it holds the Home Assistant client, emits the house (lights, speakers, switches, presence) as fox9 subjects in JSON lines, and runs one home verb at a time with homectl act --subject <subject> --verb <verb>; subcommands init, list, probe, subjects, run, act.

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

home_bridge — homectl, the events-in adapter

homectl is the reference implementation of the events-in contract (ADR 0034; docs/integrations/README.md, contract v1). It runs on the gateway host as a child of the gateway ([home_bridge] enabled = true). It holds Vulpine’s one client for house state, Home Assistant’s WebSocket API, and emits Vulpine’s home vocabulary as JSON lines keyed by subjects Vulpine owns.

homectl is the Rust binary vulpine-home (crates/vulpine_home), the gateway’s default. just setup::install-vulpine-home installs it at ~/.local/state/foxline/bin/vulpine-home, with a homectl link. A [home_bridge] homectl path ending in .py runs the retired retired/homectl/homectl.py under [home_bridge] python.

Subcommands: init, list, probe, subjects, aliases, recap, run, act, undo, restore, notify and notify-services.

ssh <gateway-host> ~/.local/state/foxline/bin/vulpine-home list
ssh <gateway-host> ~/.local/state/foxline/bin/vulpine-home probe
ssh <gateway-host> ~/.local/state/foxline/bin/vulpine-home run | head

Acting on the house

homectl act --subject <subject> --verb <verb> [--value N] runs one verb for the gateway’s home-verb route and for the brain tool pi_home_act. The light verbs are on, off, toggle and brightness.

  • Groups. A plural phrase is a group: “the office lights” is every light in office/*.
  • Zones. The map’s optional zones block names a set of rooms with one word: {"downstairs": ["office", "living-room"], "upstairs": {"rooms": ["bedroom"], "aliases": ["up stairs"]}}. “All the downstairs lights” is then every light in those rooms. A room of the same name wins; “all” and “every” are a group’s filler only. homectl init proposes zones from the upstream’s floor registry.
  • Restore. homectl restore --subject <words> [--room R] is “turn the office lights back on”. The gateway keeps a memory of what its own verbs turned off (crates/voice_gateway/src/home_restore.rs) and sends it on stdin as a JSON array of {subject, verb, value?}. The adapter resolves the words as act does and replays only the remembered members (verb: restore, restore: remembered), so a lamp switched off by hand stays off. With nothing remembered it is a plain on (restore: nothing_remembered). The gateway’s allow_kinds and confirm_subjects hold on both paths.
  • Aliases. homectl aliases --write saves the upstream’s aliases for the subjects it exposes to its own assistant in home-aliases.json beside the map, so act resolves the names you gave things in Home Assistant.
  • Locks. A lock subject (kind lock, optional battery_entity) takes status (read-only), lock (read back, no undo) and unlock. unlock acts only with the gateway’s redeemed confirm code (--confirmed --confirm-code C); otherwise it is refused as confirmation_required / requires: confirm_code. lock is never a default kind.
  • Hazard switches. A switch whose entity id, label or subject carries a hazard word is never auto-tier. The words are heater, garage, gate, sprinkler, pump, oven, stove, kettle, iron, furnace, boiler, lock, valve, water and the rest of HAZARD_TOKENS (whole words, plural forgiven). homectl init proposes such a switch with tier: confirm and hazard: <word> (counted as hazard_confirm). act refuses it unconfirmed as confirmation_required with confirm_reason: hazard_confirm_required, so the gateway’s spoken confirmation asks first. A row with tier: confirm is held the same way. allow_hazard: true on a row exempts it; "hazard_denylist": false at the top of the map turns the list off. Lights are not gated.

Radio and Spotify

A media player takes play_station: homectl act --subject kitchen/player --verb play_station --query "groove salad". It asks the public Radio Browser directory for working stations by name, most clicked first. The server comes from the all.api.radio-browser.info round-robin, with a 5 s timeout and no key. It plays the top station’s resolved stream with one media_player.play_media (media_content_type: music).

  • The query is words, at most 64 characters, never a URL. The subject must name one player.
  • The subject can be a room’s spoken name: with one player in that room, --subject studio --verb play_station --query jazz resolves it. Several players ask which; an unconfigured room does nothing.
  • Refusals: bad_query, no_station, station_unreachable. The receipt names the station, never its stream URL.
  • ack.detail: station_read_back means the player read playing with that stream as its media_content_id. The brain tool refuses station_not_confirmed when only a generic playing is available. It never infers a station from a title.
  • "radio": false at the top of the map turns the verb off.

Spotify Connect reuses the same registry. On a media_player subject, the optional "spotify_device": "Studio Connect" maps its aliases, label and room to that exact live Connect display name, so pi_mac_control can transfer playback by any of them. No mapping is built in. A missing Connect device, or an alias shared by several targets, is refused without playing elsewhere.

Notify and recap

  • homectl notify is the gateway’s Home Assistant companion transport: one notify.<service> call, with the service named by the gateway’s [notify] ha_service. The request is one JSON object on stdin, {service, title, message, urgent}. urgent is time-sensitive on iOS and high priority on Android. The answer is one JSON line with ok and a reason code (bad_service, no_token, upstream_refused, unreachable), never the words.
  • homectl notify-services looks that service up, read-only. It returns the notify domain’s names only (phones: the mobile_app_* companion services; others), and suggested, the one to set as [notify] ha_service, when there is exactly one phone.
  • homectl recap --since 3h is the read-only “what happened while I was out”. It reads HA’s logbook and history for the mapped subjects only and prints one bounded table per subject: changes, last state, times and a closed-word cause. It holds no upstream identifier.

The map

Subjects live in ~/.config/vulpine/home.json on the gateway host (--map or $VULPINE_HOME_FILE names another). home.example.json here is an example map.

  • homectl init proposes a map from the upstream’s current states; a magic-areas fused room presence becomes <room>/occupancy. Edit the names afterwards.
  • The upstream’s URL and token file are in the map’s upstream block. The token is only read from that file or $HA_LONG_LIVED_TOKEN.
  • A media_player row with "fox9_speaker": true is a room’s own Vulpine speaker (a roomctl target). Its lines say own_speaker: true, and the gateway’s ambient room note never reads its playing as a TV.
  • A Ring doorbell or motion sensor is a subject of kind camera on the HA ring integration’s event.* entity: "front-door/doorbell": {"entity": "event.<doorbell>_ding", "kind": "camera", "place": "front door"}. Each new press or motion is a contract camera event with label ding or motion. homectl init proposes them.

Second sources: Frigate and Ring

  • Frigate. A frigate block in the map (env_file, topic_prefix, cameras: {<frigate camera>: {subject, room?}}) starts an MQTT thread (mqtt.py, a stdlib 3.1.1 subscriber) on frigate/events, frigate/reviews and frigate/stats. Each event or review becomes a camera event on <subject>/events or <subject>/review. A stats message becomes the health block of a status line. The thread’s own connect and disconnect are status lines, never a bye.
  • Ring snapshots. A ring block in the map (env_file, topic_prefix, location, frames_dir, retention_s, event_types, cameras: {<ring device id>: {subject, place, label, room?}}) starts a second MQTT thread (client id fox9-homectl-ring) on ring-mqtt’s ring/<location>/camera/+/snapshot/{image,attributes}. Each motion or ding snapshot of a mapped camera becomes that camera’s latest frame: <subject>.jpg + <subject>.json (event, timestamp, received time, size) in an owner-only frames_dir (default ~/.local/state/vulpine/ring-frames). Frames are pruned past retention_s (7 days) or when the map drops the camera. The payload is untrusted: without JPEG magic, a 2 MB cap, a sane timestamp, a mapped device and the map’s location, nothing is written. Interval and on-demand snapshots are skipped. visionctl describe --place "front door" answers from that frame with its age and event type, never by opening the camera’s go2rtc stream.
  • Ring motion announcements. By default the Ring thread emits only status lines (source ring); ding and motion events come from Home Assistant. To announce Ring MQTT motion when the HA feed is stale, set "announce_events": true in the ring block and "announce": true on each chosen camera; the rest stay silent. The bridge admits only fresh (at most 60 s), non-retained motion snapshots, once per camera and timestamp, and never restored snapshots or doorbell presses. The optional event_subject names the HA motion subject, so the governor’s repeat hold drops duplicates when both feeds run. In [announcements], add motion to camera_labels and set camera_motion_score (for example 0.8 to interrupt an idle room); without it the score falls back to camera_other_score. Quiet hours, room routing, budget and repeat holds still apply.

homectl run --replay <tap> feeds a raw state_changed JSONL tap through the contract. summarize_tap.py counts a tap by domain and flip.

frigate_relay — Frigate’s alerts, signed, to the webhook intake

Frigate cannot sign a webhook, so the relay is its sender. It is the Rust binary vulpine-frigate-relay (crates/vulpine_frigate_relay), installed by just setup::install-vulpine-frigate-relay at ~/.local/state/foxline/bin/vulpine-frigate-relay. frigate_relay.py here does the same work, with mqtt.py beside it. The commands, output lines and secret handling below are the same for both.

The relay is not a child of the gateway. It runs in one of two ways, never both on one host, since they share one MQTT client id:

  • as the nix host configuration’s user agent org.nixos.fox9-frigate-relay, OFF until ~/.config/foxline/frigate-relay exists. This agent runs the .py.

  • as the launchd job com.voidfab.vulpine.frigate-relay (deploy/launchd/com.voidfab.vulpine.frigate-relay.plist.tmpl, just adapters::frigate-relay-install). The template runs the binary; frigate-relay-install python=1 renders the Python instead.

  • It subscribes to frigate/reviews with mqtt.py, its own client id, and the credentials homectl reads.

  • It keeps the alerts and sends each review id once. The POST goes to http://127.0.0.1:8796/hooks/frigate, signed with the Standard Webhooks HMAC. A detection-only review is logged once and never sent.

  • The secret is VULPINE_WEBHOOK_FRIGATE_SECRET, read from the owner-only env file of the gateway’s env. With no --env-file it resolves to gateway.env when that exists (a nix-owned gateway agent), else to ~/.local/state/foxline/overlay.env.mirror (a plist-owned gateway; the roll writes the plist’s env from overlay.env and keeps this copy). env-file prints the resolved file and whether the secret is set, never the value. The secret is never in argv, a log line or stdout.

  • To enable it on a plist-owned gateway host, run from your workstation just adapters::frigate-enable <host>. It generates the secret on the host into overlay.env, the mirror and the gateway plist; adds the [[webhooks.sources]] frigate block to the staged and the live config; re-bootstraps the gateway; and sets the agent’s ON marker. Then run darwin-rebuild switch with the nix module, then just adapters::frigate-enable <host> --probe. --dry reads and prints the plan.

  • check is the install’s gate: the secret is set and the file is owner-only. probe sends one signed relay.probe event, which the source routes only log. new-secret --env-file F appends a fresh secret line and prints only the file and the variable name.

Was this page helpful?