---
title: "Home adapter"
description: "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."
type: "living"
source: "runtime/home_bridge/README.md"
verified: "2026-11-14"
group: "Adapters and integrations"
---

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

