Homelab Remote Access

Q: How do I reach Home Assistant from outside my network?

Run localport http 8123 --token tok_YOUR_TOKEN --region eu on a machine that can reach Home Assistant, list that machine's address under trusted_proxies in Home Assistant, and open the address the agent prints.

Summary

A tunnel gives a service on your home server a public address that stays the same. The agent connects outward, so your router keeps every port closed and it works behind carrier-grade NAT. Put a password or an IP allowlist in front of anything you would not show a stranger, and run the agent as a service so it starts again after a reboot.

How it works#

The agent runs on a machine in your home and connects outward to Localport. A request to the tunnel's address is carried over that connection to the port your service listens on. Your router accepts nothing inbound, your home IP address is not published, and a change of IP address by your provider breaks nothing.

You need a Localport account, the Localport agent, and the service running on your home network.

Publish a web service#

Create an HTTP tunnel in the dashboard, then run the agent with the port the service listens on. Each service gets its own tunnel and its own address.

Service	Default port	Command
Home Assistant	8123	`localport http 8123 --token tok_YOUR_TOKEN --region eu`
Grafana	3000	`localport http 3000 --token tok_YOUR_TOKEN --region eu`
Nextcloud	8080	`localport http 8080 --token tok_YOUR_TOKEN --region eu`
Pi-hole admin	80	`localport http 80 --token tok_YOUR_TOKEN --region eu`

The agent prints the public address:

https://my-application.eu.localport.dev

HTTPS is provided for you with a publicly trusted certificate. Some applications check how they are reached. Home Assistant needs the address of the machine running the agent listed under trusted_proxies, and Nextcloud needs the tunnel's host listed under trusted_domains.

Reach SSH#

SSH is not HTTP, so it uses a TCP tunnel:

localport tcp 22 --token tok_YOUR_TOKEN --region eu

Connect with the host and the port the agent prints:

ssh user@my-application.eu.localport.dev -p 47266

Reserve the port in the tunnel's settings so the address stays the same. TCP Tunnels covers it.

Run several services from one machine#

List every tunnel in one file and one agent process serves them all:

version: 1

tunnels:
  - name: home-assistant
    token: ${LOCALPORT_TOKEN_HA}
    upstream: 8123
  - name: grafana
    token: ${LOCALPORT_TOKEN_GRAFANA}
    upstream: 3000

localport connect --config localport.yaml

Configuration lists every field.

Limit who can open it#

A tunnel is public by default. Anyone who has the address can reach the service's own login page, so add a control in front of it:

IP Allowlists accept connections only from the addresses you name.
Basic Auth asks for a username and password before the request reaches your service.
Header Authentication admits only requests that carry a header you set.

Keep the service's own login switched on as well.

Keep it running after a reboot#

Run the agent as a background service so the tunnel comes back when the machine restarts. Installation has the systemd unit for Linux and the launchd file for macOS. Both keep the token in a file that only the service account can read.

The agent runs on a Raspberry Pi. The install script picks the 64-bit or the 32-bit ARM build for the board.

Frequently asked questions#

Does this work behind CGNAT?

Yes. Carrier-grade NAT gives you no public address to forward a port to. The agent makes an outbound connection instead, and that is not affected.

Do I need dynamic DNS?

No. The tunnel's address belongs to the tunnel and does not depend on your home IP address.

Is my home IP address exposed?

No. Visitors connect to the tunnel's address. Your home IP address is not in DNS and not in the connection a visitor makes.

Can I use my own domain?

Yes. Add a CNAME record and attach the domain to the tunnel. Custom Domains has the steps.

How do I reach Home Assistant from outside my network?

Run localport http 8123 --token tok_YOUR_TOKEN --region eu on a machine that can reach Home Assistant, list that machine's address under trusted_proxies in Home Assistant, and open the address the agent prints.

Does the tunnel reconnect on its own?

Yes. After a network drop or a wake from sleep the agent reconnects and keeps the same address. Run it as a service and it also starts after a reboot.