Reach Your Smart Home Without Opening an Inbound Router Port
Home Assistant normally serves its web interface only to devices that can reach its local address. A Localtonet HTTP tunnel can publish that interface at a public HTTPS address without inbound port forwarding, a public IPv4 address, or router configuration. This guide explains how to select the correct local target, configure Home Assistant when forwarded client headers are used, handle Docker and Home Assistant OS installations, and reduce the risk of placing a smart-home control panel on the public internet.
Why use an outbound tunnel for remote access?
Home Assistant listens on TCP port 8123 by default. Devices on the same local network can normally open an address such as http://192.168.1.50:8123, but that private address is not routable from the public internet. Traditional remote access often uses router port forwarding, dynamic DNS, and a separately configured TLS certificate.
Port forwarding also depends on the internet connection having usable inbound connectivity. If an ISP places a subscriber behind carrier-grade NAT, ordinary inbound IPv4 port forwarding on the home router will not provide a public path to the service. A changing public address can also require dynamic DNS.
The Localtonet client uses a different model. It establishes an outbound connection to a Localtonet relay and forwards an assigned public endpoint to a selected local IP address and port. For Home Assistant, the normal choice is an HTTP tunnel targeting port 8123. The public side is an HTTPS URL, while the local target can remain Home Assistant's ordinary HTTP listener.
Removing port forwarding does not remove the need for application security. Use a strong, unique Home Assistant password, enable multi-factor authentication for administrative accounts, keep Home Assistant and the Localtonet client updated, and expose only the service that is required.
Understand Home Assistant trusted proxies
Home Assistant has explicit controls for reverse proxies. When a proxy supplies an X-Forwarded-For header and Home Assistant is configured to use that header, the immediate proxy must be listed under trusted_proxies. Home Assistant rejects forwarded headers from an untrusted source because accepting them from arbitrary clients would allow spoofing of the apparent client address.
The correct entry is the address Home Assistant sees as the immediate proxy. It is not automatically 127.0.0.1 in every deployment:
| Localtonet location | Likely target | Proxy address to evaluate |
|---|---|---|
| Same operating system as Home Assistant Core | 127.0.0.1:8123 |
Loopback may be correct if Home Assistant logs the connection from 127.0.0.1 |
| Another computer on the home LAN | Home Assistant's LAN address and port 8123 |
The LAN address of the computer running Localtonet |
| Separate Docker container | Home Assistant container name, host address, or another reachable address | The Localtonet container address or a narrowly controlled Docker network |
If Home Assistant reports that a request came from an untrusted reverse proxy, use the source address shown in the Home Assistant log to identify the immediate proxy. Add only that address or a narrowly scoped, controlled network. Do not trust 0.0.0.0/0, ::/0, or an entire home network merely to suppress an error.
For a same-host deployment where the logged proxy address is IPv4 loopback, the configuration can be:
http:
use_x_forwarded_for: true
trusted_proxies:
- 127.0.0.1If the log identifies IPv6 loopback instead, use ::1. If Localtonet runs on a separate LAN computer, replace the loopback entry with that computer's stable LAN address. Avoid listing addresses that are not actually acting as the proxy.
If configuration.yaml already contains an http: section, merge these settings into it. Validate the configuration and restart Home Assistant using the controls available for your installation. File editing and restart menus differ among Home Assistant OS, Container, Core, and current frontend versions.
Optional failed-login banning
Home Assistant's HTTP integration also supports ip_ban_enabled and login_attempts_threshold. The threshold is an administrative choice, not a Localtonet requirement. For example:
http:
use_x_forwarded_for: true
trusted_proxies:
- 127.0.0.1
ip_ban_enabled: true
login_attempts_threshold: 5Review the resulting ip_bans.yaml file if a legitimate client becomes blocked. Correct proxy configuration is important because Home Assistant needs an accurate client address to apply IP-based controls as intended.
How to configure a Localtonet HTTP tunnel
Install the Localtonet client on the Home Assistant host when that operating system supports it, or on another always-on device that can reach Home Assistant over the LAN. The second pattern is particularly useful for Home Assistant OS, where the appliance should normally be managed through supported add-ons rather than by manually launching unmanaged host containers.
Confirm the local Home Assistant address
From the device that will run Localtonet, open Home Assistant using its local address. Use 127.0.0.1:8123 only when Localtonet and Home Assistant share the same network namespace. Otherwise use a reachable LAN address such as 192.168.1.50:8123.
Install and connect the Localtonet client
Download the supported client from the Localtonet download page. Connect it using the device-specific token shown in your account. Treat that token as a credential and do not place it in screenshots, articles, shared shell history, or public configuration files.
Create the HTTP tunnel
In the HTTP tunnel page, select a Process Type, the connected AuthToken, and a currently available relay server. Enter the Home Assistant local IP address and port 8123. Random Sub Domain, Custom Sub Domain, and Custom Domain process types all publish the selected content at a public HTTPS address, subject to current account and product availability.
Start the tunnel
Creating the tunnel does not start it. Press Start and confirm that the selected Localtonet client remains connected. Copy the assigned public HTTPS URL without disclosing private account information.
Test from an external network
Use mobile data or another network to open the public URL. Sign in with Home Assistant credentials. If Home Assistant reports an untrusted proxy, use the logged source address to correct trusted_proxies, validate the YAML, and restart Home Assistant.
Platform-specific guidance
Windows
Localtonet is available through the Microsoft Store and as downloadable binaries for supported Windows architectures. The current download page documents running the client with a device token and installing it as a Windows Service for automatic startup. Run service-management commands from an elevated Command Prompt or PowerShell window. Use the service status controls or services.msc to verify that it is running.
If Home Assistant is in a virtual machine or on another appliance, do not target Windows loopback. Enter the Home Assistant VM or appliance LAN address instead, and allow the connection through only the relevant local firewall profile.
Linux
The current Localtonet download page provides this quick installer for supported Linux builds:
curl -fsSL https://localtonet.com/install.sh | shReview scripts before executing them with elevated privileges. The installer places the client in /usr/local/bin and may request administrative access. The documented Linux service mode requires systemd:
sudo localtonet --install-service --authtoken <YOUR_TOKEN>
sudo localtonet --start-service --authtoken <YOUR_TOKEN>
systemctl status localtonetUse a real token only in your private terminal. Consider the shell-history implications of supplying credentials on a command line. The service keeps the Localtonet client available after logout and starts it after reboot, but the public endpoint still depends on the device, its network connection, the client service, and the tunnel being operational.
macOS
The official Localtonet Homebrew tap supports the documented installation workflow:
brew tap localtonet/tap
brew install localtonet
localtonet --versionLocaltonet also documents a launchd service mode for automatic startup. Intel and Apple Silicon downloads are listed on the current download page. Do not assume that every historical Mac model or macOS release remains supported; select the build presented for the current platform.
Docker
The official image can be pulled with:
docker pull localtonet/localtonetDocker networking must be planned before creating the tunnel. Inside a container, 127.0.0.1 refers to that container, not automatically to the Home Assistant container or Docker host. If both containers use a user-defined network, target a resolvable Home Assistant container name and port. If Home Assistant publishes port 8123 on the host, target an address through which the Localtonet container can reach that host. Docker host networking has platform limitations and should not be presented as a universal solution.
Home Assistant must trust the actual immediate proxy address when forwarded headers are enabled. Container addresses can change after recreation, so use a deliberately managed Docker network or another stable design rather than repeatedly adding broad, unrelated subnets.
Home Assistant OS
Home Assistant OS is an appliance-style installation. Do not rely on entering an add-on terminal and manually launching an arbitrary Docker container as a durable installation method. Add-on access does not make unmanaged host-container changes a supported Home Assistant OS workflow, and add-on protection or permissions may prevent the commands from working.
A straightforward supported pattern is to run Localtonet on another always-on Windows, Linux, macOS, or Docker device on the same trusted LAN. Confirm that this device can open the Home Assistant LAN URL, then configure the Localtonet HTTP tunnel with the Home Assistant appliance's LAN address and port 8123. In Home Assistant, list the Localtonet device's stable LAN address as the trusted proxy if forwarded headers are being used.
When Localtonet runs on a second device, remote access depends on both devices. Reserve a stable LAN address for Home Assistant and for the Localtonet device, restrict local firewall access where practical, and keep both systems patched.
Configure the Home Assistant Companion App
The Home Assistant Companion App can use an external URL when the phone is away from the home network. The exact menu labels vary by app version and mobile platform. Open the app's server or connection settings and set the external Home Assistant URL to the Localtonet public HTTPS URL. Keep the internal URL set to a reachable local Home Assistant address if local switching is desired.
Test the configuration by disabling Wi-Fi and opening the app over mobile data. A successful browser test does not guarantee that every Home Assistant integration will accept a new external hostname. Review integrations that generate callback URLs, notification links, OAuth redirects, or webhook URLs, and configure Home Assistant's external URL setting where the integration documentation requires it.
Security checklist for an internet-facing Home Assistant instance
Troubleshooting common failures
| Symptom | Likely cause | Safe corrective action |
|---|---|---|
| Home Assistant reports an untrusted reverse proxy | The immediate proxy is missing from trusted_proxies |
Read the source address from the Home Assistant log, add only that proxy address, validate the YAML, and restart Home Assistant |
| The public URL returns a gateway or connection error | The Localtonet client cannot reach the configured local target | Open the same target from the Localtonet device and correct the IP address, port, firewall, or Docker network |
| The tunnel exists but is unavailable | The tunnel was created but not started, or its selected client is disconnected | Connect the selected client and press Start for the tunnel |
A Docker tunnel cannot reach 127.0.0.1:8123 |
Home Assistant is in a different network namespace | Use a reachable container name, host address, or intentionally configured Docker network |
| The Companion App works at home but not remotely | The external URL is absent, incorrect, or the tunnel is stopped | Verify the public URL in a mobile browser, then update the app's external server URL |
| Remote access stops after a reboot | The Localtonet client did not start automatically | Use the documented service mode for the operating system and verify its status after reboot |
Frequently asked questions
What port does Home Assistant use?
Home Assistant uses TCP port 8123 by default. Use the configured port if your installation has changed server_port or publishes the container on a different host port.
Does Localtonet require router port forwarding?
No inbound router port forwarding is required. The Localtonet client establishes an outbound connection to a relay and forwards the assigned public endpoint to the selected local service.
Must trusted_proxies always contain 127.0.0.1?
No. Use 127.0.0.1 only when Home Assistant actually sees the immediate proxy on IPv4 loopback. A Localtonet client on another LAN device or in another container has a different source address. Use Home Assistant's log to identify it.
Can this work behind carrier-grade NAT?
Yes, provided the network allows the Localtonet client to establish its outbound relay connection. The method does not depend on ordinary inbound IPv4 port forwarding or a dedicated public IPv4 address.
Can Localtonet run directly on Home Assistant OS?
Do not assume that an arbitrary Docker command entered through a terminal add-on is a supported or persistent Home Assistant OS installation. A practical approach is to run Localtonet on another supported, always-on device on the same LAN and target the Home Assistant OS device's local address.
Does creating a tunnel make it active?
No. After creating the tunnel, press Start. It remains available only while the selected client is connected and the tunnel is running.
Can I use a custom domain?
HTTP tunnels support Random Sub Domain, Custom Sub Domain, and Custom Domain process types. Check the current dashboard and documentation for availability and current DNS requirements rather than relying on nameserver values copied from an older tutorial.
Set up controlled Home Assistant access
Install the Localtonet client on a device that can reach Home Assistant, create an HTTP tunnel to the correct local address, review trusted proxy settings, and test the endpoint from an external network.
Get Started Free →
