zonefoundry/bridge repository overview

⁠ZoneFoundry Bridge

Local home-network agent for ZoneFoundry. Runs alongside Sonos speakers, exposes them to the ZoneFoundry assistant (relay) + Apple Home (HAP) + Siri.

⁠Tag taxonomy

⁠Recent releases (most recent first)

| Tag | Pushed (UTC) | Highlights | Status | |--------------------------------------|---------------------| | 0.1.108-image-tag-fix | 2026-05-27 11:11 | agent_recreate.go uses repo:latest (not @digest) so Unraid CA shows "available" not "not available" badge after 1-tap update | 🆕 待 Sam真测 |--------------------------------------------------------------------------------------------------|-------------| | 0.1.107-apple-sn-and-enqueue | 2026-05-27 07:32 | Per-household Apple Music sn= extraction; play-uri --enqueue flag | ✅ Sam真测 | | 0.1.106-play-uri-enqueue | 2026-05-27 07:21 | play-uri --enqueue (tail-append) flag for batch enqueue | OK | | 0.1.105-recreate-fix | 2026-05-27 06:21 | agent_recreate.go drops inherited Config.User to fix 1-tap update on stale digests | ✅ Sam真测 | | 0.1.104-allow-raw-commands | 2026-05-26 08:20 | Bridge accepts raw shell command pass-through (audit-guarded) | OK | | 0.1.103-split-brain-union | 2026-05-26 08:05 | Topology split-brain union — merge speakers visible from both halves | OK | | 0.1.102-bullet-proof-switch | 2026-05-26 06:54 | HomeKit scene Switch auto-reset + safety loop | OK | | 0.1.101-grouped-poll | 2026-05-25 12:44 | Group-aware Lightbulb transport poll (members poll coordinator) | OK | | 0.1.100-hub-repoll | 2026-05-25 | HAP FirmwareRevision bump 5s post-startup → Hub re-poll nudge | OK |

⁠Required Docker capabilities

The default Unraid CA template uses --cap-drop ALL without --cap-add. Add these to avoid restart loops:

--cap-add SETUID,SETGID,CHOWN,FOWNER,DAC_OVERRIDE

Without these, the entrypoint cannot:

• Drop privileges to the zf user (SETUID/SETGID)
• Write its credentials cache (DAC_OVERRIDE)
• Normalize HAP storage ownership (CHOWN/FOWNER)

The container will enter a Restarting (1) crash loop with Permission denied on /app/data/agent-credentials.env.

Hotfix without changing template (lose-cap workaround):

chmod -R 0777 /mnt/user/appdata/zonefoundry-bridge/

⁠Required environment variables

⁠Volume mounts

⁠1-tap update protocol

iOS triggers via POST /api/bridges/{cid}/apply-update. Bridge pulls :latest via docker socket, recreates self via containerCreateBody derived from current inspect.

Known failure modes:

• Stale image digest → previous container's user mismatch → unable to find user zf (fixed in 0.1.105+)
• Cap-drop ALL → entrypoint cannot rewrite credentials → restart loop (chmod 0777 host volume as hotfix; add --cap-add in Unraid template as proper fix)

⁠Repository

Source: https://github.com/kisssam6886/zonefoundry⁠ (private) Unraid CA template: https://github.com/selfhosters/unRAID-CA-templates⁠ (zf-bridge-unraid.xml)