Remote Access for Home Assistant

How outbound remote access works

Home Assistant listens on TCP port 8123 by default. A device on the same network can usually reach it through an address such as http://192.168.1.50:8123. That address belongs to a private network and is not directly routable from the public internet.

A traditional remote-access design may combine router port forwarding, dynamic DNS, and a TLS certificate. It also depends on the internet connection accepting inbound traffic. If the connection is behind carrier-grade NAT, an ordinary port-forwarding rule on the home router cannot create a path through the provider's additional NAT layer. A changing public address can introduce another dependency on dynamic DNS.

Localtonet uses an outbound connection instead. The Localtonet client runs on a device that can reach Home Assistant and connects outward to a Localtonet relay. An HTTP tunnel then maps a public HTTPS address to the selected Home Assistant IP address and port. This does not require an inbound router rule or a dedicated public IP address.

Prerequisites and local preflight checks

Complete the local checks before changing Home Assistant or creating a tunnel. Separating local validation from tunnel configuration makes failures much easier to diagnose.

Confirm that Home Assistant works locally

From the device that will run Localtonet, open the exact local Home Assistant target in a browser. Common examples are http://127.0.0.1:8123 for a truly same-host process or http://192.168.1.50:8123 for a separate Home Assistant appliance. Use the actual configured port if Home Assistant does not listen on the default.

The login page should load, sign-in should succeed, and the frontend should remain connected. Navigate between views and confirm that entity states continue updating. A static login page alone proves only that an HTTP response was returned. It does not prove that the persistent connection used by the Home Assistant frontend remains healthy.

Identify the installation types

Record both the Home Assistant installation type and the Localtonet installation type. The important distinction is where the Localtonet process runs relative to Home Assistant:

• On the same operating system and in the same network namespace.
• On another computer or appliance on the same LAN.
• In a Docker container beside or separate from Home Assistant.
• Through the current Localtonet NAS / Home Assistant installation category.

The current Localtonet download page includes a dedicated NAS / Home Assistant category in addition to Windows, macOS, Linux, Docker, OpenWrt, and other platforms. Check that category first for Home Assistant or NAS deployments. It is no longer appropriate to assume that Home Assistant OS always requires a second LAN device.

The exact package or integration offered within that category can change with the supported platform and release. Use the installation path currently presented there for your Home Assistant environment. Do not open an add-on terminal and launch an arbitrary unmanaged host container as a substitute for a listed Home Assistant installation method. If no compatible option is presented for your particular installation, run Localtonet on another supported, always-on device that can reach Home Assistant over the LAN.

Prepare account and network details

• A Localtonet account and a device-specific AuthToken for the client that will run the tunnel.
• The Home Assistant IP address or hostname as seen from that client.
• The Home Assistant port, normally 8123.
• Permission to edit and validate Home Assistant configuration if reverse-proxy settings become necessary.
• An external test connection, such as mobile data, that is not using the home Wi-Fi network.
• A recovery path to the Home Assistant host, console, file share, or local management interface before editing YAML.

Choose the correct deployment topology

The public traffic path has four conceptual parts: the browser or Companion App connects to the public HTTPS endpoint, a Localtonet relay receives that connection, the Localtonet client carries it through an outbound connection, and the client connects to the configured Home Assistant target.

The target must be interpreted from the Localtonet client's network environment. The address 127.0.0.1 always means the current machine or container namespace. It does not automatically mean the Home Assistant machine.

There is no verified basis in the supplied Localtonet documentation for promising that every Localtonet HTTP tunnel adds a particular set of forwarding headers, or for assigning one fixed immediate source address to every deployment. Network namespaces, container bridges, address translation, and installation packaging can all affect what Home Assistant observes.

For that reason, treat Home Assistant's reverse-proxy configuration as conditional. Do not add use_x_forwarded_for and a guessed trusted_proxies value merely because a tunnel exists. First create the local path, test the public endpoint, and use Home Assistant's logs to determine whether forwarded headers are present and which immediate source address Home Assistant is evaluating.

Prepare Home Assistant safely

