Home

ESP32 Tailnet Gateway — Mattboxx Edition

One ESP32. Multiple Tailnet roles. Enable only what you need.

Community firmware for the ESP32-S3 that joins your Tailscale or Headscale tailnet and then plays the network roles you switch on: a selective LAN → Tailnet service gateway, a subnet router, a Wi-Fi access-point gateway for IoT devices, an exit node, a Wake-on-LAN recovery node and an optional MQTT / Home Assistant / ntfy / SNMP endpoint.

Current firmware: v2.0.2 — download · browser installer · changelog

Start here

1. Getting Started: what you need and the shortest path to a working gateway.
2. Installation: browser installer, Easy Install for Windows/macOS/Linux, or manual images.
3. First Boot Setup: pair the board, set the admin password and Wi-Fi.
4. Roles Overview: choose the one role you need first.

Guides

Topic	Pages
Reach one remote service from LAN devices	Service Gateway
Reach your LAN from the tailnet	Subnet Router
Route Internet traffic	Exit Node
Self-hosted control server	Headscale
Wake and check a NAS or PC	Recovery and Wake-on-LAN
Monitoring and evidence	Monitoring and Health
MQTT, Home Assistant, ntfy, SNMP	Integrations
Keep it running	Updating, Backup and Restore, Troubleshooting
Boards and wiring	Hardware, Ethernet W5500
Trust and limits	Security Model
Questions	FAQ
Project	Release History, Contributing and Credits

What it is not

It is not the official Tailscale client and is not affiliated with Tailscale Inc., the Headscale project or Espressif. It does not claim full official-client policy parity, Secure Boot, signed images or out-of-band management. A microcontroller on a shared 2.4 GHz radio suits control, telemetry, dashboards and SSH — not video or bulk transfers.

The authoritative, versioned documentation lives in the repository's docs folder and on the project website. This wiki summarizes it and links to the full guides.