- Python 56.6%
- C++ 43.4%
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> |
||
|---|---|---|
| components/netbird | ||
| .gitignore | ||
| example.yaml | ||
| README.md | ||
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.