Home Assistant documents reverse-proxy controls in its HTTP integration documentation. When a reverse proxy sends X-Forwarded-For and Home Assistant is configured to use it, the immediate proxy must be included in trusted_proxies. Home Assistant rejects forwarded information from an untrusted source to prevent arbitrary clients from spoofing their apparent address.

Start without guessing the proxy address

Do not add a proxy entry before you know what Home Assistant sees. After the Localtonet HTTP tunnel is running, attempt to open the public URL. If Home Assistant records an untrusted reverse-proxy message, read the source address in that log entry. That source is the candidate immediate proxy address for the current topology.

If no reverse-proxy error appears and the frontend works normally, do not assume that adding use_x_forwarded_for improves the setup. Whether forwarded client information is present and should be trusted must be established from actual behavior and logs.

Back up the configuration before editing

Before changing configuration.yaml:

1. Create a Home Assistant backup using the supported backup controls for the installation.
2. Make a separate copy of configuration.yaml or record the exact original http: section.
3. Confirm that you can restore the file through a local console, supported file editor, network share, container volume, or host filesystem.
4. Keep local access available while testing. Do not make remote access the only management path.

Add a narrowly scoped trusted proxy only when required

If the log identifies IPv4 loopback as the immediate proxy, the relevant configuration can look like this:

http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 127.0.0.1

This is an example, not a universal Localtonet value. If the log reports ::1, a stable LAN address, or a controlled container address, use the address actually reported for your installation. Do not list both loopback families or unrelated networks without evidence that they are used.

If configuration.yaml already contains an http: section, merge the new keys into it. YAML does not permit two independent top-level http: mappings to define one combined configuration.

Validate before restarting

Use Home Assistant's current configuration validation control before restarting. Menu labels can vary by release and installation type. Home Assistant OS and supervised environments can also validate from a local terminal with the supported Home Assistant command-line controls. Container and Core installations should run the configuration check using the Home Assistant version and configuration directory used by that installation.

A safe validation and restart sequence is:

1. Save the edited YAML without closing the recovery session.
2. Run Home Assistant's configuration check.
3. If validation fails, do not restart. Correct the reported YAML line or restore the backup copy.
4. If validation succeeds, perform a controlled Home Assistant restart.
5. Wait for local access to return and sign in locally before testing the public URL.
6. Review the Home Assistant log for proxy warnings, configuration errors, and repeated authentication failures.

Rollback after an invalid or incorrect change

If Home Assistant will not start after the edit, use the local recovery path prepared earlier. Restore the original configuration.yaml, or remove the newly added proxy keys from the existing http: section. Validate again and restart Home Assistant. If the service starts but public requests fail, stop the Localtonet tunnel while correcting the configuration so the endpoint is not left in an uncertain state.

If the proxy address was correct initially but changes after a container recreation, inspect the new log entry rather than broadening the trusted range immediately. A user-defined Docker network with controlled addressing or another stable topology is safer than continually trusting unrelated dynamic subnets.

Optional failed-login banning

Home Assistant supports ip_ban_enabled and login_attempts_threshold in the HTTP integration. The threshold is an administrative choice, not a Localtonet requirement. When the correct immediate proxy is confirmed, an example is:

http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 127.0.0.1
  ip_ban_enabled: true
  login_attempts_threshold: 5

If a legitimate client is banned, stop repeated login attempts first. Access Home Assistant locally, inspect ip_bans.yaml, remove the relevant entry according to the Home Assistant recovery procedure, and restart or reload as required by the current Home Assistant version. Also correct stale credentials in browsers and mobile apps so the ban is not immediately recreated.

Install the Localtonet client

Use the current Localtonet download page to select the operating system, architecture, or dedicated NAS / Home Assistant option. Install the client on the device that can reach the Home Assistant target selected during preflight.

NAS and Home Assistant installations

Begin with the dedicated NAS / Home Assistant category on the download page. Use the package or supported integration displayed for your current platform. This is the preferred discovery path for appliance-style environments because it avoids treating a temporary shell command or unmanaged host container as a durable installation.

After installation, connect the client with its device-specific AuthToken and verify that the corresponding device appears connected. If the current category does not present a compatible package for your specific Home Assistant installation or architecture, use another supported always-on Windows, Linux, macOS, Docker, or NAS device on the same LAN.

