localhost:8123 is the default port of Home Assistant, the open-source home automation platform. On the machine running it, the dashboard is at http://localhost:8123; from a phone or laptop on the same network it's normally http://homeassistant.local:8123 or http://<IP>:8123. Getting to it from outside your home network is the part that takes some setup.
What runs on port 8123
| Install type | How 8123 is served |
|---|---|
| Home Assistant OS (Raspberry Pi, Green, Yellow, VM) | Built in, homeassistant.local:8123 |
| Home Assistant Container (Docker) | --network=host, so 8123 on the host |
| Home Assistant Core (Python venv) | hass, listens on 8123 |
ClickHouse also uses 8123 for its HTTP interface, so on a developer machine check which one you have with lsof -i :8123.
Fix "refused to connect" on port 8123
- Give it time. First boot of Home Assistant OS downloads and installs components; the page at
:8123can take many minutes to appear. - Use the IP, not
.local. mDNS names don't resolve on every network or OS, especially on some Android devices and across VLANs. Find the IP in your router's client list. - Docker. Home Assistant Container is meant to run with
--network=host. With bridge networking you must publish-p 8123:8123, and device discovery won't work properly. - Broken config. If Home Assistant started but the
http:section ofconfiguration.yamlis invalid, the web server may not come up. Checkhome-assistant.log, or run the configuration check from the CLI.
Free or change port 8123
# macOS / Linux
lsof -i :8123
# Windows
netstat -ano | findstr :8123
To move Home Assistant, set the port in configuration.yaml and restart:
http:
server_port: 8124
On Home Assistant OS, leave 8123 alone unless you have a reason; add-ons and the companion app expect it.
400 Bad Request behind a proxy or tunnel
Put Home Assistant behind Nginx, Caddy, Traefik or a tunnel agent that adds X-Forwarded-For, and you'll often get 400: Bad Request. Home Assistant refuses forwarded requests from proxies it doesn't trust. Tell it which proxies to trust:
http:
use_x_forwarded_for: true
trusted_proxies:
- 127.0.0.1 # proxy or agent on the same host
- 172.30.33.0/24 # example: add-on network on Home Assistant OS
Use the actual IP or range of your proxy; the log line for the rejected request shows it. Also make sure the proxy passes WebSocket upgrades, because the dashboard runs over a WebSocket at /api/websocket.
Access Home Assistant remotely
Options, from least to most setup:
- Home Assistant Cloud (Nabu Casa): the paid official service, which also funds the project.
- VPN (WireGuard, Tailscale): nothing public at all; your phone joins the home network.
- Tunnel: a stable HTTPS address with no port forwarding, useful when your ISP uses CGNAT or you can't change router settings. Webhook Relay has a Home Assistant add-on and setup guide, and a Raspberry Pi walkthrough using the
webhookrelaydagent in tunnel mode. There's also a TLS tunnels add-on guide. - Port forwarding 8123 on your router: works if you have a public IP, but puts the login page directly on the internet. Turn on multi-factor authentication first.
Whichever you pick, enable MFA for every user and keep Home Assistant updated.
Webhooks into Home Assistant
Automations can be triggered by a webhook trigger, which listens at /api/webhook/<webhook_id> on port 8123. Services like IFTTT, Zapier or a GitHub Action need a public URL for that. Instead of exposing the whole UI, forward only webhooks:
relay forward --bucket home http://localhost:8123/api/webhook/my-secret-id
The bucket's public URL goes to the sending service, the dashboard stays private, and every delivery is logged. Treat the webhook ID as a secret, since anyone who knows it can trigger the automation.