This is the full developer documentation for Homefellow # The setup guide for agents > For an AI agent setting up a Homefellow household server for someone, step by step, with what to ask the person first. This is for an AI agent, such as Claude Code or Codex, setting up a Homefellow household server for someone: on a Linux box, a home server or a computer that runs local AI models. Every step is a `homefellow` command that prints JSON with `--json`. The same step is an admin API call. Both are documented here: [the homefellow command](/reference/cli/) and [the admin API](/reference/admin-api/). Work step by step. After each step, read its JSON, then check `homefellow setup --plan --json` to see what’s next. Report back to the person in plain words what you did and what’s left. ## What you need to know first [Section titled “What you need to know first”](#what-you-need-to-know-first) * **One household per server.** Its data lives in one folder: `--data-dir`, by default `$XDG_DATA_HOME/homefellow`, or `/var/lib/homefellow` for the packaged service. That folder is the household. Back it up. Never share it. * **The AI runs on the household’s own computers.** Homefellow talks to local model servers such as Ollama, LM Studio, llama.cpp or vLLM, through Goose, which is bundled and checked by checksum. Don’t point it at a paid cloud service unless the person asks for that. * **Run the commands on the server machine,** as the user the server runs as. For the packaged service, that’s `sudo homefellow COMMAND`, which runs as the `homefellow` user with `/etc/homefellow/server.toml` (`homefellow-admin` is the same, under its older name). In Docker it’s `docker compose -f packaging/docker/compose.yaml exec homefellow homefellow COMMAND`. Otherwise it’s plain `homefellow COMMAND` with the same `--data-dir` and `--config` as the server. Commands may run while the server runs: it takes up changed settings within a few seconds. * **Exit codes:** 0 means it worked; 1 means it failed or the doctor found a problem (the JSON says what); 2 means bad usage. * **Ask the person before:** * publishing the server on their tailnet (`access tailscale`); * turning on home-network access (`access lan on`), which opens a port on their network; * turning on reaching it from anywhere (`access iroh on`), which keeps an encrypted connection to a relay on the internet; * running the model test, which makes real calls to their model server for a minute or two. ## The steps [Section titled “The steps”](#the-steps) ### 0. Check where things stand [Section titled “0. Check where things stand”](#0-check-where-things-stand) ```sh homefellow setup --plan --json homefellow doctor --json ``` `plan.next` is the next step to take. Each step has `state`: * `done`; * `todo`; * `attention`: something’s wrong; `detail` says what; * `optional`. Each also has `command` and `api`. In the doctor’s report, every check has `status` (`ok`, `warn`, `fail` or `skip`), `detail` and, when something’s wrong, `fix`. ### 1. The household and its owner [Section titled “1. The household and its owner”](#1-the-household-and-its-owner) Ask the person: * the household’s name, such as “The Smiths”; * their own name; * the time zone, if `homefellow setup --plan --json` and `GET /api/admin/timezone` don’t show the right one. ```sh homefellow setup --household "The Smiths" --owner "Alex" --timezone America/New_York --json ``` The setup command can also take the other steps with flags: * `--models recommended`; * `--lan on`; * `--tailscale`; * `--backups 03:15`. It prints the owner’s invite as `invite.url`. Give that link to the person to open on their phone. Don’t post it anywhere else: it signs them in as the owner. With `--lan on`, the certificate is made before that invite, so it carries the fingerprint (`invite.join.fingerprint`) and the phone can use the home address from the start. Over the API, pass `"lan": true` to `POST /api/admin/setup` for the same. `setup` works only once. After that, `homefellow invite` makes more invites. Over the API, use the setup code instead: ```sh CODE=$(homefellow setup-code) curl -X POST -H "X-Homefellow-Setup-Code: $CODE" -H 'content-type: application/json' \ -d '{"household": "The Smiths", "owner": "Alex", "device": "setup agent"}' http://127.0.0.1:8787/api/admin/setup ``` With `device`, the reply’s `token` is an owner’s device token for the rest of the admin API (`Authorization: Bearer `). Treat it as a password. ### 2. The AI models [Section titled “2. The AI models”](#2-the-ai-models) ```sh homefellow models discover --json # this computer homefellow models discover --host 192.168.1.40 --json # and another machine on the home network homefellow models discover --url http://gpu-box:8000/v1 --json ``` **Reading the result.** `recommendation.verdict` tells you what was found: * **`good`:** a model of 30B or more, or the GLM Homefellow is tuned on. * **`maybe`:** 14B to 30B. * **`too_small`:** under 14B. * **`unknown`:** the size couldn’t be read. * **`none`:** no model server answered. `recommendation.words` says this in words for the person. If nothing good is found, tell them what was found and that Homefellow needs a model of about 30B or more to read reliably. Don’t choose a tiny model without saying so. ```sh homefellow models choose --recommended --json # or a specific one: homefellow models choose --url http://127.0.0.1:11434 --model qwen3:32b --json ``` Then test it, with the person’s go-ahead: it makes real model calls. ```sh homefellow models test --json ``` **What the test does:** it reads an invented note about a dog’s rabies booster and a passport, then chooses a question. **What the verdict means:** * **`good`:** both things were found and a question was chosen in good time. * **`slow`:** it works, but slowly. * **`too_small`:** it missed things. * **`failed`:** a model didn’t answer, or answered but never with something Homefellow could use. `words` says which and the address it tried (“Failed: the reading model … didn’t answer: … Check that it’s running at …”). Check its server is running there and the model is loaded. Pass `words` on to the person. ### 3. Voice (optional) [Section titled “3. Voice (optional)”](#3-voice-optional) ```sh homefellow voice --json # how it stands homefellow voice fetch --json # download the speech model (148 MB), for answers spoken in the apps # Over the API it runs in the background: POST /api/admin/voice/fetch, then poll # GET /api/admin/voice/fetch until state is done or failed (bytes and total show how far it is). homefellow voice off --json # or turn voice off ``` Voice changes take effect when the server restarts. ### 4. Reaching it from the family’s devices [Section titled “4. Reaching it from the family’s devices”](#4-reaching-it-from-the-familys-devices) ```sh homefellow access --json ``` There are three ways. The person chooses: * **At home only, with nothing extra to install:** * Run `homefellow access lan on --json`. * After the server restarts, it serves HTTPS on port 8788 with its own certificate. It announces itself on the home network. * Phones join by the invite, which carries the certificate’s fingerprint. * A browser on the home network shows a certificate warning. The apps don’t, because they check the fingerprint. So at home the family uses the apps; a browser works over Tailscale. After setup, the plain-HTTP port (8787) serves the household only to this computer and the tailnet, after a two-hour window that lets a server without a screen be finished from another computer’s browser. The admin from another home computer is at `https://:8788/admin`. * Before anyone scans an invite, they install the Homefellow app (`homefellow.org/join` lists where to get it for each device). Invite links open `https://homefellow.org/join#hf1.…`. The part after the `#` is the invite and never reaches a website. * **Anywhere, with Tailscale:** * This works only if Tailscale is already installed and connected (`tailscale.running` is `true`). * Run `homefellow access tailscale --json`. It runs `tailscale serve`, which gives a real HTTPS address on the tailnet. That address goes first in every invite. * If it says Tailscale needs permission, tell the person to run `sudo tailscale set --operator=$USER` once, or to run the `tailscale serve` command it shows. * **Anywhere, with nothing to install (iroh):** * **Ask the person first, in these words:** “The server keeps a small encrypted connection to Homefellow’s relay, so the family’s phones can reach home from anywhere, with nothing to install. The relay sees only encrypted traffic (which devices talk, when and how much), never what’s said. You can turn it off or use another relay.” The wizard ticks it by default and `homefellow setup` asks with a yes default, but it’s the person’s choice. * At setup, pass `--anywhere on` to `homefellow setup` (or `"anywhere": true` to `POST /api/admin/setup`), so the owner’s first invite carries it. Later, run `homefellow access iroh on --json`. After the server restarts, it has an iroh endpoint with its own key. Every invite then carries it. The apps reach the household from anywhere: directly when they can, through the relay when they can’t, encrypted from end to end. * The relay defaults to Homefellow’s own, `https://relay.homefellow.org` (`--relay homefellow`). `--relay n0` is n0’s public relays, for development. `--relay https://…` is a relay of the household’s own. * `homefellow doctor` asks the relay’s `/healthz` and says plainly if it can’t be reached. * Direct connections need UDP 8789 let through the firewall (`sudo ufw allow 8789/udp comment 'Homefellow'`). Without it, they still work through the relay. * The browser web app can’t use iroh. It needs the home network or Tailscale. **The firewall.** Many Linux boxes have one on (ufw or firewalld). It blocks phones at home until the ports are let through: ```sh homefellow access firewall --json ``` **What `firewall.state` means:** * **`open`:** nothing to do. * **`blocked`:** show the person `firewall.commands` (such as `sudo ufw allow 8788/tcp comment 'Homefellow'`) and, with their go-ahead, run them (or `sudo homefellow access firewall --allow`). * **`unknown`:** the rules couldn’t be read without root. Show the commands. Once they’re run, or the person says the ports are open, record it with `homefellow access firewall --opened`, so the doctor stops warning. Never change the firewall without the person’s say-so. **Devices that joined before home-network access was on** had no fingerprint in their invite. The doctor’s `devices.pinning` lists them. Give each a fresh invite (`homefellow invite --user `), unless it reaches the server over Tailscale, where the app learns the fingerprint by itself. Don’t open the server to the internet any other way unless the person asks: no router port forwarding. ### 5. Calendars (optional) [Section titled “5. Calendars (optional)”](#5-calendars-optional) Calendars are connected in the app’s Settings by an owner: iCloud with an app-specific password, which the person makes at appleid.apple.com. Don’t ask for their Apple ID password. ### 6. The family [Section titled “6. The family”](#6-the-family) ```sh homefellow invite --name "Jordan" --json # a member homefellow invite --name "Sam" --role owner --json # another owner homefellow invite --user --json # another device for someone (`homefellow people --json` lists ids) ``` Give each link to its person. Links expire after 72 hours (`auth.invite_ttl_hours`). A kitchen screen joins with an invite of its own, then is set to kitchen-screen mode in the app’s Settings. ```sh homefellow invites --json # every invite: open, used, expired or revoked homefellow invites revoke --json # withdraw one sent to the wrong person homefellow people role owner --json # or member; the household always keeps an owner homefellow setup --later family --json # if the person will invite everyone later ``` ### 7. Backups [Section titled “7. Backups”](#7-backups) ```sh homefellow backups run --json homefellow backups check --json # it would restore: ok true homefellow backups schedule 03:15 --json # the server's own daily backup (optionally --keep 14 --dir DIR) ``` **Restoring**, with the person’s go-ahead: ```sh homefellow backups restore --json # checked, then the household as it is now is backed up first sudo systemctl restart homefellow # the restore happens as the server starts homefellow doctor --json # the restore check says what was restored homefellow backups restore --cancel # call it off before the restart ``` The household as it was is kept twice: in the safety backup and in `before-restore-/` in the data folder. Devices that signed in after the backup was made need a new invite. The settings, the certificate and the speech model stay as they are. Backups are the server’s own, into the data folder’s `backups/` (`/var/lib/homefellow/backups` for the packaged install). A release’s `server.toml` sets them daily at 03:15, keeping 14. ### 8. Check and report [Section titled “8. Check and report”](#8-check-and-report) ```sh homefellow doctor --json homefellow setup --plan --json ``` Report to the person: * what’s set up; * which models, with the test’s `words`; * how the family’s devices reach it; * that the invite links were handed over; * when backups run; * anything still `todo` or `attention`, with its `fix`. ## Restart [Section titled “Restart”](#restart) Voice, home-network access, the listening address and a restore take effect when the server restarts. `GET /api/admin/status` lists them in `restart_needed`. Restart the way it runs: * the packaged service: `sudo systemctl restart homefellow`; * a server in a terminal: stop it, then run `homefellow serve`. # Set up Homefellow with your AI assistant > Paste one message into Claude, ChatGPT, Codex or another AI assistant. It walks you through setup. An AI assistant that can run commands on your computer, such as Claude Code or Codex, can set Homefellow up with you. One that can’t run commands, such as a chat in your browser, can still guide you step by step and explain what each command says. **Paste this into your assistant:** ```text Help me set up Homefellow, a private helper for my family that runs on a computer at home. Read https://docs.homefellow.org/llms.txt first, then the setup guide for agents at https://docs.homefellow.org/agents/setup-guide.md. Follow it. Ask me before anything that changes my network or firewall, or that calls my AI models. At the end, tell me in plain words what's set up and what's left. ``` **What it will ask you:** * the household’s name, your name and your time zone; * which AI model server to use, if it finds more than one; * whether to run the model test, which takes a minute or two; * whether to turn on the home network, Tailscale or reaching it from anywhere, each in plain words; * whether to change the firewall, showing you the exact command first; * who to invite. Keep invite links and sign-in tokens out of cloud assistants An invite link signs someone in to your household. The first one makes them an owner. A sign-in token works like a password. Don’t paste either into an assistant that runs in the cloud. Ask your assistant not to repeat them back to you in chat. Even an assistant that runs commands on your computer sends what it reads to its AI provider. So have it save invites to a file without showing them (for example `homefellow invite --name Sam > ~/sam-invite.txt`), then open that file yourself. Or run `homefellow invite` yourself and send the link straight to the person it’s for. **For your assistant:** every page on this site is also plain Markdown (add `.md` to its address). [llms.txt](/llms.txt) lists them. [llms-full.txt](/llms-full.txt) is the whole site in one file. **Questions later.** Your assistant can answer questions about Homefellow too: give it this site’s address and ask. # Getting started > Which setup is yours, what the household's computer needs, then installing Homefellow, setting it up in your browser and inviting your family. Not released yet Homefellow’s first release isn’t published, so the installer below says there’s nothing to install yet. This page is exactly how setup will go once it is. ## How it fits together [Section titled “How it fits together”](#how-it-fits-together) * **The household’s computer** runs the Homefellow server. It’s usually a computer that stays on, such as a home server or a computer built for AI. One server is one household. * **The AI models** run on that computer or another one at home. Homefellow uses them to read what you tell it and to choose what to ask next. * **The apps** on your family’s phones, computers and a kitchen frame reach that server: at home over your home network, away from home through Homefellow’s relay or Tailscale. ## Which setup is yours? [Section titled “Which setup is yours?”](#which-setup-is-yours) A home server or a computer for AI A computer that stays on: a Linux box, a home server or a computer with a powerful graphics card or built for AI. Homefellow works best this way. The steps below are for you. Just a Mac or a Windows computer The desktop app can run the household on the computer it’s on. Your family reaches Homefellow while that computer is on and awake. See [installing on a Mac or Windows](/reference/install/#on-a-mac-or-windows). You want the technical details The one-line script, packages or Docker, choosing models, networking, the `homefellow` command and the admin API: start with [installing](/reference/install/). **What the household’s computer needs:** * **To stay on.** Your family’s apps reach Homefellow through it. * **To run a good AI model,** or to reach one on another computer at home. That means a powerful computer made for AI, or a gaming PC with a large graphics card. The exact requirements will be published with the first release. Smaller computers will manage as models get better. * **Linux, a Mac or Windows.** Linux is the best tested. ## Setting it up [Section titled “Setting it up”](#setting-it-up) It takes about fifteen minutes, most of it the AI test. 1. **Install Homefellow on the household’s computer.** Open a terminal on it and run: ```sh curl -fsSL https://homefellow.org/install.sh | sh ``` It downloads Homefellow, checks it’s really ours, installs it and starts it. The check uses `ssh-keygen`, which almost every Linux computer already has. If it’s missing, the installer says how to get it (on Ubuntu or Debian, `sudo apt install openssh-client`). Other ways to install, including Docker, are in [installing](/reference/install/). 2. **Open the setup page.** On any computer or phone at home, open the address the installer printed, such as `http://homeserver.local:8787/setup`. It asks for a **setup code**. Only someone at the household’s computer can see it: run `sudo homefellow setup-code` there. The code stops anyone else on your network from setting Homefellow up before you. 3. **Name the household.** Give the household’s name and your own. You’ll be its first owner. Two choices are ticked for you: * **Phones and computers at home reach it on the home network,** securely, with the server’s own certificate. * **The family’s phones reach it from anywhere,** through Homefellow’s relay. The relay only passes on encrypted traffic and never sees what’s said. You can untick it. 4. **Choose the AI.** Setup looks for AI model servers on this computer, such as Ollama or LM Studio. It also looks on another computer at home if you type its name. It recommends a model and runs a short test: it reads an invented note and chooses a question. The result is in plain words, such as “Good: it read a note in 42 s”. If the model didn’t answer at all, it says so and where to check that it’s running. If nothing good is found, you can carry on and choose later. See [the AI models](/reference/models/). 5. **Voice, if you want it.** Homefellow can turn spoken answers into text on this computer. That needs a 148 MB download, or you can leave voice off. 6. **Check how your devices will reach it.** The “Reaching it” step lists the household’s addresses. If this computer has a firewall on, it shows the exact command that lets your phones through, such as `sudo ufw allow 8788/tcp comment 'Homefellow'`. Nothing is changed without you. If you already use Tailscale, one button publishes Homefellow on it. 7. **Connect your calendars and email,** if you’d like. Homefellow reads only the accounts you choose. For iCloud calendars, make an app-specific password at appleid.apple.com. You can do this later in the app’s settings. 8. **Invite your family.** First, each person installs the Homefellow app on their phone or computer (see [the apps and the kitchen frame](/start/the-apps/)). Then they scan their own invite inside the app. Each invite is a QR code or a link, with a role: a member or an owner. An invite’s link opens `homefellow.org/join`, which says where to get the app. The invite itself stays on the phone and never reaches any website. Invites last three days. 9. **Check the backups.** Homefellow backs the household up every night at 03:15 and keeps the newest 14. Change the time if you like, make one now and check it would restore. 10. **Finish.** The last step shows a check of everything in plain words. Then install the app on your own phone and scan the invite setup made for you, so you’re signed in as the owner there too. ## Next [Section titled “Next”](#next) * **Put Homefellow on your phone** and the family’s. Set up a kitchen frame too if you have one: [the apps and the kitchen frame](/start/the-apps/). * **Answer the first questions.** Homefellow learns your household a few questions at a time: [using it day to day](/guide/day-to-day/). You can change anything from setup later. Owners find it all in the app’s Settings under the server, or in the browser at `/admin`. After setup, the admin on the home network is over HTTPS (`https://homeserver.local:8788/admin`), so the browser warns about the server’s own certificate the first time. For two hours after setup, the plain address keeps working from another computer at home, so a server without a screen can be finished from your laptop. On the household’s computer itself, `http://localhost:8787/admin` always works without a warning. Why the family uses the apps at home At home, Homefellow talks only over an encrypted connection. The apps check the server’s own certificate by the fingerprint in each invite, so they connect without a warning. A browser can’t do that check, so it warns. That’s why the family uses the apps. It’s also why a browser works best over Tailscale. [Prefer a terminal, or your AI assistant?](/agents/with-your-ai/)Every setup step is also a homefellow command. Your AI assistant can walk you through it. # Using it day to day > Today and Home, the calendar, email and calendars it reads, answering questions, asking it things, Done and Undo. Homefellow has two places: **Today** for what’s going on and **Home** for helping Homefellow learn your family. Settings opens from your initial at the top. ## Today [Section titled “Today”](#today) Today shows the scene at the time of day, then **what needs you**, then the calendar. **What needs you** is a short list. Each row says what kind of thing it is, what to do, when and why now: * **Today:** something to do today. * **Running late:** something that’s past its time. * **Coming up:** something that needs starting soon. * **Assumed: needed?** Homefellow thinks this usually goes with something you’ve told it. For example, a gift with a birthday party. Say yes if it’s needed, or “Not needed”. * **You disagree:** two of you said different things, such as two times for the same recital. * **A clash:** two things at once. * **Needs an answer:** something on the calendar that’s waiting on a question. It opens the question. Tap a row to open it. You’ll see why it’s there, who it’s for and who’s doing it, where the information came from and what’s happened so far. Then: * **Done:** it’s done. On a phone, a swipe does the same. * **Not needed:** this one isn’t needed. * **Not now:** put it off until tomorrow, in 3 days or next week. * **More:** waiting on someone, who’s doing it, fix the title, never for us, not on a given day, it’s off, turn off. After Done or Not needed, **Undo** appears for a few seconds, in case you tapped the wrong one. **When you disagree,** the item shows each answer, such as “2:00 pm, as Ada says” and “3:00 pm, as Tunde says”. Pick the right one, or choose “Neither, it’s…” and say what it really is. Both stay on record until one of you settles it. **When nothing needs you,** Today says so. The scene fills the top of the screen. ## The calendar [Section titled “The calendar”](#the-calendar) Below what needs you is the calendar: the **agenda** (today, then the days ahead), the **week** or the **month**, switched at the top. Each entry is marked by where it came from: * **outlined:** from your own calendars; * **filled in blue:** Homefellow’s own; * **a strip of tape:** something that’s due; * **a pencilled outline:** a guess Homefellow isn’t sure of yet. Homefellow can also keep a calendar of its own in your calendar account. You choose which calendar is Homefellow’s in Settings. What it learns shows up there on everyone’s phones. It writes only to that calendar. If you change one of its events in your own calendar app, your version wins. ## Reading along with email and calendars [Section titled “Reading along with email and calendars”](#reading-along-with-email-and-calendars) If you connect them, Homefellow reads along with your email, your calendars and your messages, so it notices changes without being told. When school moves the trip to Friday or the class needs a white t-shirt, it shows up in what needs you, with the email one tap away. When practice moves to Thursday, the calendar already knows. It reads only the accounts you choose, on the household’s computer. It never sends an email, never changes your own calendars and never touches your accounts. You can disconnect any of them in Settings. ## Home [Section titled “Home”](#home) Home is where you help Homefellow learn your household. **The question.** Homefellow asks one question at a time, the one that would help most right now. Answer in your own words, or by voice where your device has a microphone. The next question follows as soon as you answer. After a few, Homefellow says “That’s plenty for now”. You can stop or keep going. **Skipping.** When you skip a question, say why. It changes what happens next: * **I don’t know:** Homefellow won’t ask again soon. It may ask you to look it up instead. * **Not now:** it’ll ask again in a few days. * **Don’t ask about this:** it won’t bring the subject up again, unless you do. **Have ten minutes?** A sit-down session asks one question after another, each following from your last answer. It’s the quickest way to get Homefellow up to speed. **Something to find out.** Now and then Homefellow asks you to look something up: a date printed on a document, or a detail from a provider. Reply with what it says. You can add a photo, which is kept with your reply. **Ask Homefellow.** When you need to know something, like when the car insurance renews or who’s driving Thursday, just ask. It answers from what it knows about your household and says where the answer came from. When it doesn’t know, it says so. **Tell Homefellow something.** Anything you’d mention to someone helping out, in a sentence: “Kofi’s inhaler is running low”, “Swim moved to Thursdays”. Homefellow works out where it belongs. **What Homefellow knows.** The people, things and how you do things, each opening to what’s noted. If something’s wrong, tell Homefellow. It’ll correct it. ## Settings [Section titled “Settings”](#settings) * **Appearance:** the time of day (the colours follow the day), your device’s setting, always light or always dark. * **Notifications:** a morning summary and an alert when something’s running late. * **Email and calendars:** the accounts Homefellow reads and Homefellow’s own calendar. * **The household:** its people, their devices and invites. Owners also see the server’s settings. * **How this device reaches the household:** which of the household’s addresses it’s using. # Fixing problems > What to do when a phone can't reach the household, the setup code doesn't work or the doctor reports a problem. Most problems are about reaching the household’s computer. Start with the doctor: on that computer, run `sudo homefellow doctor`. Owners also see it in the app’s Settings, under the server. It checks everything and says what’s wrong in plain words, with the fix. ## “Can’t reach the household” [Section titled ““Can’t reach the household””](#cant-reach-the-household) Work through these in order. 1. **Is the household’s computer on and awake?** If it’s a laptop or a desktop that sleeps, the family can’t reach Homefellow until it’s awake. 2. **Is Homefellow running?** On the household’s computer, `sudo systemctl status homefellow` should say “active (running)”. If not, `sudo systemctl start homefellow`, then look at `journalctl -u homefellow -e` for the reason. 3. **At home, the firewall is the usual cause.** If the computer has a firewall on, it may block your phones. Run `sudo homefellow access firewall` to see, with the exact command that lets them through, such as: ```sh sudo ufw allow 8788/tcp comment 'Homefellow' sudo ufw allow 8789/udp comment 'Homefellow' ``` On Windows, your home network has to be set to Private, not Public: in Settings, then Network & Internet, open your network and choose Private. 4. **Away from home, check the relay.** If you turned on “reach it from anywhere”, the doctor checks Homefellow’s relay and says if it can’t be reached. In the app, Settings shows “From anywhere” and whether it’s in use. 5. **Did the household’s computer move to another address?** The apps keep every address the invite carried. If you changed the network, the computer’s name or Tailscale, give the device a fresh invite. ## The setup code doesn’t work [Section titled “The setup code doesn’t work”](#the-setup-code-doesnt-work) * **The code is on the household’s computer:** run `sudo homefellow setup-code`. It’s printed when Homefellow starts too. * **Capitals and the hyphen don’t matter.** `abcd2345` works as well as `ABCD-2345`. * **After five wrong codes**, it waits a few minutes before taking more. * **“Already set up”** means the household exists. The code is spent. Sign in with an invite instead. ## An invite doesn’t work [Section titled “An invite doesn’t work”](#an-invite-doesnt-work) * **“Already been used”:** each invite signs in one device. Ask an owner for a new one. * **“Expired”:** invites last three days. Ask for a new one. * **“Withdrawn”:** an owner took it back. Ask them for a new one. * **A page saying to get the app:** that’s `homefellow.org/join`. Install the Homefellow app, then open the invite link again (or use “Copy the invite” and paste it into the app). The invite never leaves your phone. * **“This invite link looks incomplete”:** part of the link was cut off, often by a messaging app. Ask for the link again, or scan the QR code inside the app. * **A certificate warning in the browser:** that’s expected on the home network, because the household uses its own certificate. Use the Homefellow app instead, which checks the certificate against the invite. * **“Open Homefellow in its app” in a browser at home:** at home, Homefellow is for the apps. Use the app, or the household’s Tailscale address in a browser. ## The AI isn’t working [Section titled “The AI isn’t working”](#the-ai-isnt-working) * **“Failed: the reading model didn’t answer”:** the model server isn’t running, the address is wrong or the model isn’t loaded. The message says which address it tried. Start the server (for example open Ollama), then run `sudo homefellow models test` again. * **“It answered, but never with something Homefellow could use”:** the model is running but isn’t following Homefellow’s instructions. Try a larger or newer model. * **“Too small”:** the model missed things in the test. Homefellow needs a model of about 30 billion parameters or more to read reliably. See [the AI models](/reference/models/). * **“Slow”:** it works, but slowly. A faster computer helps, or a smaller model that still passes the test. ## What the doctor’s checks mean [Section titled “What the doctor’s checks mean”](#what-the-doctors-checks-mean) | Check | What it looks at | | -------------------------------------- | -------------------------------------------------------------------------------- | | Setup | whether the household is set up | | The reading model, the questions model | whether each AI model answers | | Goose | the tool Homefellow uses to talk to the AI, at the version it should be | | The model test | the last test of the models and how it went | | Voice | whether spoken answers can be turned into text | | Disk space | room for the household’s data and backups | | The household’s time zone | that dates and reminders use the right one | | Calendars | that connected calendars are syncing | | Reaching it from your devices | that the household’s addresses answer | | The firewall | whether the firewall lets your phones through at home | | The home-network certificate | the certificate the apps check at home | | Devices without the fingerprint | devices that joined before home-network access was on; each needs a fresh invite | | Reaching it from anywhere | whether the relay can be reached | | Backups | that a recent backup exists and would restore | | A restore | a restore waiting for the next start, or the last one done | | Version | which version is running | Each one is ok, a warning or a problem. A problem always comes with a fix. ## Still stuck? [Section titled “Still stuck?”](#still-stuck) Ask your AI assistant, with this site’s address: see [set up Homefellow with your AI assistant](/agents/with-your-ai/). It can run the doctor with you and read what it says. # Privacy, in plain words > Where your family's information lives, what leaves your home and what never does. **Your family’s information stays at home.** Homefellow runs on a computer in your home. Everything it learns and everything you tell it is kept on that computer. The AI runs at home too. Nothing is sent to us or to an AI company. **What does leave your home:** * **Reaching home from anywhere,** if you turned it on. The household’s computer keeps a small encrypted connection to Homefellow’s relay, so your phones can reach it away from home. The relay passes on traffic it can’t read. It sees which devices talk to each other, when and how much, never what’s said. You can turn this off, or use another relay. * **Reading the accounts you connect.** Homefellow reads the email, calendars and messages you choose, from your providers, on the household’s computer. What it reads stays on that computer. It writes only to the one calendar you chose as its own. It never changes your other calendars and never sends email. * **Updates.** When you update, the household’s computer downloads Homefellow from `releases.homefellow.org`. **Where the household’s information lives:** on its own computer at home. That’s your answers, your notes, the household’s calendar, what Homefellow knows about each person, your photos and recordings. Your own phones and computers reach it there. If you connect calendars or email, Homefellow reads them and writes its own calendar into the account you choose, so that calendar also lives with your calendar provider. **Nothing changes without you.** Homefellow suggests and reminds. It won’t change your other calendars or your accounts. What it assumes, it marks “Assumed: needed?” and waits for your yes. **It shows its work.** Every item says where its information came from: whose answer and when. **It’s open source,** so anyone can check exactly what it does with your family’s information. **Nothing is used to train an AI model.** Your answers teach Homefellow your family’s ways, on your own computer. Nothing you share is used to train an AI model, here or anywhere else. The website homefellow\.org has its own privacy page, about the site and its email list: [homefellow.org/privacy](https://homefellow.org/privacy/). # Homefellow help > A private helper for family life. It gets to know your household, keeps one calendar for everyone and tells you what needs you and why. Running a household means carrying a lot in your head: the dentist on Thursday, the school form that’s due before the trip, the dog’s yearly checkup. Homefellow carries some of it with you. It learns your family a few easy questions at a time. It reads along with your email and calendars if you let it. Then it brings up the few things that need you now, each with why. ## What we stand for [Section titled “What we stand for”](#what-we-stand-for) * **Your family’s information stays at home.** Homefellow and its AI run on a computer in your home. Nothing is sent to us or to an AI company. * **Free and open source.** No subscription, no ads. Anyone can see exactly what it does. You provide the computer it runs on. The project runs the shared relay at no cost to families. * **It shows its work.** Everything it tells you says where it came from. When it doesn’t know, it says so. * **Your family is in charge.** It suggests and reminds. It doesn’t change your calendars or accounts without you. * **For families of every shape.** It never assumes who does what from who someone is. ## Where it stands [Section titled “Where it stands”](#where-it-stands) Homefellow is being built in the open. It isn’t released yet, so there’s nothing to install today. These pages describe how it will work. To hear when you can try it, leave your email at [homefellow.org](https://homefellow.org/#updates). Using Homefellow Getting started, the apps and the kitchen frame, using it day to day, privacy in plain words and fixing problems. Technical reference Installing it, the AI models, reaching it from your devices, the `homefellow` command, the admin API, backups and releases. For AI assistants Every page is also plain Markdown, with an `llms.txt` for agents. Your assistant can set Homefellow up with you. [Set Homefellow up with your AI assistant](/agents/with-your-ai/)The prompt to paste and what your assistant will ask you before it changes anything. # The admin API > The household server's admin API, for setup and its settings. Every call is also a homefellow command. The admin API sets the household up and manages the server. Every call here is also a `homefellow` command (see [the homefellow command](/reference/cli/)), which prints the same JSON with `--json`. ## Who may call it [Section titled “Who may call it”](#who-may-call-it) * **Before the household exists:** the one-time setup code, in the header `X-Homefellow-Setup-Code`. The server prints it when it starts. `homefellow setup-code` shows it again. Five wrong codes in ten minutes answer `429 slow_down`. Once the household exists, the code is spent (`403 set_up`). * **After:** an owner’s device token, as `Authorization: Bearer `. A member’s token answers `403 forbidden`. **Setup mode.** Until the household exists, only `/api/health`, `/api/admin/*`, `/setup` and the web app’s files answer. The rest answers `503 not_set_up`. **Settings** chosen here go into the data folder’s `settings.toml`. Models take effect at once. Voice, home-network access, the listening address and a restore take effect at the next start. `restart_needed` lists them. ## The calls [Section titled “The calls”](#the-calls) | Call | Command | What it does | | ------------------------------------------- | ------------------------------ | --------------------------------------------------------------------- | | `GET /api/admin/status[?probe=true]` | `status`, `doctor` | the doctor’s report, what needs a restart, the addresses, the version | | `GET /api/admin/plan` | `setup --plan` | the setup steps and where each stands | | `POST /api/admin/plan/later` | `setup --later family` | leave inviting the household for later | | `GET /api/admin/version` | `version` | the version and database schema | | `GET /api/admin/timezone` | | the computer’s time zone | | `POST /api/admin/setup` | `setup` | create the household and its first owner | | `GET /api/admin/models` | `models` | the models in use and the last test | | `POST /api/admin/models/discover` | `models discover` | look for model servers | | `POST /api/admin/models/choose` | `models choose` | use those models | | `POST /api/admin/models/test` | `models test` | test the models | | `GET`, `POST /api/admin/voice` | `voice` | how spoken answers are turned into text | | `GET`, `POST /api/admin/voice/fetch` | `voice fetch` | download the speech model and see its progress | | `GET /api/admin/access` | `access` | addresses, home network, Tailscale, iroh, the firewall | | `POST /api/admin/access/lan` | `access lan on\|off` | the home network, over HTTPS | | `POST /api/admin/access/tailscale` | `access tailscale` | publish on the tailnet | | `POST /api/admin/access/iroh` | `access iroh on\|off` | reach it from anywhere | | `POST /api/admin/access/firewall` | `access firewall` | record or open the firewall | | `GET`, `POST /api/admin/invites` | `invites`, `invite` | list or make invites | | `DELETE /api/admin/invites/{id}` | `invites revoke ID` | withdraw an open invite | | `POST /api/admin/people/{id}/role` | `people role ID owner\|member` | change someone’s role | | `GET`, `PUT /api/admin/backups` | `backups`, `backups schedule` | the backups and their schedule | | `POST /api/admin/backups/run` | `backups run` | make a backup now | | `POST /api/admin/backups/check` | `backups check` | check a backup would restore | | `POST`, `DELETE /api/admin/backups/restore` | `backups restore` | stage a restore, or call it off | ## The doctor and the plan [Section titled “The doctor and the plan”](#the-doctor-and-the-plan) `GET /api/admin/status` answers `{"doctor": Report, "restart_needed": [key], "setup": {"done"}, "addresses": [Address], "version"}`. With `probe=true` it also asks the model servers and addresses, which takes a few seconds. * **`Report`:** `{"ok", "problems", "warnings", "version", "checked_at", "checks": [Check]}`. * **`Check`:** `{"id", "status": "ok"|"warn"|"fail"|"skip", "title", "detail", "fix"?}`. * **The check ids:** `setup`, `models.keeper`, `models.explorer`, `goose`, `models.test`, `voice`, `disk`, `timezone`, `calendars`, `addresses`, `firewall`, `certificate`, `devices.pinning`, `iroh`, `backups`, `restore`, `version`. `GET /api/admin/plan` answers `{"steps": [Step], "next": id|null, "done": bool}`. Each step is `{"id", "title", "state": "done"|"todo"|"attention"|"optional"|"later", "detail", "command", "api"}`. The step ids are `household`, `models`, `goose`, `voice`, `access`, `calendars`, `family`, `backups`. ## Setting up [Section titled “Setting up”](#setting-up) `POST /api/admin/setup`, with the setup code: ```json { "household": "The Smiths", "owner": "Alex", "timezone": "America/New_York", "device": "setup agent", "lan": true, "anywhere": true } ``` It answers `{"household", "owner", "token", "invite"}`. * **`timezone`** defaults to the computer’s. * **`lan: true`** turns on home-network access and makes its certificate before the invite, so the owner’s first invite carries the fingerprint. * **`anywhere: true`** turns on reaching it from anywhere, with the relay in `relay` (Homefellow’s by default), so the first invite carries the server’s key. Ask the person first: it keeps a connection to a relay on the internet. * **With `device`,** the caller is signed in as the owner. `token` is its device token. Treat it as a password. * **`invite`** signs the owner in on another device: give its `url` to the person. * **It works once.** After that it answers `409 conflict`. ## Models [Section titled “Models”](#models) * **`POST /api/admin/models/discover`** `{"hosts"?: [host], "urls"?: [url]}` answers `{"found": [Found], "recommendation"}`. `Found` is `{"kind", "url", "models": [{"name", "billions"|null, "context"|null}]}`. The recommendation is `{"keeper", "explorer", "verdict": "good"|"maybe"|"too_small"|"unknown"|"none", "words"}`. * **`POST /api/admin/models/choose`** takes one of `{"keeper": Pick, "explorer"?: Pick}`, `{"keeper_profile", "explorer_profile"?}` or `{"recommended": true, "hosts"?, "urls"?}`. A `Pick` is `{"url", "model", "api_key"?, "context"?}`. * **`POST /api/admin/models/test`** answers `{"verdict": "good"|"slow"|"too_small"|"failed", "words", "reading_seconds", "question_seconds", "found", "missed", "question", "at"}`. It makes real model calls. ## Access [Section titled “Access”](#access) `GET /api/admin/access` answers `{"addresses": [Address], "primary", "lan", "mdns", "tailscale", "iroh", "firewall", "restart_needed"}`. * **`Address`:** `{"kind": "tailnet"|"public"|"mdns"|"lan"|"local", "url", "pinned"}`, in the order the apps prefer. `pinned` means it uses the server’s own certificate. * **`firewall`:** `{"manager", "ports", "state": "open"|"blocked"|"unknown"|"opened"|"none", "blocked", "words", "commands", "can_allow"}`. * **`POST /api/admin/access/lan`** `{"on", "port"?, "mdns"?}`: HTTPS on `port` (8788) after the next start. * **`POST /api/admin/access/iroh`** `{"on", "relay"?: "homefellow"|"n0"|"off"|"https://…", "port"?}`: reaching it from anywhere after the next start. `422 no_iroh` means this build has no iroh. * **`POST /api/admin/access/tailscale`** runs `tailscale serve` and records the `ts.net` address. `422 tailscale` says what’s wrong. * **`POST /api/admin/access/firewall`** `{"opened"?: bool, "allow"?: bool}`: record that the ports are open, or run the commands (only when the server runs as root). ## Invites [Section titled “Invites”](#invites) * **`POST /api/admin/invites`** `{"role"?, "name"?, "user"?}` answers `{"id", "code", "url", "join", "qr_svg", "expires_at", "role", "fingerprint"}`. `user` signs in another device for that person. * **The link** is `https://homefellow.org/join#hf1.`, from the server’s `server.join_url` (`--join-url`). The payload is base64url JSON: `{"v": 1, "household", "code", "addresses": [Address], "fingerprint"?, "iroh"?: {"key", "relay"?, "addrs"?}}`. The part after `#` never reaches a server, so homefellow\.org never sees the invite. The page there tells a newcomer to install the app. The apps open these links directly. * **The older form,** `

