Reaching it from your devices

A household’s devices reach its server in up to three ways. Every invite carries all of the household’s addresses. Each app tries them all at once, preferring them in this order:

1. the tailnet, if you use Tailscale;
2. the home network, with the server’s own certificate;
3. from anywhere, over iroh through a relay.

The native apps use all three. A browser works best over Tailscale (below): at home, Homefellow is for the apps.

sudo homefellow access shows the addresses and how each stands.

The ports

Port	What it’s for
8787/tcp	plain HTTP: the setup page from any computer before setup; afterwards the household only to this computer itself and the tailnet (see below)
8788/tcp	the home network, over HTTPS with the server’s own certificate
8789/udp	direct connections from anywhere (iroh)

The home network

sudo homefellow access lan on        # then restart the server

The server makes its own certificate, kept in the data folder’s tls/. It serves HTTPS on 8788. It announces itself on the home network as _homefellow._tcp (mDNS), so apps can find it.

The fingerprint. Every invite carries the certificate’s SHA-256 fingerprint. An app trusts the household’s home address only if the certificate it’s shown has that fingerprint, so nobody else on the network can pretend to be your household. Browsers can’t check a fingerprint, so they show a certificate warning at home.

HTTPS only at home. After setup, the household travels only over HTTPS on the home network, the admin included:

• The plain-HTTP port (8787) serves the household to this computer itself (Tailscale Serve, the desktop app, a reverse proxy) and to tailnet addresses, which are already encrypted.
• To other devices on the home network, it answers 403 use_secure_connection, or a page in a browser saying to use the app. Before setup it serves the setup page to any computer, so a server without a screen can be set up from another one.
• The admin from another computer is at https://<computer>:8788/admin. The browser warns about the server’s own certificate the first time: check the fingerprint it shows against sudo homefellow access, then accept it. On the household’s computer itself, http://localhost:8787/admin needs no warning.

Devices that joined before home-network access was on have no fingerprint. The doctor lists them; give each a fresh invite.

Tailscale

If the household’s computer already runs Tailscale:

sudo homefellow access tailscale

It runs tailscale serve, which publishes Homefellow at https://<machine>.<tailnet>.ts.net with a certificate every browser trusts. That address goes first in every invite. If it says Tailscale needs permission, run sudo tailscale set --operator=$USER once.

From anywhere, with nothing to install

sudo homefellow access iroh on        # then restart the server

The server gets its own iroh key and keeps a small encrypted connection to a relay. Every invite then carries the server’s key and its relay. The apps reach home from anywhere:

• directly, when the networks allow, which is most of the time;
• through the relay, when they don’t.

It’s encrypted from end to end either way. The relay sees which devices talk, when and how much, never what’s said.

Who may connect. Each device has its own iroh key, sent when it joins. The server accepts connections only from keys of invited devices. A device’s token must belong to that same key. Signing a device out closes its connection within seconds.

The relay:

--relay	Means
homefellow (the default)	Homefellow’s own relay, https://relay.homefellow.org
n0	n0’s public relays, for development
https://…	a relay of your own: see running your own relay
off	direct connections only

Direct connections need UDP 8789 let through the firewall; without it, they still work through the relay.

Homefellow’s relay

A relay passes encrypted traffic between a household’s server and its devices when they can’t connect directly. It also tells devices their public address (QUIC address discovery), so most of the time they can connect directly instead.

Every household uses Homefellow’s own relay by default, at https://relay.homefellow.org. It’s the official iroh-relay on a small server, with fair-use limits: 50 new connections a second and 2 MiB/s per device.

What it can see: which devices’ keys talk to which, when and how much. Traffic is encrypted from end to end between the household’s server and its devices, so the relay never sees what’s said.

sudo homefellow doctor checks the relay is up (it asks the relay’s /healthz).

Using another relay

sudo homefellow access iroh on --relay https://relay.example.org

New invites then carry that relay. Devices that joined before keep working; give them a fresh invite to move them to the new relay.

Running your own relay

A relay needs a machine with a public address and a DNS name, on Ubuntu 24.04. Homefellow’s own relay runs on a $4-a-month cloud server. We estimate that’s enough for thousands of households. We’ll measure it as families join.

1. Point an A record (and an AAAA record for IPv6) at the machine, not proxied.
2. Open these ports: 22/tcp (SSH), 80/tcp, 443/tcp (relaying, over TLS) and 7842/udp (address discovery).
3. From a checkout of Homefellow’s source, run packaging/relay/setup.sh root@<the machine>. It builds iroh-relay at the pinned version, installs it as a locked-down service with its own Let’s Encrypt certificate, sets up the firewall and automatic security updates, then starts it. It’s safe to run again.
4. Check it: curl https://<your relay>/healthz.

The full runbook, with metrics and updating, is docs/RELAY.md in Homefellow’s source.

The relay’s iroh version must match the one Homefellow uses (packaging/relay/relay.pins). Update the relay when Homefellow’s iroh is upgraded.

The firewall

Many Linux machines have a firewall on. It blocks the family’s phones at home until the ports are let through:

sudo homefellow access firewall

State	Means
open	nothing to do
blocked	it shows the exact commands, such as sudo ufw allow 8788/tcp comment 'Homefellow'
unknown	the rules couldn’t be read without root. Run the commands it shows, then sudo homefellow access firewall --opened so the doctor stops warning

It never changes the firewall unless you ask (sudo homefellow access firewall --allow).

On Windows, the home network must be set to Private. On a Mac, allow incoming connections when macOS asks.

Don’t open the server to the internet any other way: no router port forwarding is needed.