Sheaf for Home Assistant

Bring your Sheaf plural system into Home Assistant. This integration surfaces who is currently fronting as Home Assistant entities so you can drive automations off front changes (lighting, climate, presence, announcements, reminders) and change the front from Home Assistant.

Works with the hosted instance and any self-hosted Sheaf instance.

Status: early. See the issue tracker for what is and isn't wired up yet.

Install

HACS (custom repository)

1. In HACS, add https://github.com/sheaf-project/sheaf-ha as a custom repository of type Integration.
2. Install Sheaf, then restart Home Assistant.
3. Go to Settings > Devices & Services > Add Integration and search for Sheaf.

Manual

Copy custom_components/sheaf/ into your Home Assistant config/custom_components/ directory and restart.

Set up

You need an API key. In the Sheaf web UI: Settings > API Keys > Create, with these scopes:

Scope	Needed for
fronts:read	reading current fronters (always)
members:read	resolving member names, avatars, groups (always)
system:read	identifying your system (always)
fronts:write	the switch services and the quick-switch control
notifications:read, notifications:write	the webhook transport only

API keys can't create other keys, so this must be done from the web UI. The key is shown once.

Adding the integration is a short wizard:

1. Connect - enter your instance URL (e.g. https://app.sheaf.sh) and the key.
2. Transport - pick how updates arrive (see below). Your choice is tested before you can continue, so a disabled stream or an unreachable webhook is caught up front rather than failing silently later.
3. Members - optionally narrow which members are surfaced, picking from your actual member and group lists.

All of this can be changed afterwards from the integration's Configure button.

Entities

• binary_sensor per member - on when that member is fronting. Carries pronouns, colour, fronting-since, and the member avatar as its picture. Great for per-member automations.
• sensor "Current fronters" - the current front as text, with a structured fronters attribute (co-fronting is fully supported; the fronting set is the union of all open fronts).
• sensor "Fronter count" - number of people currently fronting (custom fronts like Asleep/Away are excluded).
• select "Front" - quick single-member switch. It's single-value, so it reads unknown while more than one member is fronting; use the per-member switches or the services for co-fronting.
• switch per member (optional) - toggle a member's fronting on/off, so you can build a co-front by turning several on. Enable Add a fronting switch per member in options; needs fronts:write. Turning one off ends the front they were in and re-creates it for whoever remains, so the removed member's time stays in your history.

Events

• sheaf_front_joined fires on the Home Assistant event bus when a member joins a front - including when they were already fronting and a new front starts with them in it (e.g. a switch from Alex to Alex + Sam fires for both). Data: member_id, member_name, front_id, new_front (true if the front itself is new), was_already_fronting (true if they were already fronting elsewhere and continued into this front, e.g. a replace), started_at, and cofronters. Only surfaced members appear, matching your privacy filter. Use it with an event trigger:

  trigger:
    - platform: event
      event_type: sheaf_front_joined
      event_data:
        member_name: Sam

Services

• sheaf.set_front - set the front to one or more members (replace to switch cleanly, or add co-fronters). Optional custom_status.
• sheaf.add_fronter / sheaf.remove_fronter - adjust who's fronting without a full switch.
• sheaf.end_front - end the current front. To drop a single member instead, use sheaf.remove_fronter.
• sheaf.set_custom_status - set the free-text status on the current front.

See the automation cookbook for copy-paste examples.

Keeping up to date (transport)

Choose in the integration's options:

• Polling (default) - checks every 5 minutes (minimum 1 minute). Simple, works everywhere.
• Live stream (push, recommended) - Home Assistant holds an open connection to Sheaf's front-change stream and updates within a second or so. Needs no inbound reachability, so it works even when Home Assistant is only reachable on your LAN. Requires a Sheaf instance with the front stream enabled (FRONT_STREAM_ENABLED, on by default).
• Webhook (push) - Sheaf pushes front changes to Home Assistant. Home Assistant must be reachable from the Sheaf instance. Deliveries are HMAC-verified. If your Home Assistant is on a private address, the Sheaf operator must add your subnet to WEBHOOK_ALLOWED_PRIVATE_CIDRS on the server, otherwise Sheaf's SSRF protection blocks it. Prefer the live stream unless you have a reason not to.

All transports keep polling in the background as a backstop and reconcile against the API, so state stays correct even if a push is missed.

If a transport isn't behaving, see Troubleshooting.

Privacy: which members are surfaced

By default every member becomes an entity. You can narrow this in the options, using the same include/exclude model Sheaf uses for notification visibility:

• Member rules (include_members / exclude_members) always win.
• Group rules (include_groups / exclude_groups) apply to a member's groups; exclusions win on a conflict.
• Base set (base_all_members, base_include_private) is the fallback.

Excluded members get no entity at all and never appear in the aggregate sensor, the count, the quick-switch options, or any fired event. To build an allowlist, turn off Surface all members by default and add include rules.

License

AGPL-3.0-or-later. See LICENSE.