Open on your phone

There are two ways to use Homestead on a phone: the web app in your phone’s browser, and the Homestead phone app. The web app works on main today. The phone app can connect and sign in, but its main screens are still being built.

Your phone needs to reach the server

At home, your phone and the server share a Wi-Fi network, so the server’s local address works. Away from home, you need remote access; see Remote access. Tailscale is the simplest choice and works for the phone app too.

Use the web app

The web app runs separately for now

On main, the server answers the API on port 8080 but doesn't serve the web app yet: opening http://localhost:8080/ returns 501 not_implemented (webdist is still empty). Until that lands, run the web app's development server from the same checkout, as in Quick start. It listens on http://localhost:5173 and forwards /api, /media and /mcp to the server.

On a home network, start the web app with pnpm --dir web dev --host so your phone can reach it at the machine’s address, such as http://192.168.1.20:5173. The phone app talks to the server directly on port 8080.

1. On your phone, open the server’s address in the browser.

2. Sign in with your username and password.

3. Optional: install it to your home screen from the browser’s menu. Homestead is a progressive web app, so it opens like an app. On Android Chrome, “Share to Homestead” then appears in the share sheet and opens the add screen with the shared text.

Use the phone app

The Flutter app runs on iOS 15+ and Android 8+. It isn’t in the App Store or Google Play yet, so for now you build it from the mobile/ folder of the repository yourself.

Part of the app	Status
Connect, sign in, pair by QR, accept an invite, find on Wi-Fi	On main
Feed, story rail and hearth picks	Coming in 1.0 (M-03)
Story viewer	Coming in 1.0 (M-04)
Add people and share-sheet intake	Available on main (M-05)
People, person page, circles, import	Coming in 1.0 (M-06)
Settings and agent status	Coming in 1.0 (M-07)

When the app starts, it asks you to find your Homestead. Pick one of three ways.

Scan a QR code

1. On your computer, open Homestead using an address your phone can reach (not localhost), or set HOMESTEAD_BASE_URL. The QR code carries that address.

2. Show a pairing QR code. It appears on the last welcome step (“Open on my phone”) and will live under Settings → Open on phone. Available on main (W-09)

3. In the phone app, choose Scan QR from your computer and point the camera at the code.

4. The app signs you in as the member who made the code. No password needed.

A pairing code lasts 10 minutes and works once. It is also shown as 8 characters you can type.

Found on your Wi-Fi

The server announces itself on your local network as _homestead._tcp, using the household name. Choose Found on your Wi-Fi and tap your household.

This only works when the container can reach your local network’s multicast traffic. In Docker’s default bridge network it can’t, so nothing appears. On Linux you can run the container on the host network instead of publishing the port:

docker run -d --name homestead --network host -v homestead-data:/data homestead

With Compose, uncomment network_mode: host in deploy/compose.yaml (Linux only). See Docker Compose.

To turn the announcement off, set HOMESTEAD_MDNS=false.

Enter address

Choose Enter address and type the server address. A short form such as homestead.local:8080 works; the app adds the scheme. Then sign in with your username and password.

Note

A signed-in phone holds a device token (it starts with hsd_). It lasts 365 days and renews while you use it. A screen to list and revoke devices is planned for after 1.0.

Check that it worked

• In the browser: you see your feed after signing in.
• In the app: the connect screen shows “Signed in to” and your server.

If the app says “That address answers, but it isn’t a Homestead server”, check the port. If it says “We couldn’t reach Homestead at that address”, check that the phone is on the same network or on your Tailscale network. More in Troubleshooting.