Installation

Installation

Three routes, all installing the same release files.

Route	Best for	How
Browser installer	A new Wi-Fi gateway, no tools to install	Install firmware in desktop Chrome/Edge over USB
Easy Install	Guided install on Windows, macOS or Linux	ESP32-Tailnet-Gateway-v<version>-EASY-INSTALL-Windows-macOS-Linux.zip from the latest release
Advanced downloads	Manual flashing, Web UI updates, the experimental W5500 image	Downloads with checksums

Browser installer

Desktop Chrome or Edge only (Web Serial). Safari, Firefox and phone browsers should use Easy Install. Connect the board with a data cable, press Connect & Install, choose the ESP32-S3 port. The installer asks before erasing: erase only for a new setup.

Easy Install

Unzip and read START-HERE.txt. The scripts verify checksums and that an ESP32-S3 answers before writing anything.

System	New device (asks to type ERASE)	Keep settings
Windows	windows\INSTALL-NEW-DEVICE.bat	windows\UPDATE-KEEP-SETTINGS.bat
macOS / Linux	sh macos-linux/install.sh new	sh macos-linux/install.sh update

Windows includes esptool; macOS and Linux need Python 3 and esptool 5 (python3 -m pip install --user "esptool>=5,<6"). On Linux a permission error means adding your user to the dialout (Debian/Ubuntu) or uucp (Arch) group.

Release files

File	Use
ESP32-Tailnet-Gateway-v<version>-WiFi-factory.bin	Full image at offset 0x0 — erases settings
firmware.bin	Application image for System → Firmware (keeps settings)
firmware-eth.bin	Application image of the experimental W5500 build only
SHA256SUMS.txt, release-manifest.json	Checksums and file manifest
FIRMWARE-LICENSES.txt	Third-party notices

Never upload a factory image through the Web UI, and never flash the W5500 image on a Wi-Fi-only board. If the board is not detected: use a data cable, install the CP210x/CH34x driver if your board needs it, then hold BOOT, tap RESET, release BOOT and retry.

Next: First Boot Setup.