ESP32 NAT Router: a $3 router with an 8-client ceiling

What this firmware is, and the network roles it covers

This is ESP-IDF firmware in C that uses the ESP32 as a WiFi NAT router. The AP interface is one side of the route, and the STA interface or an Ethernet port is the uplink. It can also put WireGuard on the uplink, which turns the device into a VPN router in the ordinary sense of the phrase rather than as a marketing label.

The use cases list in the README is the most honest part of the documentation, because it describes situations rather than features. A simple range extender for an existing network. A second network with a different SSID and password and restricted access for guests or IoT devices. A VPN router. A converter from a corporate WPA2-Enterprise network to a regular WPA2-PSK one for devices that cannot do enterprise auth. A classic WiFi router with an Ethernet uplink. An MCP server for controlling the network through an AI assistant. Presence detection and network monitoring inside a Home Assistant setup. And debugging or monitoring WiFi devices.

That last group is where the design shows. The stated throughput is 15 Mbps or more for NAT routing, which is low next to a real router, but it is in the range where packet capture, WireGuard throughput and TLS handshakes all become visibly slow. The feature set reads like a commercial router's manual, and the throughput number reads like a microcontroller's. Both are accurate.

The repository also documents a family of spin-off projects built from the same base, each narrowing the scope: a layer 2 WiFi repeater with no NAT and no DHCP on a dedicated branch, a separate Ethernet-to-WiFi bridge for the W32-ET01 board, a reversed-direction Ethernet router, and a PPPoE variant for open-source ISP use. The ESP8266 predecessor is described as the grandfather of the line. If your need is a layer 2 bridge rather than a router, the sibling project is the right target and this one would be the wrong tool.

The RAM budget is the real specification

The README states the maximum number of simultaneous WiFi clients is 8, and 5 on the ESP32-C3, due to RAM limitations, at about 5KB per client. Then it lists what each major feature costs: the web interface, PCAP capture, WireGuard, remote console, WPA2-Enterprise and MQTT Home Assistant each require several additional kilobytes. The conclusion the documentation draws is that using all of them at once will probably exhaust the ESP32's resources, and that unused or disabled features are optimized for minimal to no RAM usage.

Read that as a configuration exercise rather than a limitation to work around. A realistic setup is the web interface plus WireGuard, or MQTT plus DHCP reservations, not six features enabled because they exist. The advice to check remaining heap when in doubt is the operative instruction, and it means the free heap figure on the status display is a more useful diagnostic than any single feature flag.

The eight-client limit also reframes the guest-network use case. An isolated SSID with a restricted ACL is a genuinely good fit for a handful of IoT devices, and it is exactly the case where the firewall ACL feature earns its place. It is a poor fit for a guest network at a party, and no amount of configuration changes that.

Two display options help here. A plain GPIO LED or an addressable strip on WS2812 or SK6812 gives color-coded status, and there is explicit support for the 72x40 I2C SSD1306 OLED found on some ESP32-C3 mini boards. On a device with this little memory, an optional display module is a reasonable thing to leave unplugged.

Network features: ACL firewall, capture, VPN and enterprise WiFi

The feature set covers the parts of a home router that are usually missing from firmware projects. Port forwarding maps external ports to internal devices. DHCP reservations assign fixed IPs to specific MAC addresses, which matters more here than on a full-size router because address-based rules break when the DHCP lease shifts. A firewall provides ACL rules to restrict or monitor traffic.

Packet capture is implemented as live PCAP streaming to Wireshark or other network tools, which turns the device into a diagnostic instrument rather than only a router. Combined with mDNS, so the router answers to `esp32-nat-router.local`, and with a network-accessible CLI over TCP with per-interface binding and password protection, this is a fairly complete troubleshooting setup for the kind of intermittent WiFi problem that is hard to see from a laptop.

The WireGuard side has the detail that suggests real use rather than a checkbox: automatic MSS clamping and Path MTU handling. Those two settings are exactly what breaks hand-rolled WireGuard on small MTU links, and having them handled by default means a tunnel over a cellular uplink or a nested network is less likely to hang on large packets.

WPA2-Enterprise support lists PEAP, TTLS and TLS as the accepted methods, and the framing is that this converts a corporate network to WPA2-PSK for simple devices. That is the clearest single use case in the whole list: one ESP32 joining an enterprise network and rebroadcasting it as something a printer or a sensor can join.

