Installing

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

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://<this computer>:8787/setup (see Getting started), or with sudo homefellow setup in a terminal.

The one-line installer

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 <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)

For Debian, Ubuntu, Fedora, RHEL and openSUSE:

sudo apt install ./homefellow_<version>_amd64.deb      # or arm64
sudo dnf install ./homefellow-<version>-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

For servers that already run everything in containers:

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

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

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:

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.

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

• A Mac (macOS 13 or later): open the DMG and drag Homefellow to Applications.
• Windows: unzip Homefellow-<version>-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

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.