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
lightinoffice/*. - Zones. The map’s optional
zonesblock 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 initproposes 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 asactdoes 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 plainon(restore: nothing_remembered). The gateway’sallow_kindsandconfirm_subjectshold on both paths. - Aliases.
homectl aliases --writesaves the upstream’s aliases for the subjects it exposes to its own assistant inhome-aliases.jsonbeside the map, soactresolves the names you gave things in Home Assistant. - Locks. A
locksubject (kindlock, optionalbattery_entity) takesstatus(read-only),lock(read back, no undo) andunlock.unlockacts only with the gateway’s redeemed confirm code (--confirmed --confirm-code C); otherwise it is refused asconfirmation_required/requires: confirm_code.lockis never a default kind. - Hazard switches. A
switchwhose 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 ofHAZARD_TOKENS(whole words, plural forgiven).homectl initproposes such a switch withtier: confirmandhazard: <word>(counted ashazard_confirm).actrefuses it unconfirmed asconfirmation_requiredwithconfirm_reason: hazard_confirm_required, so the gateway’s spoken confirmation asks first. A row withtier: confirmis held the same way.allow_hazard: trueon a row exempts it;"hazard_denylist": falseat 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 jazzresolves 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_backmeans the player readplayingwith that stream as itsmedia_content_id. The brain tool refusesstation_not_confirmedwhen only a genericplayingis available. It never infers a station from a title."radio": falseat 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 notifyis the gateway’s Home Assistant companion transport: onenotify.<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}.urgentis time-sensitive on iOS and high priority on Android. The answer is one JSON line withokand a reason code (bad_service,no_token,upstream_refused,unreachable), never the words.homectl notify-serviceslooks that service up, read-only. It returns the notify domain’s names only (phones: themobile_app_*companion services;others), andsuggested, the one to set as[notify] ha_service, when there is exactly one phone.homectl recap --since 3his 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 initproposes 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
upstreamblock. The token is only read from that file or$HA_LONG_LIVED_TOKEN. - A
media_playerrow with"fox9_speaker": trueis a room’s own Vulpine speaker (a roomctl target). Its lines sayown_speaker: true, and the gateway’s ambient room note never reads itsplayingas a TV. - A Ring doorbell or motion sensor is a subject of kind
cameraon the HAringintegration’sevent.*entity:"front-door/doorbell": {"entity": "event.<doorbell>_ding", "kind": "camera", "place": "front door"}. Each new press or motion is a contractcameraevent withlabeldingormotion.homectl initproposes them.
Second sources: Frigate and Ring
- Frigate. A
frigateblock in the map (env_file,topic_prefix,cameras: {<frigate camera>: {subject, room?}}) starts an MQTT thread (mqtt.py, a stdlib 3.1.1 subscriber) onfrigate/events,frigate/reviewsandfrigate/stats. Each event or review becomes acameraevent on<subject>/eventsor<subject>/review. A stats message becomes thehealthblock of astatusline. The thread’s own connect and disconnect arestatuslines, never abye. - Ring snapshots. A
ringblock 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 idfox9-homectl-ring) on ring-mqtt’sring/<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-onlyframes_dir(default~/.local/state/vulpine/ring-frames). Frames are pruned pastretention_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
statuslines (sourcering); ding and motion events come from Home Assistant. To announce Ring MQTT motion when the HA feed is stale, set"announce_events": truein theringblock and"announce": trueon 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 optionalevent_subjectnames the HA motion subject, so the governor’s repeat hold drops duplicates when both feeds run. In[announcements], addmotiontocamera_labelsand setcamera_motion_score(for example0.8to interrupt an idle room); without it the score falls back tocamera_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-relayexists. 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=1renders the Python instead. -
It subscribes to
frigate/reviewswithmqtt.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-fileit resolves togateway.envwhen 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-fileprints 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]] frigateblock to the staged and the live config; re-bootstraps the gateway; and sets the agent’s ON marker. Then rundarwin-rebuild switchwith the nix module, thenjust adapters::frigate-enable <host> --probe.--dryreads and prints the plan. -
checkis the install’s gate: the secret is set and the file is owner-only.probesends one signedrelay.probeevent, which the source routes only log.new-secret --env-file Fappends a fresh secret line and prints only the file and the variable name.