Getting started

Install Firmware v3.0.2, complete the guided setup, then enable only the roles you need. Use a computer for USB installation; a phone or computer can handle the setup afterwards.

Before you start

An ESP32-S3 N8R8 or N16R8: 8 MB octal PSRAM and at least 8 MB flash. Check supported hardware.
A USB data cable and a computer. The browser installer needs desktop Chrome or Edge; Easy Install supports Windows, macOS and Linux.
A 2.4 GHz Wi-Fi network for the usual Wi-Fi setup. Ethernet and cellular need external hardware and remain experimental.
Tailscale or Headscale for Tailnet roles. Local administration and local Wake-on-LAN do not require either.

1. Install, or update an existing gateway

New board

Use Connect & Install in your browser or the Easy Install package. Choose the new-device installation and confirm the erase only when you intend to initialize the board. Restart after installation, then continue below.

Already configured?

Back up first and follow Updating. For an existing 3.x gateway, prefer System → Firmware to keep its settings and previous OTA image. Versions 2.x and 1.x have their own migration steps.

A factory/new-device erase deletes settings and the Tailnet identity. It is not needed for an ordinary update or a Wi-Fi connection problem. Follow the current installer instructions rather than commands for the older partition layout.

2. Complete the guided first-boot setup

On a genuinely unconfigured board, join ESP32-Tailnet-Setup-XXXX. Its suffix identifies the board. Stay connected if your phone reports that this open setup network has no Internet.
Open the setup notification. If it does not appear, browse to http://192.168.4.1/.
When prompted, press BOOT once to pair. Alternatively, read the current eight-digit code from the USB serial console at 115200 baud and enter it in the setup page.
Create your administrator password: at least eight characters. There is no default admin password.
Select the available uplink. For Wi-Fi, choose your 2.4 GHz network, enter its password and press Test connection. The setup Wi-Fi may briefly disconnect during the test.
Configure Tailscale or Headscale, or skip it and join later where the chosen uplink permits. Choose your roles and a separate password for the gateway's protected Wi-Fi/recovery network.
Review the summary, save and restart. Rejoin your home Wi-Fi and use the address shown by setup. The displayed .local name is another option when your LAN and client support mDNS.

Choose your language in the setup page. The First boot guide explains pairing, uplinks and finding the gateway after restart. An update preserving an existing configuration does not reopen this initial setup network.

3. Join your Tailnet

If you skipped registration, open the Tailscale page. Set the gateway's name and registration credentials; Headscale also needs your control-server URL. Keep auth keys private and scoped to the intended role.

Review node expiry and approve only the routes or exit-node role you intend to use in your Tailnet administration. See Headscale, Subnet routing and Exit-node roles.

4. Start with one useful role

Reach a remote service from an ordinary LAN device: reserve the gateway's LAN address, then add a Network → LAN → Tailnet rule. Restrict its source to the intended client, check the destination and test from that client. Service Gateway guide.
Connect an IoT device: configure the protected gateway Wi-Fi and the routing it needs. IoT gateway guide.
Wake or recover a NAS/PC: save a compatible device and configure Wake-on-LAN or Smart Recovery. A sent packet is not proof that the device booted. Remote recovery guide.
Automate later: MQTT, Home Assistant, ntfy and other integrations are optional. They are not prerequisites for local administration, routing or local recovery. Automation guide.

5. Check the path you actually need

Confirm the uplink and Tailnet state in Status.
From another authorized Tailnet device, open the gateway through its Tailnet address or name.
For a service rule, connect to its listen port from the intended LAN client and check its counters. A visible peer or connected control plane alone does not prove service authorization or reachability.

If something does not work

Keep a configuration backup. If home Wi-Fi becomes unavailable, use the protected recovery network configured during setup; it is distinct from the open first-boot network. Administer the HTTP Web UI from a trusted LAN or over the Tailnet. Follow Device recovery or Troubleshooting before considering a factory reset.

Repository reference: Getting started.