Getting started

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?

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.

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.

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. Homefellow needs a model of about 30 billion parameters or more to read reliably. Smaller computers will manage as models get better.
Linux, a Mac or Windows. Linux is the best tested.

Setting it up

It takes about fifteen minutes, most of it the AI test.

Install Homefellow on the household’s computer. Open a terminal on it and run:
Terminal window
```
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.
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.
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.
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.
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.
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.
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.
Invite your family. First, each person installs the Homefellow app on their phone or computer (see the apps and the kitchen frame). 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.
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.
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.

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.
Answer the first questions. Homefellow learns your household a few questions at a time: using it 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.

Prefer a terminal, or your AI assistant?Every setup step is also a homefellow command. Your AI assistant can walk you through it.

Free and open source. For families of every shape.homefellow.org Privacy For AI assistants