zf-bridge-unraid

Overview

ZoneFoundry Bridge — connects your Sonos system to ZoneFoundry's iOS app, voice assistant, and IM bots (Telegram, WeChat, QQ) via the cloud relay. First launch: pair with a one-time code from your iOS app, container persists credentials in /app/data and reuses on restart. 1-tap updates: the iOS app's Bridges screen surfaces "升级" / "Apply Update" when a new bridge image is published — tap once and the bridge pulls the new image via the mounted docker socket and restarts itself. No SSH or Container Manager interaction needed. Host network mode is required so the bridge can SSDP-discover Sonos speakers on your LAN. Container runs as non-root user (UID 10001) with --cap-drop ALL — make sure the host data path is chowned 10001:10001. The docker socket mount and --group-add 281 (Unraid's docker group GID) grant the bridge permission to pull new images for self-update; remove them if you prefer manual updates only.

Runtime arguments

Network: host
Shell: sh
Privileged: false
Extra Params: --cap-drop ALL --read-only --tmpfs /tmp:rw,nosuid,nodev,size=16m --group-add 281

Template configuration

Relay URLVariable

ZoneFoundry cloud relay WebSocket URL.

Target: ZF_RELAY_URL
Default: wss://relay.zonefoundry.dev/ws
Value: wss://relay.zonefoundry.dev/ws

Pair Code (first launch only)Variable

One-time 6-letter code from your iOS app's Add Bridge screen. Only needed for first launch — once paired, container caches credentials in /app/data and you can clear this field.

Target: ZF_PAIR_CODE

User ID (override)Variable

Advanced: explicit user_id from existing pairing (skips pair-code redeem). Leave empty to use pair code instead.

Target: ZF_USER_ID

Agent Secret (override)Variable

Advanced: explicit secret matching User ID. Leave empty to use pair code instead.

Target: ZF_AGENT_SECRET

Connector ID (override)Variable

Advanced: explicit connector identity for multi-bridge users. Leave empty for default-legacy.

Target: ZF_CONNECTOR_ID

Data VolumePathrw

Persistent data: cached pairing credentials. Must be chowned 10001:10001 on host (chown -R 10001:10001 /mnt/user/appdata/zonefoundry-bridge).

Target: /app/data
Default: /mnt/user/appdata/zonefoundry-bridge
Value: /mnt/user/appdata/zonefoundry-bridge

Docker Socket (1-tap update)Pathrw

Mounts the host's docker socket so the bridge can pull and apply its own image updates when you tap '升级' / 'Apply Update' in the iOS app's Bridges screen. Combined with --group-add 281 in Extra Parameters, the non-root bridge user gets permission to talk to Docker. Remove this mount and the --group-add flag if you prefer to update manually via Apply Update on this template.

Target: /var/run/docker.sock
Default: /var/run/docker.sock
Value: /var/run/docker.sock

Links

Template Support Docker Hub Project

Details

Repository

zonefoundry/bridge:latest

Registry

https://hub.docker.com/r/zonefoundry/bridge

Last Updated2026-05-03

First Seen2026-05-06

Run zf-bridge-unraid on Unraid.

zf-bridge-unraid is listed in Community Apps for Unraid OS. Explore Unraid to build a flexible home server, NAS, or homelab.

Explore Unraid OS