Skip to content

famstack 0.5.0-beta.1

Pre-release
Pre-release

Choose a tag to compare

@arthware-dev arthware-dev released this 13 Nov 15:13
· 59 commits to main since this release
24a9194
famstack-0 5 0-beta 1

Warning

If you want to stay on 0.4, don't update. ./stack update on 0.4.x offers this beta and asks first: answer n. On 0.4.3 or older, run ./stack update v0.4.4 to get the last 0.4 fixes.

Tip

New users should start with 0.5. A plain git clone gives main, which is still 0.4.4, so clone the beta's tag:

git clone --branch v0.5.0-beta.1 https://github.com/famstack-dev/famstack.git && cd famstack
./stack

Why a beta? We have a lot of new features in the pipeline to make famstack easier to install, more fun to use and more secure. Some of them are not fully ready yet and need polishing. The last test runs did not cover an English instance, an iPhone, a Mac with more than 16 GB, domain mode, the backup stacklet and an AI server other than oMLX, so tell us what you find there.

Highlights

An easier install. ./stack now ends in a setup page in your browser. It walks you through the family, the chat on your phone, the AI, Photos and Documents, up to the first letter you file. For the AI there are two ways. famstack installs oMLX for you with one command in the terminal, which I recommend, because famstack is tested and tuned with it. Or you connect your own server, anything that speaks the OpenAI API, like Ollama, LM Studio or the oMLX app. The setup says your AI is ready only after it answered a first question.

Paired devices. Today Homer can see Marge's plans for Homer's birthday party. That should not happen in a family. From this release, a phone or a browser opens the dashboard, the card pages and the wiki only after you paired it with a QR code from the Mac, and each person gets a first password of four words. It is the foundation for proper visibility rules in your household.

Memory as the core of famstack. Everything the family files ends up in the memory, so I started to rework it. Every card now has its own beautiful page and a link that never changes. This will be the place to correct things, with a beautiful UI soon. The archivist links the page in its answers, and it opens on any paired device in the house. A note keeps your own words, quoted below a clean version. You can correct every card consistently by replying in its thread, or later in the UI, which can be more convenient at times, for example for lists. The memory also gets a nightly backup.

Better German, and language handling in general. famstack talks to you in the stack's language. On a German stack, the bots welcome you, answer and explain a failed filing in German.

New voices through oMLX. Speech runs through oMLX now, with a natural German voice (Qwen3-TTS) and Kokoro for English. famstack reads a text in the voice of its own language and reads markdown as plain speech.

Better support for 16 GB Macs. famstack gives its own oMLX a fixed 9 GB memory limit, reads long prompts in chunks and unloads the model after 10 idle minutes. The default model now loads and reads long documents on a 16 GB Mac. If you run your own oMLX, the setup shows these settings as a recommendation and changes nothing.

Also new: Stacky sets reminders with ./stack core schedule, and ./stack extensions add installs an extension. Stacky, the backup stacklet and the infra stacklet stay beta. If something breaks, tell me: open an issue or join our Discord.

How it was tested: a fabricated family on a 16 GB MacBook Air M4 with macOS 15.5, Qwen3.5-9B and oMLX 0.8.0rc1 from Homebrew, set up in German with an Android phone: the automated tests (7,044 unit tests, and the end-to-end tests with the real model: 42 plus 13 with a stand-in), a new install from the first page to the first filed letter, and an update from 0.4.4 that kept the AI's key and settings. And we run 0.5.x at home too, as early adopters :)

Upgrading from 0.4.4

Take a backup first, because this is a beta and the way back to 0.4 was not tested. Run ./stack down all, copy your data folder (data_dir in stack.toml) and stack.toml, users.toml and .stack/, then run ./stack up all. The admin guide has more on backups and updating, and the guide Backup strategy for a self-hosted Mac home server helps you choose where the copy goes.

./stack update v0.5.0-beta.1
./stack restart
./stack doctor
./stack memory check-format

Pair your admin device

The dashboard, the card pages and the wiki now open only on a paired device. ./stack restart ends with a QR code: scan it with your phone to pair it. It waits up to 10 minutes for the scan; press Ctrl-C to pair later. Pair the others with ./stack devices pair <person>, or on the Mac in Setup, Add a phone. Open the Mac's pages from the menu bar app or with ./stack devices admin-link. If you use the menu bar app, run ./stack app install again. The admin guide explains how a device gets paired and the admin key.

Change the first passwords

Change each person's password in Element, Immich, Paperless and Forgejo, because on 0.4.4 every person's first password is their first name.

What the restart does

The bots wait during the restart while twelve migrations run once each: about 2 minutes on the test Mac. They answer what was sent in that time afterwards. If a migration fails, the bots stay on hold: fix the cause, then run ./stack up <id>. The restart also:

  • moves Immich to the newest 3.x, a minor update that most installs already have through Watchtower,
  • restarts the famstack API on the Mac, because its code changed,
  • downloads the speech model of the house language (up to 1.9 GB),
  • removes the old speech container stack-ai-speech and its image (about 1 GB),
  • moves famstack's oMLX into its own folder, ~/famstack-data/ai/omlx, under its own LaunchAgent. It stops the old Homebrew service once and keeps your API key. The models in ~/.omlx/models stay shared, and the oMLX app's own ~/.omlx settings stay as they are,
  • on a Mac with 16 GB or less, gives famstack's oMLX a fixed 9 GB memory limit, reads prompts in chunks and unloads the model after 10 idle minutes. Speech stays on; ./stack doctor says what it costs,
  • ends the AI's start with one short question to the AI, and says so when it does not answer,
  • moves the chat port 42031 in front of Synapse, so Element X on Android signs in at once. The port number stays the same.

Only if

Only if Then
The oMLX app runs on this Mac and famstack runs its own oMLX Quit the app from its menu bar before ./stack restart. famstack's oMLX does not start while the app runs, because two MLX servers on one Mac share its graphics memory
You use the oMLX app as your own server, and an older famstack moved it to port 42060 Set its port back to 8000 in the app's settings. famstack no longer shares the app's settings
famstack's oMLX is older than 0.5.0 Run brew upgrade omlx, then ./stack restart ai. I recommend the latest stable oMLX release
Your speech server is not an oMLX Set [ai] speech_url and [ai.voices], because otherwise the stack does not speak
You call ./stack ai say --voice with a Piper voice (alloy, echo, fable, nova, onyx, shimmer) Name it in [ai.voices]
An extension bot calls _should_react or overrides _room_mode_allows_react Remove the await, route with await self._message_context(room), and make the override a plain method
An extension bot has from microbot import MicroBot Change it to from stack.bot import MicroBot. The old import loads until 0.6
ChatAI no longer reads answers aloud In Open WebUI, open Admin Panel > Settings > Audio and set the Text-to-Speech Engine to Web API, because the speech container is gone
You use the backup stacklet Run ./stack up backup after any ./stack down all, because down all removes its nightly cron entry
A script runs ./stack up, down, restart or destroy famstack runs one of them at a time. A run of another stacklet waits its turn and says for which run. Exit code 75 means the same stacklet is still running: nothing changed, wait and try again
What the twelve migrations do

Each one that changes something is one commit in the memory's repository, by the memory bot. None calls the model.

Migration What it does
docs/0001 Moves photos filed as bookmarks to notes
memory/0001 Moves a topic's todos.md to a list
memory/0002 Gives every card a card_id
memory/0003 Names people on records by id, links their person files, removes Person: tags
memory/0004 Gives correspondents and topics a card of their own
memory/0005 Tags topics by the ontology's id
memory/0006 Adds kind: archive to list archives, renames a diary card's medium to kind
memory/0007 Names the people of diary cards by id
memory/0008 Moves a note's sources into ## Sources and its machine fields into a <name>.json file beside it
memory/0009 Gives a correspondent written by hand its title
memory/0010 Tags diary cards by topic id
memory/0011 Brings cards from before 0.3.0-beta.2 and older emails into the format

A diary card that a person changed stays as it is, and the output lists it. memory/0011 removes a name that matches no person file from a card's persons, and the name stays in the card's text.

