The setup guide for agents

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 and the 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

• 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

0. Check where things stand

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

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.

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:

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 <token>). Treat it as a password.

2. The AI models

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.

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.

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)

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

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://<computer>: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:

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

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

homefellow invite --name "Jordan" --json             # a member
homefellow invite --name "Sam" --role owner --json   # another owner
homefellow invite --user <id> --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.

homefellow invites --json                   # every invite: open, used, expired or revoked
homefellow invites revoke <id> --json       # withdraw one sent to the wrong person
homefellow people role <id> owner --json    # or member; the household always keeps an owner
homefellow setup --later family --json      # if the person will invite everyone later

7. Backups

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:

homefellow backups restore <name> --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-<time>/ 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

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

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.