Skip to content
Homefellow
Homefellow is being built. This is how it will work.Hear when it's ready

The homefellow command

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”

This is the command’s own help, from homefellow 0.1.0:

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 <data_dir>/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://<bind>)
                               [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 <data_dir>/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 <data_dir>/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.

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