Linux quick installer

For a supported general-purpose Linux host, the download page provides a quick installer that detects the operating system and CPU architecture and installs the client at /usr/local/bin/localtonet:

curl -fsSL https://localtonet.com/install.sh | sh

Review downloaded scripts before executing them in a privileged environment. Installation into /usr/local/bin and service management may request administrative access.

The documented Linux service mode requires systemd. It starts the client after reboot and keeps it running after logout. Direct command-line token arguments can be retained in shell history, process records, or administration logs, so consider the package-based protected token file described below when it is compatible with the host.

Linux DEB and RPM service packages

The current download page also provides DEB and RPM packages for x64 and ARM64. These packages require systemd 247 or newer and OpenSSL 3. Examples of compatible platform generations listed by Localtonet include Debian 12, Ubuntu 22.04 or newer, and RHEL 9.

The package route is useful for an always-on Home Assistant companion host because it provides a systemd service and a protected token-file workflow. For a Debian or Ubuntu x64 package downloaded into the current directory, the documented sequence is:

sudo apt install ./localtonet-linux-x64.deb
sudo chmod 600 /etc/localtonet/auth-token
sudo localtonet --headless --authtoken-file /etc/localtonet/auth-token --check-config
sudo systemctl enable --now localtonet.service
sudo journalctl -u localtonet.service

Before running the configuration check, edit /etc/localtonet/auth-token as root and replace the placeholder with the actual token on one line. Do not paste the token into shared command output. ARM64 systems must use the matching ARM64 package. For RPM systems, select the matching RPM architecture and follow the package-specific commands currently shown on the download page rather than substituting Debian package commands.

Compared with the quick installer, the DEB or RPM path has explicit systemd and OpenSSL prerequisites but avoids repeatedly passing the token as a command-line argument. After an upgrade, the package documentation states that the configuration is preserved and the standard client service should be restarted.

Windows and macOS

Windows users can install through the Microsoft Store or use a current standalone build. Windows Service mode starts Localtonet automatically on boot and keeps it running after logout. Service installation and management require an elevated Command Prompt or PowerShell session, and the service can be inspected through services.msc.

On macOS, Localtonet provides Intel and Apple Silicon downloads and an official Homebrew tap:

brew tap localtonet/tap
brew install localtonet
localtonet --version

The current download page also documents launchd service mode. Select a build that matches the Mac architecture and verify service status after a restart.

Docker

The official Localtonet image can be pulled with:

docker pull localtonet/localtonet

Plan Docker networking before creating the tunnel. Inside the Localtonet container, 127.0.0.1 points back to that container. If Home Assistant is in another container, use a deliberately configured network path such as a resolvable service name on a shared user-defined network. If Home Assistant publishes port 8123 on the Docker host, use a host address that is actually reachable from the Localtonet container.

Do not assume host networking is portable across every Docker platform. Protect the AuthToken through the supported private configuration mechanism used by the deployment rather than embedding it in a public Compose file or image.

Create and start the Localtonet HTTP tunnel

Local validation and software installation should now be complete. The following sequence keeps the Localtonet product configuration separate from Home Assistant preparation and external testing. For current interface details, consult the Localtonet HTTP tunnel documentation.

Verify the browser, frontend connection, and Companion App

Test in layers so that a successful local request is not confused with successful remote operation.

Test with an external browser

1. Keep the local Home Assistant session open for recovery and log review.
2. Disconnect the test phone from home Wi-Fi and use mobile data, or use another external network.
3. Open the Localtonet public HTTPS URL.
4. Confirm that the Home Assistant login page loads without a gateway error.
5. Sign in using a normal Home Assistant account.
6. Open multiple dashboard views and entity dialogs.
7. Trigger or observe a safe state change and verify that the frontend updates without manual reload.
8. Leave the page open long enough to confirm that it does not repeatedly disconnect or become stale.

The final checks matter because Home Assistant's frontend uses a persistent connection for ongoing state updates. A login page or one rendered dashboard response does not establish that the full frontend session remains connected.

