Skip to content

Network Security

Jump to bottom
David2766 edited this page Aug 21, 2026 · 1 revision

Network and Security

NAMO is intended for use on a trusted local network. This guide explains safe network design, device addressing, remote access, and the information that must remain private.

한국어로 보기

Caution

Never expose a NAMO device directly to the public internet. Do not publish its dashboard or API through port forwarding, DMZ, a public IP address, a public reverse proxy, or an internet tunnel. Adding an HTTPS certificate alone does not make NAMO a safe internet-facing service. Read Local network principles and Safe remote access before deployment.

Local Network Principles

  • Connect NAMO and its setup phone, computer, or Home Assistant host to the same trusted LAN.
  • Use password-protected 2.4GHz Wi-Fi. NAMO does not accept an open Wi-Fi network.
  • Guest Wi-Fi and client isolation can block device communication, discovery, and pairing.
  • If VLANs are used, explicitly design and verify the required local traffic and mDNS path.
  • Do not leave router administration or Wi-Fi credentials at their defaults.

Local-only operation does not mean the device is safe to publish on the internet. Sensing and coordination run locally, and the local network is the trust boundary.

Device Addresses and mDNS

The most reliable address is the IP shown by the setup page or router.

http://<device-ip>/dashboard

On the same network, a .local address may also work:

http://<device-name>.local/dashboard

.local depends on mDNS and multicast traffic. It generally works most consistently on macOS and iOS, but may fail on Windows, some Android devices, browsers, VPNs, or VLANs. Use the IP address when this happens; it does not by itself indicate a device fault.

Create a DHCP reservation on the router if the address changes frequently. Do not register a NAMO address in public DNS.

Router and Firewall

Do not use any of the following:

  • Port forwarding to a NAMO IP address
  • DMZ or exposed-host configuration for NAMO
  • A public IP address assigned directly to NAMO
  • A public reverse proxy, regardless of its authentication setting
  • A public tunnel that turns the local NAMO HTTP address into an external URL

When using a local firewall or VLAN, allow only the traffic required between NAMO devices, setup browsers, and Home Assistant. After changing isolation rules, verify the dashboard, pairing, coordinate fusion, and Home Assistant state separately.

Safe Remote Access

For remote access, keep all NAMO addresses private and configure a VPN on the router or another trusted gateway.

  1. Connect through the VPN to the trusted LAN at the installation site.
  2. Open the NAMO local IP address after the VPN is connected.
  3. Restrict VPN users and devices to the people who need access.
  4. Remove unused VPN accounts and access grants.

The VPN must not add a public service to the NAMO device itself. It should securely place the remote browser on the local network, where the existing local address is used.

Information to Protect

Do not include the following in screenshots, issue reports, public repositories, or shared documents:

  • Wi-Fi names and passwords
  • ESPHome Native API encryption keys
  • Device-pairing credentials and confirmation information
  • Firmware-signing private keys and private key paths
  • Floorplans, zones, statistics, and living-space information in backups
  • Internal IP addresses and complete network layouts that do not need to be public

Use a different ESPHome API key for every NAMO device. Do not redistribute a local build environment or firmware image that contains personal keys.

Safe Device Pairing

  • Enable Allow connection for 3 minutes only when intentionally starting a connection.
  • Approve only when the six-digit code is exactly the same on both devices.
  • Reject unknown devices and unexpected requests.
  • Let the invitation expire after setup instead of repeatedly leaving it open.
  • Reset old connection records and restore trusted firmware before using a second-hand device or one from an unknown source.

Firmware and Backups

  • Use signed .namo-ota or factory images from the official Release source.
  • Install alpha firmware only after explicitly allowing one installation for ten minutes on that device.
  • Do not install firmware or distribution files from an unverified source.
  • A backup may omit Wi-Fi and complete pairing keys while still containing sensitive floorplan and usage information; store it securely.
  • Remove passwords, API keys, and credentials from logs and backups before reporting a problem.

If Exposure or Credential Loss Is Suspected

  1. Remove router port forwarding, DMZ, proxies, and tunnels immediately.
  2. Isolate NAMO from the trusted LAN and block the suspected access path.
  3. Replace exposed Wi-Fi passwords, API keys, and related account credentials.
  4. If firmware integrity is uncertain, recover over USB with an official factory image.
  5. Reconfigure and pair only the required devices.
  6. Review the router and other devices on the same network.

A leaked firmware-signing private key cannot be fixed by restarting NAMO. Stop using the key and follow the project's key replacement and recovery procedure.

Security Checklist

  • NAMO is connected only to trusted local Wi-Fi.
  • No port forwarding, DMZ, or public tunnel exists.
  • Remote access is available only through a VPN.
  • Every device uses a different ESPHome API key.
  • Pairing codes are verified in person.
  • Firmware comes from a trusted official release.
  • Backups and logs are handled as sensitive data.

Related Guides

NAMO Wiki

English

한국어

Clone this wiki locally