Skip to content

About

ESP32-S3 firmware: Wake-on-LAN from Telegram or ntfy (no VPN needed), Tailscale/Headscale gateway, and Ethernet or 4G/LTE uplinks that keep IoT devices online. Selective LAN-to-Tailnet forwarding, subnet routing, Home Assistant and remote recovery.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

132 stars

Watchers

0 watching

Forks

Latest commit

 

History

1,034 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
RecoveryGateway — Mattboxx Edition. One ESP32. Remote access, Wake-on-LAN and backup internet. Enable only what you need.

RecoveryGateway

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

License: GPL-3.0 Platform: ESP32-S3 ESP-IDF 6.1 CodeQL Latest stable release Support on Ko-fi Support on GitHub Sponsors

Install in your browser · Download firmware · Setup guide · Website

What you can do

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.

Quick start

  1. Check your board. Use an ESP32-S3 N8R8 or N16R8 with 8 MB octal PSRAM. See supported hardware, or buy the tested board.
  2. 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.
  3. Set up. Join the board's RecoveryGateway-Setup-XXXX Wi-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.
  4. Join your Tailnet. Connect to Tailscale or Headscale, then enable the role you need.

First-boot walkthrough · Update an existing gateway

LAN → Tailnet Service 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.

A LAN client connects to one Tailnet service through a source-restricted rule on the ESP32.

Configure your first service rule · MQTT between two homes

Web interface

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
Status dashboard showing the uplink, Tailnet and resource overview Network services with a LAN-to-Tailnet rule

Browse the gallery for mobile, first boot, recovery, alerts, firewall and diagnostics.

What's new in Firmware 3.0.30

  • 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.

Also in 3.0.29

  • 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.

Also in 3.0.28

  • 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.

Also in 3.0.27

  • 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).

Also in 3.0.26

  • 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

Downloads

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.

Supported hardware

ESP32-S3 N16R8 or N8R8 board. Tested 4G setup: one charger on an OTG Y-cable powers the board and a TCL LinkKey IK41 SIM stick; computer on the COM port optional; optional microSD, W5500 Ethernet and UART modem.

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

Buy the tested board

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.

USB 4G sticks, modems and Ethernet adapters (from 3.0.25)

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.

Documentation

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

Security

  • PBKDF2-HMAC-SHA256 password verifier with a one-time login challenge, device-wide login budget, SameSite=Strict session cookie.
  • State-changing requests are screened against cross-origin and cross-site use; untrusted Host names 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.

Limits

  • 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.

Contributing

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:

Support Mattboxx on GitHub Sponsors

Support the Mattboxx edition on Ko-fi

Credits and licences

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.

About

ESP32-S3 firmware: Wake-on-LAN from Telegram or ntfy (no VPN needed), Tailscale/Headscale gateway, and Ethernet or 4G/LTE uplinks that keep IoT devices online. Selective LAN-to-Tailnet forwarding, subnet routing, Home Assistant and remote recovery.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

132 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages