Support

Questions, bugs and feature requests: open an issue on GitHub.

Getting started

Family Agent needs one machine at home to act as the server. Install the desktop app there; it runs the server for you as long as it is open (or in the tray).

1. Install Ollama on that machine and pull a model that supports tool calling. Without tool calling the assistant can talk but cannot actually do anything — that is a property of the model, not of this app.
2. Install the desktop app and open it. On first run it asks you to create the owner account and name your home.
3. Add an account for each person in Family. Everyone's documents, tasks and chats stay separate.
4. On a phone, open the app on the same Wi-Fi. It should find the server by itself; if not, enter the address shown in the desktop app's Settings.

A phone can't find the server

Usually one of these:

• Different networks. Guest Wi-Fi and the main network are often separate. Put both devices on the same one.
• Client isolation. Some routers stop devices talking to each other. Look for "AP isolation" or "client isolation" and turn it off.
• The desktop app is closed. Closing the window keeps it running in the tray, but Quit stops the server for everyone.
• Local network permission. On iOS, check Settings → Family Agent → Local Network is on.

If discovery still fails, the address is in the desktop app under Settings → Advanced, and every client accepts a typed address.

The assistant replies but never does anything

Almost always the model. It has to support tool calling in Ollama's serving layer, and not every model does. The repository's decision log lists the ones that have been tried and what happened.

Replies are very slow

A full planner turn can take a couple of minutes on modest hardware, because everything is running locally. A smaller model is faster and less reliable at choosing tools; a larger one is the reverse. This is the trade-off you own by running your own inference.

I've forgotten the admin password

From the repository on the server machine, ./scripts/show-accounts.sh lists the accounts and ./scripts/reset-password.sh <username> resets one. If the password vault was set up, the account holder unlocks it afterwards with the recovery code issued at setup.

Where are the downloads?

On the releases page — pick the file for your machine:

• macOS (Apple Silicon): the .dmg — drag Family Agent to Applications and open it.
• Windows (x64 or Arm): the -setup.exe — run it and follow the installer.
• Linux (amd64 or arm64): the .deb on Debian/Ubuntu, or the .AppImage anywhere else (make it executable and run it).

After that the app updates itself — it checks on launch and from Settings → Updates, and always asks before installing.

macOS says the app can't be opened

Released builds are signed with an Apple Developer ID and notarized by Apple, so this shouldn't happen. If it does, you're most likely running a build you compiled yourself — those aren't signed by Apple. Right-click the app, choose Open, and confirm; once per build.

Windows says the app is from an unknown publisher

Windows builds aren't code-signed with a paid certificate yet, so SmartScreen shows this once per version. Click More info, then Run anyway. This is a first-run prompt, not a sign anything is wrong with the download.

Reporting something

GitHub issues is the place. Useful things to include: which app, what you expected, what happened, and anything from the desktop app's Activity screen around the time it went wrong. Please don't paste vault contents or document text you would not want public.