If Home Assistant reports an untrusted proxy, return to the logs, identify the immediate source address, update the existing http: section narrowly, validate the YAML, and restart safely. Do not guess based solely on whether Localtonet is installed on the same physical computer.

Configure the Home Assistant Companion App

The Companion App can use an external server URL when the phone is away from the home network. Menu names vary by mobile platform and app version. Open the server or connection settings for the Home Assistant server and set the external URL to the Localtonet public HTTPS address. Keep the internal URL set to a reachable local address if local network switching is desired.

Home Assistant can also maintain URL-related settings that integrations use when generating links or callbacks. Follow the current Home Assistant remote-access guidance and the Companion App networking documentation because exact controls and automatic connection behavior can vary by version and platform.

After saving the app configuration:

• Disable Wi-Fi and open the Companion App over mobile data.
• Confirm that login succeeds and dashboards continue updating.
• Test a harmless entity interaction.
• Open a notification link if notifications are part of the intended workflow.
• Check for repeated login attempts caused by stale stored credentials.

A browser working remotely does not guarantee that every integration accepts a new external hostname. Integrations involving OAuth redirects, generated links, webhooks, or callback URLs can have their own documented URL requirements.

Verify operation after reboot

Restart the device running Localtonet during a planned maintenance window. After it returns:

1. Confirm that Home Assistant is locally reachable.
2. Verify that the Localtonet service, app, container, or supported Home Assistant package started.
3. Confirm that the device appears connected in Localtonet.
4. Verify that the tunnel is running.
5. Repeat the external browser test.
6. Confirm that the frontend remains connected and receives live state updates.

Do not assume that operating-system autostart also starts every saved tunnel. Verify both the client connection and tunnel state after maintenance.

Routine operation and change management

Remote access is an operating service, not a one-time configuration. Small changes to LAN addressing, container networking, authentication, or app settings can break a previously working path.

Keep local addresses stable

If Localtonet targets a Home Assistant LAN address, reserve that address through the router or configure it according to the network's normal address-management practice. If Localtonet runs on another LAN device and that address is trusted by Home Assistant, keep its address stable as well.

For Docker, prefer a deliberate user-defined network and stable service discovery rather than copying a temporary container IP. Recreated containers can receive different addresses, and Docker network address translation can change the immediate source Home Assistant logs.

Review the endpoint after upgrades

After upgrading Home Assistant, Localtonet, the host operating system, Docker, a NAS platform, or the Companion App, repeat the local and external checks. Review Home Assistant logs for new proxy warnings and verify service startup after reboot.

Stop access when it is not required

Use the Localtonet dashboard to stop the tunnel when remote access is temporarily unnecessary. Delete obsolete tunnels and revoke a device token if it may have been disclosed. Stopping a tunnel and disconnecting a client are different lifecycle events, so verify the intended state explicitly.

Security checklist for internet-facing Home Assistant

IP banning can reduce repeated login attempts, but it is not a substitute for strong credentials, multi-factor authentication, updates, monitoring, and narrowly configured trusted proxies. Multi-factor authentication also does not protect an unpatched vulnerable component or an already authenticated session.

Maintain a local recovery account and a local management path. If remote access is the only way to administer the system, a stale external URL, accidental ban, invalid YAML file, or disconnected Localtonet client can turn a routine configuration problem into a lockout.

Troubleshoot by failure domain

Start by deciding whether the failure belongs to Localtonet, the local Home Assistant target, reverse-proxy handling, DNS or URL configuration, the Companion App, or authentication. Changing several layers at once makes the original cause difficult to identify.

A practical isolation sequence

1. Open Home Assistant locally from the Localtonet device.
2. Confirm that login and live frontend updates work locally.
3. Confirm that the Localtonet client is connected.
4. Confirm that the HTTP tunnel is running.
5. Open the public URL in an external browser.
6. Inspect Home Assistant logs for proxy, ban, authentication, or configuration messages.
7. Only after the browser works, test the Companion App and integration-specific links.

If step one fails, the problem is not the public URL. If steps one through four pass but the public URL fails, investigate the tunnel configuration or relay connection. If the public browser works but the app fails, focus on the app's server URL, cached credentials, network switching, and version-specific settings.

Frequently asked questions