Formerly ESP32 Tailnet Gateway: same firmware, same settings, new name.
Mattboxx Edition · One ESP32. Remote access, Wake-on-LAN and backup internet. Enable only what you need.
Tailscale / Headscale gateway · Wake-on-LAN from Telegram or ntfy, no VPN needed · Ethernet and 4G/LTE uplinks for IoT
Use it as a Tailnet gateway, as a stand-alone Wake-on-LAN node you command from Telegram or ntfy, or as an IoT gateway that stays online over Ethernet or a mobile SIM when Wi-Fi drops. Each role is optional: you do not need Tailscale to use Wake-on-LAN or the backup uplinks.
ESP32-S3 N8R8 / N16R8 · 8 MB octal PSRAM
Install in your browser · Download firmware · Setup guide · Website
| Use case | What the ESP32 does |
|---|---|
| Wake and check a NAS or PC — no VPN needed | Send Wake-on-LAN and verify that the device answers, from a Telegram bot or an ntfy topic. Works with or without Tailscale. Setup and command reference. |
| Keep IoT devices online | Use a mobile SIM or wired Ethernet as the main or the backup uplink, with automatic failover and an optional monthly data limit. SIM: a 4G/LTE modem wired to the board's pins (UART, e.g. SIM7600 or A7670 modules), or plugged into its USB port (4G USB sticks, tested with a TCL LinkKey IK41, and USB LTE modems). Ethernet: a W5500 module on the pins (SPI), or a USB Ethernet adapter or phone tethering on the USB port (beta). Hardware · USB devices. |
| Connect devices that cannot run Tailscale | Forward one TCP or UDP service from the local LAN to a Tailnet peer. Restrict the source by IP/CIDR. |
| Reach a remote LAN | Advertise approved subnets to Tailnet clients. Configure the gateway's own Wi-Fi for IoT devices. |
| Monitor and automate | Track events and resource trends locally. Optionally use MQTT and Home Assistant, ntfy, Telegram, email or SNMP. |
- Check your board. Use an ESP32-S3 N8R8 or N16R8 with 8 MB octal PSRAM. See supported hardware, or buy the tested board.
- Install. Open the Web Installer in desktop Chrome or Edge with a USB data cable. You can also use Easy Install or the advanced downloads.
- Set up. Join the board's
RecoveryGateway-Setup-XXXXWi-Fi, go to http://192.168.4.1, pair using the BOOT button or USB setup code, and test your uplink. Open the address shown at the end of the wizard. - Join your Tailnet. Connect to Tailscale or Headscale, then enable the role you need.
First-boot walkthrough · Update an existing gateway
For example, a home automation controller at a second site can send MQTT messages to a broker on your Tailnet. The controller connects to the ESP32's LAN address. The ESP32 forwards the connection to the broker using one rule that specifies the destination, protocol, port and allowed source.
Configure your first service rule · MQTT between two homes
Screenshots show the embedded Firmware 3.0.19 interface with fictional configuration, peers and measurements. Open an image for the full view.
| Status | Service Gateway |
|---|---|
![]() |
![]() |
Browse the gallery for mobile, first boot, recovery, alerts, firewall and diagnostics.
- Saving the Ethernet or mobile data (SIM) uplink shows the Restart button, like the other settings that apply after a restart.
- System → About shows the RecoveryGateway repository as the source.
- USB SIM sticks on the home network's address range (e.g. 192.168.1.x on both sides) no longer cut the gateway off from the home devices.
- Mobile data as the main uplink carries name lookups too, so Tailscale stays connected instead of dropping every few minutes.
- New name: RecoveryGateway (formerly ESP32 Tailnet Gateway): same firmware, same settings, new addresses (this repository and its website). Gateways on 3.0.27 or older still find 3.0.28 with Check for updates.
- One more case that could block the tunnel is fixed: a device whose key expiry carries a time zone offset (possible with some control servers).
- Fix for tailnets with recently added devices: their new 64-bit device IDs made the gateway refuse the device list and block the tunnel.
- Headscale with a private CA or a self-signed certificate.
- First connection without working DNS, ACL "cap:" rules, two relays to other regions at once.
- LAN → Tailnet: up to 5 allowed devices per rule, and a guide to share one service with another network.
- Configuration profiles for every first-boot goal.
Install the current firmware · Full changelog
| Method | Use it for |
|---|---|
| Web Installer | First install from desktop Chrome or Edge over USB |
| Easy Install | Guided USB setup on Windows, macOS or Linux |
| GitHub Releases | OTA image, factory image, checksums, provenance and license notices |
To update an existing gateway, use System → Firmware. Factory installs
can erase settings. See the update and rollback guide
and verify release files against SHA256SUMS.txt.
For the historical 3.0.2 notice bundles, see their separate checksums.
Firmware 3.x runs on ESP32-S3 with 8 MB octal PSRAM and at least 8 MB of quad flash:
| Supported | Not supported |
|---|---|
| N16R8 — e.g. ESP32-S3-DevKitC-1 N16R8, WROOM-1/1U-N16R8 (tested) | 4 MB flash (N4…) |
| N8R8 — e.g. ESP32-S3-DevKitC-1 N8R8, WROOM-1/1U-N8R8, Freenove N8R8, Seeed XIAO ESP32S3 (same layout, not yet tested on 3.x) | R2 or no PSRAM, octal-flash modules (WROOM-2, N16R16V, N32R8V), other ESP32 chips |
The gateway is developed and tested on the ESP32-S3-DevKitC-1 N16R8 (16 MB flash, 8 MB octal PSRAM). If you do not have a board yet, these are the ones I use, on Amazon:
For a wired connection there is also an ESP32-S3 board with built-in Ethernet and a PoE module: Amazon link. Ethernet support (W5500) is experimental and not yet validated on real hardware; check that the board has 8 MB octal PSRAM (R8) and at least 8 MB of flash, and set its W5500 pins under Network → Ethernet.
Affiliate links: buying through them supports the project at no extra cost to you. As an Amazon Associate I earn from qualifying purchases. Any board in the table above works.
Details and community reports: Hardware.
Besides a W5500 module or a modem wired to the pins, the gateway can use one USB device on the board's USB port (not the COM port): a USB LTE modem or 4G stick with a SIM, a USB Ethernet adapter (Realtek RTL8152/8153/8156, CDC-ECM/NCM) or Android USB tethering. Choose USB in first-boot setup or on the Network page, save, restart, then plug the device.
- Tested: a TCL LinkKey IK41 4G USB stick with a SIM, as the main Internet uplink: Tailscale stays connected over mobile data, name lookups use the SIM, and home devices stay reachable even though the stick uses the same 192.168.1.x range as the home router (from 3.0.29).
- Not yet tested with real devices: USB modems in serial (AT/PPP) mode, USB Ethernet adapters and phone tethering. Reports are welcome.
Affiliate link: buying through it supports the project at no extra cost to you. As an Amazon Associate I earn from qualifying purchases.
- The board does not supply 5 V on its USB port. Use a powered USB-C OTG Y-cable with a 5 V charger (at least 2.5 A for a modem or stick), or the device's own 5 V supply with grounds connected. Tested: a single charger on the Y-cable's power input runs both the board and a TCL LinkKey IK41 stick (cable plug in the board's USB port, stick in the cable's socket), with nothing on the COM port. LTE modems draw up to 2 A in bursts: a computer's USB port is not enough (modem resets, reset reason BROWNOUT).
- Never connect two 5 V sources together: if you bridge the board's USB-OTG pad, never plug that port into a computer or charger.
- After the restart the USB port is a USB host: flash and logs go through the COM port; power can come from the Y-cable alone. One device, no hubs, about 10 Mbit/s at most.
- While a USB connection is on, the Wi-Fi keeps 16 receive buffers instead of 24 to leave internal RAM for the device. Bursts of Wi-Fi traffic, such as a speed test from a phone on the gateway's access point, can be slower or lose more packets; ordinary use was unchanged in measurements. With the pins or with these uplinks off, nothing changes.
Full guide: USB devices · docs/USB-DEVICES.md.
| Area | Start here |
|---|---|
| Setup, hardware and configuration | Getting started · Hardware · Configuration |
| Networking | Service Gateway · Network modes · Dynamic DNS |
| Recovery and automation | NAS recovery · Smart Recovery · Automation |
| Operations | Security policy · Diagnostics · Release history |
| Development | Documentation index · Testing · Wiki |
- PBKDF2-HMAC-SHA256 password verifier with a one-time login challenge,
device-wide login budget,
SameSite=Strictsession cookie. - State-changing requests are screened against cross-origin and cross-site
use; untrusted
Hostnames are refused when no password is set (DNS rebinding). - First boot is restricted to the setup AP, requires physical pairing and seals setup requests with X25519/AES-256-GCM. It does not authenticate the downloaded page against an active nearby impersonator; use a trusted setup site.
- Tailnet authorization is checked on original packets before NAT, fails closed on malformed or revoked policy and is not a claim of full official-client policy parity.
- A Service Gateway source filter is not client identity: prefer
/32. - The local Web UI is HTTP; administer it from a trusted LAN/AP or over the tailnet. The portable image does not enable Secure Boot or flash encryption.
Report vulnerabilities privately: see SECURITY.md.
- Estimated peak Tailnet transfer speed: roughly 8 Mbit/s (1 MB/s) over a direct Wi-Fi tunnel in favorable conditions. A W5500 Ethernet uplink may improve that by removing Wi-Fi airtime contention. The firmware's sustained Ethernet ceiling remains unmeasured. Relay paths and concurrent traffic can reduce throughput.
- Service Gateway scope: IPv4 TCP/UDP, up to 8 rules, one Tailnet IPv4 destination per rule; a port forwarder, not transparent routing. UDP cannot be verified without an application reply.
- Exit node: IPv4 only; IPv6 fails closed. A selected exit node fails closed when unreachable.
- Not supported: tailnet lock; Headscale with self-signed certificates.
- Experimental hardware: W5500 requires compatible hardware and pin settings. This embedded community client does not promise full official-client policy parity. See release availability.
Bug reports, hardware reports and guide improvements are welcome. Read CONTRIBUTING.md and the code of conduct; use the issue templates. Follow the checks in Testing for the published source.
Support the Mattboxx edition on GitHub Sponsors or Ko-fi — entirely optional. The firmware and all features remain free:
GPL-3.0-only (LICENSE) with an additional permission for ESP-IDF and Espressif's binary libraries and terms on attribution and on the Mattboxx name (LICENSE-EXCEPTION.md), for all Mattboxx code from 8 November 2026 and every release from 3.0.12. Releases up to 3.0.11 were published under MIT and copies of them keep those terms. The original firmware's MIT notice is kept in licenses/upstream. Built on:
- Csontikka/esp32-tailscale-subnet-router — the original firmware this edition builds on. Support the upstream author via GitHub Sponsors or Buy Me a Coffee.
- Mattboxx/microlink — the pinned networking dependency, derived through Csontikka's fork from Cameron Malone's original MicroLink. The current fork uses GPL-3.0-only with an ESP-IDF linking permission and preserves the original MIT and third-party notices. Previously published firmware retains the terms of the MicroLink revision it shipped.
- wireguard_lwip — Daniel Hope's userspace WireGuard for lwIP (BSD-3-Clause), with separately licensed crypto notices.
- ESP-IDF — Espressif SDK (primarily Apache-2.0; bundled libraries retain their own licenses).
Full attribution: NOTICE.md. Brand assets: assets/brand. Bundled third-party components and the separately distributed esptool flashing program retain their respective licences. RecoveryGateway is independent community firmware. It is not affiliated with Tailscale Inc., the Headscale project or Espressif. Tailscale, Headscale, WireGuard and ESP32 are trademarks of their respective owners. Legacy README: 1.13 documentation.