Known limits

  • 16 GB Macs: the whole stack fits, but tightly. A long document such as a contract takes one to four minutes, and a new install turns speech off.
  • Private notes: a note filed from a private chat stays off other people's pages, but any paired device opens it by its link, and the dashboard's Activity list shows its title.
  • oMLX app: quit it before famstack installs its own oMLX, because two AI servers on one Mac share its graphics memory. Or connect the app as your own server.
  • Backups: Forgejo as a whole and the databases of Immich and Paperless are not in the backup yet.
Everything that changed (119 entries)

Security

  • Core Stacklet: Open the dashboard, the card pages and the wiki only on a paired phone or browser, with ./stack devices (#438)
  • Core Stacklet: Give the Mac's pages at http://127.0.0.1:42002 the admin's rights only with the admin key (#438)
  • Core Stacklet: Give each caller of the famstack API its own token, and the agent its own chat password (#438)
  • Core Stacklet: Give each new person a first password of four words, shown only on their paired phone and the Mac (#438)
  • Core Stacklet: Keep the agent from sending messages as a person with --as (#275)
  • AI Stacklet: Replace the placeholder key of the oMLX the stack manages with ./stack ai key new (#438)

Added

  • Core Stacklet: Add a setup page that walks through the family, the phone's chat, the AI, Photos and Documents (#335, #436, #445, #453)
  • Core Stacklet: Show the stack on the dashboard, and follow each start of a stacklet wherever it was started (#335, #436)
  • Core Stacklet: Give every card a page and a link that never changes, /go/card/<card id> (#437)
  • Core Stacklet: Browse the memory's cards at http://127.0.0.1:42002/cards, on the Mac only (#257, #281)
  • Core Stacklet: Show the memory's activity on the dashboard (#296, #300, #315)
  • Core Stacklet: Open notes and diary cards by card id wherever they move (#227, fixes #222)
  • Core Stacklet: Add ./stack core schedule to run stack commands at a time (#261)
  • Core Stacklet: Let the agent set reminders with the scheduler (#323, #417)
  • Core Stacklet: Add ./stack core firewall to say whether macOS's firewall keeps phones from the chat (#436)
  • Core Stacklet: Sign each bot's device with its own cross-signing keys (#260)
  • Core Stacklet: Add ./stack core web fetch to show how the stack reads a page (#368)
  • AI Stacklet: Set up the AI on the setup page or the first ./stack up ai: famstack's oMLX, or your own server (#436, #440, #456)
  • AI Stacklet: Run famstack's oMLX in ~/famstack-data/ai/omlx, apart from the oMLX app's settings (#456)
  • AI Stacklet: Ask the AI server one short question with ./stack ai check, and say ready only after it answered (#457)
  • AI Stacklet: Show the settings recommended for this Mac with ./stack ai recommended show (#436, #456)
  • AI Stacklet: Speak through oMLX: Kokoro for English, Qwen3-TTS for German (#336, #340, fixes #246)
  • AI Stacklet: Speak a text in the voice of its own language, or with ai say --language (#253, fixes #242)
  • AI Stacklet: Read markdown aloud as plain speech (#253, fixes #243)
  • AI Stacklet: Speak sentence by sentence, and add ai say --no-wait (#258, fixes #240)
  • AI Stacklet: Set the volume and the speech server with ai say --volume and [ai] speech_url (#253)
  • AI Stacklet: Keep the audio of repeated phrases with ai say --keep and --prepare (#382)
  • AI Stacklet: Turn speech on or off with [ai] speech (#436, #439)
  • Agent Stacklet: Let an extension stacklet answer as the agent with [agent] runtime (#332)
  • Archivist Bot: File a typed or spoken note as a clean version of its words, with the words quoted (#286, #290, #298)
  • Archivist Bot: Answer a filing with a short card that links to its page (#401, #403, #437)
  • Archivist Bot: Keep an email's sender on its card (#437)
  • Archivist Bot: Lead a bookmark's summary with why it was kept (#286)
  • Memory Stacklet: Keep filings made while Forgejo is down, and name them in ./stack memory pull (#325)
  • Memory Stacklet: Back up the memory's repository each night, in a git bundle on the backup disk (#357)
  • Memory Stacklet: Add find, card and links to read the memory as cards (#254)
  • Memory Stacklet: Give every card an id of its own, and open any card at /go/<card_id> (#270)
  • Memory Stacklet: Show each card type in one layout in the chat, the card pages and ./stack memory card (#280)
  • Memory Stacklet: Add ./stack memory card edit to change a card's fields, checked against its schema (#295)
  • Memory Stacklet: Compile the wiki views of a changed card within seconds, without the model (#277)
  • Memory Stacklet: Keep a note's sources and how it was made in a .json file beside its card (#290, #304)
  • Memory Stacklet: Add ./stack memory reprocess to preview and refile one note (#290)
  • Memory Stacklet: Keep a person's hand edits through a refile, also after a move (#303, #315, #317)
  • Memory Stacklet: File a note from ./stack memory write as the chat files it (#316)
  • Memory Stacklet: Treat a household's own topics as topics in tags, search and the graph (#319)
  • Memory Stacklet: Add ./stack memory topic rename to give a topic a new id (#371)
  • Memory Stacklet: Show who sent each source of a card in the wiki, and when (#408)
  • Memory Stacklet: Name people on a diary card, as "Bart or Lisa" when the words do not say who (#286)
  • Memory Stacklet: File a diary entry under 400 characters without a summary (#286)
  • Memory Stacklet: Preview the newest diary cards with ./stack memory diary --preview (#302)
  • Messages Stacklet: Encrypt a message sent into an encrypted room (#275)
  • Messages Stacklet: Send to a person's private chat with --to (#275)
  • Messages Stacklet: Send as the agent or a bot with --as (#275)
  • Messages Stacklet: Add --html and --mention-nobody to ./stack messages send (#403)
  • Photos Stacklet: Add an incubating Immich account for the stack itself with [photos] stack_account (#376)
  • stack CLI: Run stacklet migrations once, in order, and hold the bots until they have run (#231, #299, fixes #220)
  • stack CLI: Ask setup questions as forms, and answer them with ./stack configure and --answer (#339)
  • stack CLI: Install extensions with ./stack extensions add, from the catalog or any git repo (#344)
  • stack CLI: Let an extension's command do its work in the bot runner (#367)
  • stack CLI: Show a stacklet without containers as running in ./stack list, and restart it when stale (#337)
  • stack CLI: Keep each stacklet's last run as a log in .stack/runs/ (#436)

Fixed

  • stack CLI: Keep the stack's secrets when .stack/secrets.toml cannot be read, instead of overwriting them (#438)
  • stack CLI: Run one up, down, restart or destroy at a time; a second run of one stacklet exits with code 75 (#436, #454)
  • stack CLI: Offer a pre-release only to an instance already on one, from this release on (#343)
  • stack CLI: Show what a quiet stacklet command returned (#330)
  • stack CLI: Load a command or a bot that uses @dataclass (#290, #292)
  • Messages Stacklet: Let Element X on Android sign in at once, without minutes of waiting (#451)
  • Messages Stacklet: Keep each person's chat password and devices when the chat setup runs again (#438)
  • Messages Stacklet: Post the bots' welcomes, notices and answers in the stack's language (#445, #447)
  • Messages Stacklet: Encrypt a file that ./stack messages upload sends into an encrypted room (#388, fixes #387)
  • Messages Stacklet: Refuse a send when the server cannot say whether the room is encrypted (#388)
  • Messages Stacklet: Let family members find every account in chat search (#331)
  • Core Stacklet: Restart the famstack API on the Mac when an update changed its code (#438)
  • Core Stacklet: Restart the bots after a ./stack up only when core's settings changed (#436)
  • Core Stacklet: Encrypt a bot's file sent into an encrypted room (#388, fixes #387)
  • Core Stacklet: Answer a voice message when whisper misspells the bot's name (#329, #338)
  • Core Stacklet: Answer the first message in a room a bot just joined (#251)
  • Core Stacklet: Stop the bots at once on shutdown (#272)
  • Stacker Bot: Send the backup's first start from the Server room to the Mac's terminal, as the AI's (#436)
  • AI Stacklet: Fit the default model on a 16 GB Mac: a fixed 9 GB limit for famstack's oMLX, prompts read in chunks (#434, #436)
  • AI Stacklet: Stop installing the Piper speech container (about 1 GB). ChatAI reads answers aloud with the browser's voice (#428)
  • AI Stacklet: Pass the models named in [ai.models] to the bots (#258)
  • AI Stacklet: Say clock times the way people say them (#258)
  • AI Stacklet: Report a prompt over the model's limit as too long, with both sizes in the log (#396, #410, fixes #342)
  • Agent Stacklet: Sign in to chat after the first ./stack up agent, with no restart by hand (#409, fixes #173)
  • Archivist Bot: Give the reason a filing failed in the stack's language (#450)
  • Archivist Bot: Write a correction of an email to its card, and change only what the correction names (#402)
  • Archivist Bot: Answer "Not filed" with the reason when the memory refuses a capture (#402)
  • Archivist Bot: Read a correction in an encrypted room (#404)
  • Archivist Bot: Confirm a filed email in its thread, with no second message in the room (#400)
  • Archivist Bot: Keep a note's own words when a reply corrects it (#286)
  • Archivist Bot: Commit a chat correction as the person who replied (#303)
  • Archivist Bot: Wait up to 900 s for the model to classify a large scan (#399)
  • Memory Stacklet: Link people and correspondents to pages that open (#315, fixes #230)
  • Memory Stacklet: Write only tags that Obsidian accepts: a topic id or a lowercase keyword (#284, #315, fixes #228)
  • Memory Stacklet: Rebuild a diary card only when its entry changed, or with diary --rebuild (#302)
  • Memory Stacklet: Stop writing cards on a ./stack memory diary --limit run (#302)
  • Memory Stacklet: Name the bot as committer and the person as author on every memory commit (#297, #300, #302, #315)
  • Memory Stacklet: Ask for a wiki page again when the model's answer repeats itself (#377, fixes #374)
  • Memory Stacklet: Show a bookmark's link on its wiki page and in the archivist's reply (#405)
  • Memory Stacklet: Make every person's pages reachable from the wiki's sidebar (#406)
  • Memory Stacklet: Keep a person's notes off the home page and other people's pages in the wiki (#422)
  • Memory Stacklet: Rebuild a topic's page when an email is filed into it (#399)
  • Memory Stacklet: Count the day in the household's time zone in the wiki, lists, search and diary (#354)
  • Memory Stacklet: Find a list by its title, and a calendar entry as show prints it (#255)
  • Memory Stacklet: Say how to start a list when an item has none (#324)
  • Memory Stacklet: Read flow lists such as tags: [a, b] in a card's frontmatter as lists (#234)
  • Photos Stacklet: Make the album commands see an album's photos on Immich 3 (#415)
  • Photos Stacklet: Close the Immich session the login sync opens (#380)

Performance

  • Memory Stacklet: Ask the model only for a wiki page whose request changed: 1 call on a quiet night, was 10 (#356)
  • Memory Stacklet: Reuse the model server's cache on a home page rebuild: 13.4 s, was 75.7 s on 300 filings (#355)
  • Memory Stacklet: Read all cards in one batch at night: about 3 s, was 9 to 10 s on 500 filings (#354)
  • stack CLI: Start a stack command in a quarter less time: a list read takes 0.25 s, was 0.33 s (#250)

Documentation

  • stack CLI: Describe the install as a Mac user meets it in the admin guide (#436)
  • Memory Stacklet: Describe the memory format in docs/memory-format.md, readable without famstack (#304)
  • Memory Stacklet: Describe renaming a topic in the admin guide (#371)
  • Agent Stacklet: Say that a runtime switch gives the agent a device that cannot read older messages (#390)
  • stack CLI: Describe extensions in the admin guide, and reserve ports 42100 to 42199 for them (#344, #368)
  • Record the memory's and the stack's design in ADR-015 to ADR-022 (#229, #256, #265, #276, #288, #315, #328, #339, #344)