AvianVisitors/avian/forwarding

Optional: forwarding the collage off your local network

Default install hosts the collage at http://birdnet.local/collage/ on your LAN with no auth. If you want it accessible from anywhere — or piped into Home Assistant / MQTT — pick one of the recipes below.

Each recipe is independent. Skip what you don't need.

---

1. Cloudflare Tunnel (recommended for public access)

Gives you a public HTTPS URL with no port forwarding and no exposed home IP. Free Cloudflare account required.

Install cloudflared on the Pi:

sudo mkdir -p /usr/share/keyrings
curl -fsSL https://pkg.cloudflare.com/cloudflare-main.gpg \
  | sudo tee /usr/share/keyrings/cloudflare-main.gpg >/dev/null
echo 'deb [signed-by=/usr/share/keyrings/cloudflare-main.gpg] https://pkg.cloudflare.com/cloudflared $(lsb_release -cs) main' \
  | sudo tee /etc/apt/sources.list.d/cloudflared.list
sudo apt update && sudo apt install -y cloudflared

Authenticate + create the tunnel:

cloudflared tunnel login
cloudflared tunnel create birds

Add a public route — pick a hostname on a zone you own:

cloudflared tunnel route dns birds birds.your-domain.com

Configure the tunnel to point at the local Caddy:

sudo cp avian/forwarding/cloudflared.yml /etc/cloudflared/config.yml
# edit /etc/cloudflared/config.yml — set `tunnel:` to your tunnel UUID
sudo cloudflared service install
sudo systemctl restart cloudflared

Adding password protection on the public URL. With Cloudflare in front, gate the public endpoint via Cloudflare Access (zero-trust free tier supports up to 50 users) — see Cloudflare docs. The local LAN URL remains unprotected. If you'd rather use HTTP Basic auth on Caddy itself, see forwarding/caddy-auth.caddy.

---

2. Home Assistant — surface latest detection as a sensor

Add to configuration.yaml:

rest:
  - resource: http://birdnet.local/api/recent.json?hours=1
    scan_interval: 60
    sensor:
      - name: "Latest Bird"
        value_template: >
          {% set top = value_json.species | sort(attribute='last_seen', reverse=true) | first %}
          {{ top.com if top else 'none' }}
        json_attributes_path: "$.species[0]"
        json_attributes:
          - sci
          - n
          - last_seen
          - best_conf

Use the sensor in automations — flash a light when a new species is heard, etc.

---

3. MQTT — fan out detections to other services

If you already run an MQTT broker, publish every new detection. Install paho-mqtt and run the bridge:

sudo pip3 install paho-mqtt --break-system-packages
cp avian/forwarding/mqtt-bridge.py ~/avian-mqtt.py
# edit ~/avian-mqtt.py — broker host, topic prefix
sudo cp avian/forwarding/avian-mqtt.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now avian-mqtt

The bridge polls /api/recent.json?hours=1 once a minute and publishes new species under birdnet/<slug> with the full record as JSON payload.