/invite/#hf1.` (or `

/invite/` alone), is still accepted everywhere. The server makes it when `server.join_url` is `off`, or when the payload has no address for other devices and no `iroh` part. * **`GET /api/admin/invites`** lists them, newest first, each `open`, `used`, `expired` or `revoked`. An invite’s code isn’t kept, so it can’t be shown again. ## Backups [Section titled “Backups”](#backups) * **`GET /api/admin/backups`** answers `{"dir", "keep", "daily_at", "backups": [{"name", "path", "bytes"}], "last_check", "restore", "last_restore", "restart_needed"}`. * **`PUT /api/admin/backups`** `{"dir"?, "keep"?, "daily_at"?: "HH:MM"|"off"}`. * **`POST /api/admin/backups/run`** makes one now. * **`POST /api/admin/backups/check`** `{"name"?}` answers `{"ok", "words", …}`: whether it would restore. * **`POST /api/admin/backups/restore`** `{"name"}` stages a restore for the next start, after checking the backup and backing up the household as it is now. `DELETE` calls it off. See [backups and restoring](/reference/backups/). The rest of the server’s API, for the apps, is documented in `docs/design/API.md` in Homefellow’s source. # Backups and restoring > How Homefellow backs up the household and how a restore works safely. Everything Homefellow knows lives in one data folder: a database and the household’s photos and recordings. A backup is a consistent copy of it, taken while the server runs, in a folder named by its time. A backup works as a data folder to restore from. ## Making backups [Section titled “Making backups”](#making-backups) ```sh sudo homefellow backups schedule 03:15 # the server's own daily backup (--keep 14 --dir DIR) sudo homefellow backups run # one now sudo homefellow backups # the backups, where they go and how many are kept sudo homefellow backups check # check the newest would restore ``` The server makes the backups itself, every day at 03:15. It keeps the newest 14. They go into the data folder’s `backups/` (`/var/lib/homefellow/backups` for the packaged install) unless you choose another folder. The setup page’s “Backups” step, the admin and these commands change it. The doctor checks the newest is recent and would restore. Keep a copy somewhere else too: another disk, or a NAS. A backup holds your family’s answers, so keep it private. ## Restoring [Section titled “Restoring”](#restoring) ```sh sudo homefellow backups restore # checked, then the household as it is now is backed up first sudo systemctl restart homefellow # the restore happens as the server starts sudo homefellow doctor # says what was restored sudo homefellow backups restore --cancel # call it off before the restart ``` A restore is done safely: 1. The backup is checked. It’s refused if it wouldn’t restore. 2. It’s copied into the data folder, so pruning old backups can’t lose it. 3. A fresh backup of the household as it is now is made, so the restore itself can be undone. 4. Nothing changes until the server next starts. 5. Then the household as it was moves aside to `before-restore-/` in the data folder. The backup takes its place. **What a restore doesn’t touch:** the settings, the home-network certificate and the speech model. **What it does undo:** devices that signed in after the backup was made, with invites made since. Those devices need a new invite. ## Moving to another computer [Section titled “Moving to another computer”](#moving-to-another-computer) Install Homefellow on the new computer, copy a backup there and restore it. Then give the family’s devices fresh invites, so they learn the new addresses. # The homefellow command > Every homefellow command, generated from the command's own help. `homefellow` is the household server and its command line, in one program. Every admin command runs on the server machine against its data folder. Add `--json` to any of them for JSON, which is what scripts and AI assistants should read. **Running it:** * **The packaged service:** `sudo homefellow COMMAND`. It runs as the `homefellow` user with `/etc/homefellow/server.toml`. * **Docker:** `docker compose -f packaging/docker/compose.yaml exec homefellow homefellow COMMAND`. * **Otherwise:** `homefellow COMMAND`, with the same `--data-dir` and `--config` as the server. Commands may run while the server runs: it takes up changed settings within a few seconds. Some settings need a restart. `homefellow status` lists them. **Exit codes:** 0 means it worked; 1 means it failed, or the doctor found a problem (the JSON says what); 2 means bad usage. **The most used:** | Command | What it does | | ------------------------------- | ------------------------------------------------------------- | | `homefellow setup-code` | the one-time setup code for the setup page | | `homefellow setup` | sets the household up, asking in the terminal or taking flags | | `homefellow setup --plan` | the setup steps and where each stands | | `homefellow doctor` | checks everything, in words, with fixes | | `homefellow models discover` | looks for AI model servers | | `homefellow models test` | tests the chosen models | | `homefellow access` | the household’s addresses | | `homefellow invite --name NAME` | an invite for someone | | `homefellow people` | who signs in and their devices | | `homefellow backups run` | makes a backup now | ## Every command [Section titled “Every command”](#every-command) This is the command’s own help, from `homefellow 0.1.0`: ```text usage: homefellow [serve] [OPTIONS] homefellow COMMAND [ARGS] [OPTIONS] [--json] homefellow --version commands (each also as `admin COMMAND`; add --json for JSON): serve run the server (the default) setup [--household NAME --owner NAME [--timezone ZONE]] [--models recommended|skip] [--lan on|off] [--anywhere on|off] [--tailscale] [--backups HH:MM|off] set the household up: asks in a terminal, or takes it all as flags; prints the owner's invite link setup --plan the setup steps and where each stands setup --later family leave inviting the household for later, so the plan stops asking setup-code the one-time setup code, for the /setup page and the admin API doctor [--no-probe] check everything, in words, with fixes (exit 1 when something fails) status the checks without asking the model servers or addresses version this server's version models [list] the models in use and the last test models discover [--host HOST]... [--url URL]... look for model servers here and on those hosts models choose --recommended [--host HOST]... [--url URL]... models choose --url URL --model NAME [--explorer-url URL --explorer-model NAME] [--api-key KEY] models choose --keeper-profile NAME [--explorer-profile NAME] use those models from now on models test read an invented note and choose a question with them voice [status] how voice answers are transcribed voice fetch download the speech model (148 MB) voice off | voice builtin [--model NAME] | voice endpoint --url URL [--model NAME] access [status] the household's addresses, home network and Tailscale access lan on|off [--port PORT] [--mdns on|off] HTTPS on the home network with this server's own certificate access tailscale publish it on your tailnet with `tailscale serve` access iroh on|off [--relay n0|off|URL] [--port PORT] reach it from anywhere over iroh, with nothing to install access firewall [--opened | --not-opened | --allow] whether the firewall lets the home-network ports through, and the command that does; --opened: you've opened them (when it can't check without root); --allow: run that command (as root) invite [--role member|owner] [--name NAME] [--user ID] an invite link (carrying every address); with --user, a link that signs in another device for that person (for a lost phone) people who signs in, and their devices people role ID owner|member change someone's role (the last owner stays an owner) invites [list] every invite: open, used, expired or revoked invites revoke ID withdraw an open invite revoke-device ID sign a device out backups [list] the backups, where they go and how many are kept backups run make a backup now backups check [NAME] check the newest (or NAME) would restore backups schedule HH:MM|off [--keep N] [--dir DIR] the server's own daily backup backups restore NAME restore a backup at the server's next start: it's checked, and the household as it is now is backed up first backups restore --cancel call off a restore that's waiting backup DIR copy the database into DIR (which must not exist yet); DIR then works as a data folder, to restore from fetch-speech-model [NAME] [--sha256 HEX] download a whisper.cpp model into /models and check it (default: the configured speech.model) service commands (one person's background service, no root): service install [--keep-awake] run this server at login and now (launchd on macOS, systemd --user on Linux, a logon task on Windows) service uninstall stop it and remove the service service start | stop start or stop it (stop keeps it from starting at login until start) service status whether it's installed and running options (a flag beats its environment variable, which beats the data folder's settings.toml, which beats the configuration file): --config FILE configuration file (default $HOMEFELLOW_CONFIG, else $XDG_CONFIG_HOME/homefellow/server.toml) --bind VALUE address to listen on (default 127.0.0.1:8787) [server.bind; HOMEFELLOW_SERVER_BIND] --data-dir VALUE database and media (default $XDG_DATA_HOME/homefellow; on macOS ~/Library/Application Support/Homefellow) [server.data_dir; HOMEFELLOW_SERVER_DATA_DIR] --public-url VALUE the address families use, for invite links (default http://) [server.public_url; HOMEFELLOW_SERVER_PUBLIC_URL] --join-url VALUE the page invite links open, which sends people to the app (default https://homefellow.org/join; off for links at the server's own address) [server.join_url; HOMEFELLOW_SERVER_JOIN_URL] --keeper-profile VALUE the keeper's model profile, a name or a .toml path (default glm-spark-keeper) [agents.keeper_profile; HOMEFELLOW_AGENTS_KEEPER_PROFILE] --explorer-profile VALUE the explorer's model profile (default glm-spark-quick) [agents.explorer_profile; HOMEFELLOW_AGENTS_EXPLORER_PROFILE] --profiles-dir VALUE where profiles live (default profiles) [agents.profiles_dir; HOMEFELLOW_AGENTS_PROFILES_DIR] --goose-bin VALUE the Goose binary, keeping the profile's pinned SHA-256 (default: the profile's) [agents.goose_bin; HOMEFELLOW_AGENTS_GOOSE_BIN] --speech-mode VALUE builtin (whisper.cpp), endpoint or off (default builtin) [speech.mode; HOMEFELLOW_SPEECH_MODE] --speech-model VALUE whisper model file, a name in /models or a path (default ggml-base.en.bin) [speech.model; HOMEFELLOW_SPEECH_MODEL] --speech-model-sha256 VALUEthe model's SHA-256 (known for the models fetch-speech-model offers) [speech.model_sha256; HOMEFELLOW_SPEECH_MODEL_SHA256] --speech-language VALUE spoken language code, or auto (default en) [speech.language; HOMEFELLOW_SPEECH_LANGUAGE] --speech-endpoint VALUE an OpenAI-compatible /audio/transcriptions URL, for mode endpoint [speech.endpoint; HOMEFELLOW_SPEECH_ENDPOINT] --speech-endpoint-model VALUEthe model name sent to the endpoint (default whisper-1) [speech.endpoint_model; HOMEFELLOW_SPEECH_ENDPOINT_MODEL] --invite-ttl-hours VALUE how long an invite link stays valid (default 72) [auth.invite_ttl_hours; HOMEFELLOW_AUTH_INVITE_TTL_HOURS] --lan VALUE on: also serve HTTPS on the home network with this server's own certificate (default off) [access.lan; HOMEFELLOW_ACCESS_LAN] --lan-port VALUE the home network's HTTPS port (default 8788) [access.lan_port; HOMEFELLOW_ACCESS_LAN_PORT] --mdns VALUE on: announce the server on the home network as _homefellow._tcp (default on, with access.lan) [access.mdns; HOMEFELLOW_ACCESS_MDNS] --iroh VALUE on: reach the household from anywhere over iroh, with no account or extra software (default off) [access.iroh; HOMEFELLOW_ACCESS_IROH] --iroh-port VALUE the UDP port iroh listens on, named in invites (default 8789) [access.iroh_port; HOMEFELLOW_ACCESS_IROH_PORT] --iroh-relay VALUE homefellow (Homefellow's relay, relay.homefellow.org), n0 (n0's public relays, for development), off, or a relay's https:// address (default homefellow) [access.iroh_relay; HOMEFELLOW_ACCESS_IROH_RELAY] --backups-dir VALUE where backups go (default /backups) [backups.dir; HOMEFELLOW_BACKUPS_DIR] --backups-keep VALUE how many backups to keep (default 14) [backups.keep; HOMEFELLOW_BACKUPS_KEEP] --backups-daily-at VALUE HH:MM on the household's clock for the server's daily backup, or off (default off) [backups.daily_at; HOMEFELLOW_BACKUPS_DAILY_AT] The agents' environment overrides (HOMEFELLOW_GOOSE_BIN, HOMEFELLOW_MODEL, HOMEFELLOW_HOST, HOMEFELLOW_TIMEOUT_SECONDS) apply too. Setting up: docs/SETUP_FOR_AGENTS.md. ``` # Installing > Installing Homefellow on Linux with the one-line installer, packages or Docker. On a Mac or Windows, with the desktop app. Not released yet Homefellow’s first release isn’t published, so `homefellow.org/install.sh` says there’s nothing to install yet and the downloads aren’t up. This page is exactly how installing will work once they are. The installer already works with a release you’ve built yourself (`--file`). ## On Linux [Section titled “On Linux”](#on-linux) Homefellow’s server runs on Linux on x86_64 and ARM64 machines. Its binaries need glibc 2.34 or later: Debian 12, Ubuntu 22.04, Fedora 36 and newer. There are three ways to install it. After any of them, set the household up in a browser at `http://:8787/setup` (see [Getting started](/start/getting-started/)), or with `sudo homefellow setup` in a terminal. ### The one-line installer [Section titled “The one-line installer”](#the-one-line-installer) ```sh curl -fsSL https://homefellow.org/install.sh | sh ``` What it does: 1. Finds the machine type and downloads the matching release from `https://releases.homefellow.org`. 2. Checks its signature with Homefellow’s release key, which is built into the installer, then its SHA-256. It refuses a release that doesn’t check. 3. Installs it as a system service, asking for `sudo`, then starts it. 4. Prints the setup page’s addresses and how to see the setup code (`sudo homefellow setup-code`). It checks the signature with `ssh-keygen` (OpenSSH 8.1 or newer), which is on almost every Linux machine. On a bare container without it: `sudo apt install openssh-client` (or `dnf install openssh-clients`). Without it, the installer says so and stops. What it sets up: | Path | Holds | | ----------------------------- | ------------------------------------------------------------ | | `/usr/lib/homefellow` | the server and the AI tools it uses | | `/etc/homefellow/server.toml` | the settings | | `/var/lib/homefellow` | the household’s data | | `/var/lib/homefellow/backups` | the server’s own daily backups, at 03:15, the newest 14 kept | | `/usr/bin/homefellow` | the `homefellow` command | **Options,** after `sh -s --`: | Option | What it does | | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--user` | installs for you only, without root, in `~/.local` and `~/.config`, as a systemd user service. Run `loginctl enable-linger $USER` to keep it running while you’re logged out | | `--listen local` | listens only on this computer (`127.0.0.1:8787`), for use behind Tailscale Serve or a reverse proxy. The default, `lan`, listens on the home network so your other devices can reach it | | `--version ` | installs a particular release | | `--no-speech-model` | skips the 148 MB speech model. Voice stays off until `homefellow voice fetch` | | `--file homefellow-….tar.gz` | installs a release you’ve already downloaded, with its release’s `SHA256SUMS` and `SHA256SUMS.sig` (or its own `.sig`) beside it | | `--file … --unsigned` | for a tarball you built yourself and nothing else: installs it without checking a signature | | `--uninstall` | removes Homefellow, keeping the household’s data, backups and settings. Add `--purge` to delete those too | ### A package (.deb or .rpm) [Section titled “A package (.deb or .rpm)”](#a-package-deb-or-rpm) For Debian, Ubuntu, Fedora, RHEL and openSUSE: ```sh sudo apt install ./homefellow__amd64.deb # or arm64 sudo dnf install ./homefellow--1.x86_64.rpm # or aarch64 ``` It installs the same files as the one-line installer. It starts the server, which makes its own daily backups into `/var/lib/homefellow/backups`. Fetch the speech model afterwards with `sudo homefellow voice fetch`. * **Upgrading:** install the newer package. * **Removing:** `apt remove` or `dnf remove`. The household’s data in `/var/lib/homefellow` is never deleted by the package, even by `apt purge`. ### Docker [Section titled “Docker”](#docker) For servers that already run everything in containers: ```sh docker compose -f packaging/docker/compose.yaml up -d docker compose -f packaging/docker/compose.yaml exec homefellow homefellow setup-code ``` * **The data** is in the `homefellow-data` volume. The speech model is fetched into it on the first start. * **The network:** the compose file uses the host’s network, so Homefellow sees this machine’s real name and addresses. The invites it makes then work on the family’s phones. It listens on 8787 (the setup page), 8788 (the home network, over HTTPS) and 8789/udp (reaching it from anywhere). * **The image** is built from a release (`packaging/build-release.sh`, then `packaging/docker/build-image.sh`). * **Settings** are environment variables: each setting in `server.toml` has one, such as `HOMEFELLOW_SERVER_BIND` for `server.bind`. * **Local AI models** usually run on the host (Ollama on 11434, LM Studio on 1234). With the host’s network they’re at `localhost`, where setup looks first. No GPU is needed in the container. * **Removing:** `docker compose down`, plus `-v` to delete the data volume too. ### The service [Section titled “The service”](#the-service) The packaged service runs as the `homefellow` user, can write only its data folder and restarts on failure. * `sudo systemctl status homefellow`: whether it’s running. * `journalctl -u homefellow -f`: its log. * `sudo homefellow COMMAND`: runs a `homefellow` command as the service’s user with its settings. ### The firewall [Section titled “The firewall”](#the-firewall) If the computer has a firewall on (ufw or firewalld), your phones can’t reach Homefellow at home until its ports are let through. The installer says so at the end. Nothing is changed for you: ```sh sudo ufw allow 8788/tcp comment 'Homefellow' # the home network, over HTTPS sudo ufw allow 8789/udp comment 'Homefellow' # direct connections from anywhere sudo homefellow access firewall # check again ``` See [reaching it from your devices](/reference/networking/). ## On a Mac or Windows [Section titled “On a Mac or Windows”](#on-a-mac-or-windows) On a Mac or a Windows computer, Homefellow is the desktop app. It’s a client to a household like the phone apps. It can also run the household itself on that computer. ### Installing the app [Section titled “Installing the app”](#installing-the-app) * **A Mac** (macOS 13 or later): open the DMG and drag Homefellow to Applications. * **Windows:** unzip `Homefellow--x86_64-windows.zip`, right-click `install.ps1` and choose Run with PowerShell. It installs for you, with a Start Menu shortcut and an entry in “Apps & features”. To join a household that runs elsewhere, paste your invite link on the app’s first screen. ### Running the household on this computer [Section titled “Running the household on this computer”](#running-the-household-on-this-computer) Choose **Run the household on this computer**, on the first screen or in Settings. The app: 1. downloads the household’s server, the “host pack” (about 85 MB) and checks it; 2. starts it as your own background service, with no administrator needed; 3. opens the setup page in your browser with the setup code already filled in; 4. signs this computer in as the household’s owner once setup is done. The app itself stays small: the server is separate. Closing the app’s window doesn’t stop the household. **Settings shows** “This computer runs the household”, with its state, Stop and Start, “Keep this computer awake while it’s plugged in”, Open the admin and Remove. **Where things live:** | What | Mac | Windows | | ---------------------- | ------------------------------------------ | ------------------------------ | | The household’s data | `~/Library/Application Support/Homefellow` | `%LOCALAPPDATA%\Homefellow` | | The background service | a launchd agent, started at login | a task started when you log in | **Sleep.** Your family’s phones can’t reach a computer that’s asleep. “Keep this computer awake while it’s plugged in” stops it sleeping on mains power only. **The firewall:** * **On a Mac,** the first time Homefellow listens on the home network, macOS asks “Allow incoming connections?”. Choose Allow. * **On Windows,** your home network must be set to Private: in Settings, then Network & Internet, open your network and choose Private. `homefellow access firewall` checks it. **By hand:** the host pack’s `homefellow service install` does what the app does. `service status`, `stop`, `start` and `uninstall` manage it. **Moving to another computer** later is a backup and a restore: see [backups and restoring](/reference/backups/). # The AI models > Which local AI models Homefellow works with, how setup finds and tests them, how to change them. Homefellow uses two AI models, which can be the same one: * **the reading model** reads each new thing the family shares (an answer, a note, a calendar change) and updates what Homefellow knows; * **the questions model** chooses the next question or lookup. Both run on the household’s own computers. Homefellow talks to them through [goose](https://goose-docs.ai/), which is bundled with the server and checked by its checksum. ## What works [Section titled “What works”](#what-works) * **A model server** with an OpenAI-compatible API: Ollama, LM Studio, llama.cpp’s server or vLLM, on the household’s computer or another one at home. * **A capable open model.** Homefellow is developed and tuned on GLM. In our testing so far, larger models read more reliably and small ones tend to miss things. * **A powerful computer made for AI**, or a large graphics card. Homefellow is aiming to run on smaller computers as models get better. The exact requirements (which models, how much memory and how fast) will be published with the first release, from what we’ve tested. ## How setup finds them [Section titled “How setup finds them”](#how-setup-finds-them) `homefellow models discover` (the setup page’s “AI models” step) looks for model servers on the usual ports: | Server | Port | Asks | | --------- | ----- | ------------ | | Ollama | 11434 | `/api/tags` | | LM Studio | 1234 | `/v1/models` | | llama.cpp | 8080 | `/v1/models` | | vLLM | 8000 | `/v1/models` | It looks on this computer, on any other computer you name (`--host 192.168.1.40`) and at any address you type (`--url http://gpu-box:8000/v1`), giving each 1.5 seconds. It leaves out embedding and speech models, then recommends a pair, with a verdict: * **good:** 30 billion parameters or more, or the GLM Homefellow is tuned on; * **maybe:** 14 to 30 billion; * **too small:** under 14 billion; * **unknown:** its size couldn’t be read; * **none:** no model server answered. ## Choosing [Section titled “Choosing”](#choosing) ```sh sudo homefellow models choose --recommended sudo homefellow models choose --url http://127.0.0.1:11434 --model qwen3:32b sudo homefellow models choose --url URL --model NAME --explorer-url URL2 --explorer-model NAME2 ``` A new choice takes effect at once, with no restart. The choice is written as profiles in the data folder’s `profiles/`, with the settings pointing at them. ## The test [Section titled “The test”](#the-test) ```sh sudo homefellow models test ``` It reads an invented note about a dog’s rabies booster and a passport into a throwaway household, then chooses one question. It makes real model calls, so it takes as long as one reading and one question: often a minute or two. | Verdict | Means | | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | good | both things were found and a question was chosen in good time | | slow | it works, but slowly | | too small | it answered, but missed things: try a larger model | | failed | a model didn’t answer (“Failed: the reading model didn’t answer”), with the address it tried: check its server is running there and the model is loaded. A model that answered but never with something Homefellow could use is failed too. The words say which | The result is kept. The doctor shows it. # Reaching it from your devices > The home network and its certificate, Tailscale, reaching home from anywhere, Homefellow's relay and running your own, the firewall. 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 [Section titled “The ports”](#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 [Section titled “The home network”](#the-home-network) ```sh 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://: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 [Section titled “Tailscale”](#tailscale) If the household’s computer already runs [Tailscale](https://tailscale.com): ```sh sudo homefellow access tailscale ``` It runs `tailscale serve`, which publishes Homefellow at `https://..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 [Section titled “From anywhere, with nothing to install”](#from-anywhere-with-nothing-to-install) ```sh 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](#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 [Section titled “Homefellow’s relay”](#homefellows-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](https://github.com/n0-computer/iroh) 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 [Section titled “Using another relay”](#using-another-relay) ```sh 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 [Section titled “Running your own 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@`. 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:///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 [Section titled “The firewall”](#the-firewall) Many Linux machines have a firewall on. It blocks the family’s phones at home until the ports are let through: ```sh 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. # Updates and releases > How to update Homefellow, what's kept, where releases live and how the installer checks they're really Homefellow's. ## Updating [Section titled “Updating”](#updating) **The one-line installer:** run it again. It downloads the newest release, checks its signature, installs it and restarts the server on the new version: ```sh curl -fsSL https://homefellow.org/install.sh | sh ``` **A package:** install the newer `.deb` or `.rpm`. **Docker:** pull or build the newer image, then `docker compose up -d` again. **The desktop app:** install the newer app; the household it runs is updated with it. **What’s kept:** the household’s data, its backups, the chosen models and the settings. If a new release changes the default settings, your `/etc/homefellow/server.toml` is kept and the new defaults are put beside it as `server.toml.new`. **The database** is upgraded automatically when the new version starts. It’s a good idea to make a backup first: `sudo homefellow backups run`. **The apps** and the server don’t have to be updated together, but keep them close: a much newer app may need a newer server. `sudo homefellow version` shows the version that’s running. ## Releases and signatures [Section titled “Releases and signatures”](#releases-and-signatures) Not released yet Nothing is published at `releases.homefellow.org` yet. This is how releases will be laid out and checked. Homefellow’s releases are published at `https://releases.homefellow.org`: ```plaintext releases.homefellow.org/ latest the latest version install.sh the one-line installer / homefellow--x86_64-linux.tar.gz .sig .sha256 homefellow--aarch64-linux.tar.gz .sig .sha256 homefellow__amd64.deb … .sig .sha256 homefellow-host--aarch64-macos.tar.gz … SHA256SUMS SHA256SUMS.sig ``` `homefellow.org/install.sh` serves the same installer, so the one-line install works from either address. ### Signatures [Section titled “Signatures”](#signatures) Every file is signed with Homefellow’s release key, as an SSH signature (`ssh-keygen -Y sign`, in the namespace `homefellow-release`). Checking one needs only `ssh-keygen`, which comes with OpenSSH on almost every Linux computer and Mac. The key, in SSH’s allowed-signers form: ```plaintext release@homefellow.org namespaces="homefellow-release" ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIC6g0I19tJIxxVqDn6B2hJspd9TyjWm7AU8xHQYC2pad ``` The same line is built into the one-line installer, which refuses any release whose signature doesn’t check. The file names carry the version. `SHA256SUMS` lists them all and is signed too. So the installer checks a download against that signed list, which ties each file to its release. ### Checking a release by hand [Section titled “Checking a release by hand”](#checking-a-release-by-hand) Save the key line above as `allowed_signers`, then: ```sh v=$(curl -fsSL https://releases.homefellow.org/latest) curl -fsSLO https://releases.homefellow.org/$v/SHA256SUMS curl -fsSLO https://releases.homefellow.org/$v/SHA256SUMS.sig ssh-keygen -Y verify -f allowed_signers -I release@homefellow.org -n homefellow-release \ -s SHA256SUMS.sig < SHA256SUMS sha256sum --check --ignore-missing SHA256SUMS ``` How releases are cut, signed and published is `docs/RELEASES.md` in Homefellow’s source. # The apps and the kitchen frame > Homefellow on iPhone, Android, a Mac, Windows and Linux: how each device joins. Plus a kitchen frame on the wall. Each person installs the Homefellow app first, then joins the household with their own invite. An invite is a QR code or a link from an owner. It carries the household’s addresses, so the app can reach home both at home and away. An invite’s link looks like `https://homefellow.org/join#hf1.…`. Opened on a phone without the app, it shows a page that says where to get the app, with a button to copy the invite. Once the app is installed, opening the link opens the app straight away. The part after the `#` is the invite itself. Browsers never send it to a website, so it stays on the phone. ## iPhone [Section titled “iPhone”](#iphone) The iPhone app needs iOS 26.1 or later. Once it’s installed: 1. Open the invite’s link, or scan the invite’s QR code in the app, or paste the link. 2. Give your name if the invite doesn’t have it. 3. You’re in. Today opens with what needs you. On your home network the app also finds the household by itself (“On this network”). It still needs the invite’s code to join. ## Android [Section titled “Android”](#android) The Android app works on phones and tablets. It scans the invite’s QR code with Google’s code scanner where the device has Google services. Otherwise, paste the link. A tablet or a digital frame can become the kitchen frame (below). ## A Mac, Windows or Linux computer [Section titled “A Mac, Windows or Linux computer”](#a-mac-windows-or-linux-computer) The desktop app joins with the invite link: paste it on its first screen. On a Mac or a Windows computer it can also [run the household itself](/reference/install/#on-a-mac-or-windows). ## In a browser [Section titled “In a browser”](#in-a-browser) At home, Homefellow is for the apps. The home network carries only encrypted connections. The apps check the household’s own certificate against the invite, so they connect without a warning. A browser can’t check it that way, so it warns on the home network’s encrypted address. Owners still reach the setup page and the admin in a browser (see [getting started](/start/getting-started/)). If you use Tailscale, the household’s Tailscale address works in any browser with no warning, at home or away. ## The kitchen frame [Section titled “The kitchen frame”](#the-kitchen-frame) A tablet or a digital picture frame on the kitchen wall shows the household’s day as everyone passes: the scene at the time of day, what needs you, today and tomorrow, then the week at a glance. It’s the Android app in kitchen-screen mode. To set one up: 1. Make an invite for the frame, in the app’s Settings or on the household’s computer. 2. Install the Android app on the frame and join with that invite. 3. In the app’s Settings, turn on the kitchen screen for this device. The frame then fills the screen in landscape, stays on and dims itself at night. Its colours follow the day, from morning light to dark paper at night. * **It shows** what needs you, today, tomorrow and the week. * **You can tap** to open a need, mark it Done or browse the week. * **It doesn’t ask.** There are no questions, no lookups and no “Tell Homefellow something” on the frame. Questions belong on people’s own phones, where they can answer when it suits them. * **It doesn’t listen.** Most frames have no microphone, so the frame has no voice. Many digital frames run older versions of Android or have no Google services. If yours can’t scan a QR code, paste the invite link instead. ## How a device reaches home [Section titled “How a device reaches home”](#how-a-device-reaches-home) The apps try the household’s addresses all at once and use the best one that answers: 1. **On Tailscale,** if you use it. 2. **At home,** over the home network, using the server’s own certificate, which the invite lets the app check. 3. **From anywhere,** through Homefellow’s relay, encrypted from end to end. It goes direct whenever your networks allow and through the relay when they don’t. Settings in each app shows which way it’s reaching home (“How this phone reaches the household”). See [reaching it from your devices](/reference/networking/) for the details.