Can Home Assistant Work Behind a Reverse Proxy on a Subpath?

Home Assistant can run behind a reverse proxy, but serving it reliably from a rewritten subpath is generally not a supported deployment boundary.

A page at example.com/homeassistant may return HTML while later requests still target root-relative assets, authentication routes, WebSockets, or integration callbacks. Test more than the first screen: use a fresh browser, sign in, open a live dashboard, reload a nested route, and complete one callback. If any layer drops the prefix, move Home Assistant to its own hostname rather than adding more rewrites.

Separate Reverse-Proxy Support From Subpath Support

A reverse proxy can terminate TLS and forward a hostname-root request to Home Assistant. A subpath adds a different requirement: every generated URL, asset, API call, WebSocket, redirect, and callback must consistently preserve a prefix that the application understands. Success at the proxy layer does not establish that application contract.

Home Assistant community testing reaches a direct verdict that the application does not support deployment under a URL prefix. The resolved answer to putting Home Assistant on a subpath recommends a subdomain regardless of proxy choice.

PASS for reverse-proxy support means Home Assistant works at the root of a dedicated hostname with correct forwarding. FAIL for the proposed subpath means one or more application routes lose the prefix. Do not combine those verdicts into a claim that reverse proxies themselves are incompatible.

Use Frontend Assets as the First Low-Risk Test

Open the proposed subpath in a private browser profile and inspect the network requests before changing Home Assistant. If the base document loads but JavaScript, icons, manifests, or translations request paths from the hostname root, the topology has already failed its first reversible discriminator.

A documented path-rewrite attempt returned the main page while frontend resources requested slash-prefixed URLs without the Home Assistant prefix. That root-relative asset failure is an application-path mismatch, not a missing file on the proxy.

PASS means every frontend resource returns successfully under the intended route. FAIL means 404 responses or root-path requests appear. Stop there and test a dedicated hostname; response-body substitution is brittle because future frontend builds can introduce new paths that the rewrite does not cover.

Test WebSockets, Authentication, and Nested Routes

A static dashboard shell is not a complete session. Sign in from a clean profile, watch entity updates for several minutes, refresh a nested dashboard URL, sign out, and sign back in. Then inspect whether HTTP upgrades, tokens, redirects, and route reloads retain the same public origin and path.

Home Assistant relies heavily on WebSockets for live frontend communication, so a proxy must preserve the upgrade path and headers. An operator's account of reverse-proxy WebSocket handling shows why loading HTML alone is not a sufficient compatibility test.

PASS means authentication, live updates, navigation, and direct reloads all work without path translation errors. FAIL confined to sockets or redirects still rejects the subpath design. Fixing one proxy directive does not prove callbacks and future routes will become prefix-aware.

Featured

ZimaCube 2 Personal Cloud Home NAS

ZimaCube2

$799.00 - $2,499.00

Buy Now

Choose a Dedicated Hostname as the Stable Boundary

Publish Home Assistant at the root of a dedicated hostname such as ha.example.com, then route that hostname through the reverse proxy to the internal service. This preserves one public origin without requiring the application to understand a path prefix. A private VPN or tunnel can provide the same clean root boundary without public exposure.

When an existing remote path breaks after network changes, verify DNS, public address, NAT, tunnel, and proxy routing independently. The ZimaSpace diagnostic for remote access after a router change provides that adjacent path check.

The alternative passes when a clean browser can load assets, establish a WebSocket, authenticate, refresh nested routes, and reach Home Assistant after a proxy restart. Keep the old route available only long enough to roll back DNS or proxy changes; do not operate two ambiguous public URLs indefinitely.

Stop When the Full Session Survives a Restart

Restart the proxy and Home Assistant once, then repeat the complete test from LAN and the intended remote network. Confirm the certificate name, forwarded client address, trusted-proxy boundary, login, live state, logout, and one integration callback. This is the original workload, not a reduced static-page check.

Declare success only for the root-hostname design that passes every step. A subpath that works only after custom response rewriting remains unsupported operational debt because an update can change asset or callback behavior. Document the known-good hostname, upstream address, and rollback configuration.

Escalate when the root-hostname design still fails, because the remaining cause is likely proxy trust, WebSocket forwarding, DNS, certificate, or routing rather than base-path support. Do not expose Home Assistant directly on an unprotected port merely to preserve the desired URL shape.