Hardware coverage is broad. Pre-built binaries exist for ESP32, ESP32-C3, ESP32-C5, ESP32-C6, ESP32-S3 and the WT32-ETH01, and the tree carries a per-target `sdkconfig.defaults` for each variant including PoE isolated and Ethernet common configs. The C5 support includes dual-band 5 GHz with a configurable band preference of auto, 2.4 GHz or 5 GHz, and the Ethernet path uses a LAN8720 PHY on the W32-ET01.

Installing: a browser flasher, esptool, or the network itself

Three installation paths exist, and they are genuinely different in what they require.

The web installer is the easiest. It runs in the browser, needs no tools or command line, and requires a browser with the Web Serial API. You pick a firmware variant, WiFi or Ethernet, and click Connect & Install. Worth noticing what that means technically: Web Serial talks to the chip over USB, so this is a USB flash dressed as a web page, not an over-the-air update. The project hosts it at a GitHub Pages URL, which also means the flashing step depends on a third-party web host staying up and on your browser exposing a serial API. Both are fine in practice, neither is fine as a supply-chain assumption.

The command line path uses esptool against the pre-built binaries in the `firmware_*` directories:

esptool.py --chip esp32 \
--before default_reset --after hard_reset write_flash \
-z --flash_mode dio --flash_freq 40m --flash_size detect \
0x1000 firmware_esp32/bootloader.bin \
0x8000 firmware_esp32/partition-table.bin \
0xf000 firmware_esp32/ota_data_initial.bin \
0x20000 firmware_esp32/esp32_nat_router.bin

The manifest files at the repository root, one per variant, exist for this purpose: `manifest_esp32_wifi.json`, `manifest_esp32_poe_iso.json` and `manifest_wt32_eth01.json`.

The third path is the router itself. OTA updates can be flashed directly from the web UI once the device is running, which covers routine firmware changes. And for building from source there is `platformio.ini`, a `CMakeLists.txt`, a `build_all_targets.sh` script, and a `components/` directory holding the ESP-IDF components.

First boot is deliberately unsecured, then locked down. The device offers an open AP with SSID `ESP32_NAT_Router`. You join it, open `http://esp32-nat-router.local` or `http://192.168.4.1`, set your upstream WiFi and AP settings on the Getting Started page, and Save & Reboot. The open network is a temporary bootstrap state, so treat the window between first power and Save & Reboot accordingly.

Home Assistant integration, MCP bridge, and a branch described two ways

Home Assistant support runs over MQTT with auto-discovery, publishing telemetry and per-client statistics. Combined with DHCP reservations and per-client stats, that makes presence detection possible without touching the router firmware itself, which is the sensible architecture. The web UI pages are documented in the wiki along with security and backup/restore, so configuration export is available.

The MCP bridge is the newest and least settled item. It is described as letting AI assistants such as Claude control the router through the Model Context Protocol, and the README marks it BETA inside the key features list. That marker is doing real work: an MCP server exposes router configuration and state to an assistant, which means an agent can act on your network rather than just query it. The open issue count is 153 on a project with 2,162 stars and 489 forks, so treat beta as literal.

One description in the README contradicts itself in a way worth noting. The layer 2 WiFi repeater is introduced as still under development, and in the same sentence described as working generally with good performance and turning the ESP into a WiFi extender for more than two dollars. Those are not the same claim. A feature under development can work well on a bench and still fail on hardware or firmware combinations nobody has tried, so the branch is a reasonable thing to experiment with and a poor thing to depend on. The spin-off projects, by contrast, are described as separate repositories with their own scope, which is a clearer signal.

One more gap worth naming: the repository metadata reports no license, and there is no license file in the tree listing. For a firmware project that people flash onto hardware they own, that is an unusual omission, and it matters if you intend to modify or redistribute it.

Editorial conclusion

What makes this firmware interesting is not that an ESP32 can route packets. It is the range of network roles squeezed into one binary that also has to run a web server, a WireGuard endpoint, a packet capture pipeline and an MQTT client on the same heap. Range extender, guest network, WPA2-Enterprise to WPA2-PSK converter, VPN router, and Home Assistant presence detection are genuinely different products that usually need different firmware, and the routing core here supports all of them. The limits are equally clear and equally concrete. Eight simultaneous clients, five on the C3, at roughly 5KB of RAM each, means this is not a household router substitute and never will be at this hardware tier. Enabling the web interface, PCAP capture, WireGuard, remote console, enterprise WiFi and MQTT together is documented as likely to exhaust the heap, so the realistic configuration is two or three of those, chosen deliberately. Check your remaining heap before assuming a missing feature is broken. The README is unapologetic about all of this, which is more useful than a feature list that omits the budget.

Frequently asked questions

Official sources

1. Issues
2. martin-ger/esp32_nat_router on GitHub
3. README