No description
  • Python 56.6%
  • C++ 43.4%
Find a file
Jonas Leder 1803d4000f netbird: allow duplicate randombytes at link time
netbird_lite defines randombytes(), esphome's libsodium does too.
Devices with api encryption fail to link on the duplicate.

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
2026-11-01 23:09:16 +01:00
components/netbird netbird: allow duplicate randombytes at link time 2026-11-01 23:09:16 +01:00
.gitignore init netbird client for esphome 2026-11-01 22:14:11 +01:00
example.yaml init netbird client for esphome 2026-11-01 22:14:11 +01:00
README.md init netbird client for esphome 2026-11-01 22:14:11 +01:00

esphome-netbird

ESPHome external component that puts an ESP32 into a NetBird network. It wraps netbird-lite (Apache-2.0, by Insight-IT GmbH), which is published in the ESP Component Registry as insight-it-gmbh/netbird_lite.

This project is not affiliated with or endorsed by NetBird GmbH or Insight-IT GmbH.

Requirements

  • ESPHome 2026.x, ESP32 family board (tested target: ESP32-C6, see example.yaml)
  • framework: type: esp-idf (netbird-lite is an ESP-IDF component, Arduino is not supported)
  • Wi-Fi or Ethernet working in the same config
  • A NetBird management server and a setup key (see netbird-lite README: self-hosted v0.80.0 tested)

Usage

Copy components/netbird/ into your ESPHome config directory next to your YAML, or use it as an external component from this repository:

external_components:
  - source: github://insight-it-gmbh/esphome-netbird   # or: source: components (local copy)
    components: [netbird]

netbird:
  management_url: https://netbird.example.com
  setup_key: !secret netbird_setup_key     # only needed for the first registration
  hostname: esp32-demo                     # optional, default esp32-<MAC>
  connected:                               # optional binary_sensor: NetBird sync up
    name: NetBird connected
  ip_address:                              # optional text_sensor: NetBird IP
    name: NetBird IP

See example.yaml for a full config. The component needs a network connection before it starts the NetBird client; it polls every 5 s, starts the client once the network is up, and then updates the sensors.

The component adds the netbird-lite IDF component to the build (esp32.add_idf_component) and enables TLS with the certificate bundle. Those options are set by the component, not by you.

Options

Option Required Meaning
management_url yes Management server URL, max 127 characters
setup_key no Setup key, max 63 characters. Used for registration; netbird-lite stops sending it after success
hostname no Peer name in the NetBird dashboard
connected no binary_sensor, on while the device is synced with management
ip_address no text_sensor, the device's NetBird address

Setup keys in firmware can be extracted. Prefer one-off keys, see the netbird-lite security notes.

Limits (from netbird-lite)

  • All traffic goes through the NetBird relay (no direct peer-to-peer connections)
  • IPv4 only, setup-key login only, inbound firewall only
  • Policies with port ranges do not reach the device
  • At most 4 remote peers by default

Layout

components/netbird/
  __init__.py   ESPHome config schema and code generation
  netbird.h     component class
  netbird.cpp   starts netbird-lite once the network is up, publishes the sensors
example.yaml    complete example config

Verification

esphome config example.yaml (with a secrets.yaml) passes. See the notes at the end of the commit or PR for what was compiled.

License

Apache-2.0 (same as netbird-lite). netbird-lite distributions keep its NOTICE file, see its repository.