← Build Log
Releases · Part 1

famstack 0.2.1 is out

First tagged release. Photos, documents in chat, local AI on a Mac. It works on my machine, hopefully on yours too.

So I tagged 0.2.1 today. Back in the day we would have called this Beta. It took me way longer than I expected. But here we are.

#TL;DR

What you get today:

Requirements: macOS on Apple Silicon (M1+), OrbStack or Docker Desktop, Homebrew. AGPLv3.

Install:

git clone https://github.com/famstack-dev/famstack.git
cd famstack
./stack

If you want to see what that actually looks like before you run it on your own machine, I recorded the whole install on my Mac:

famstack 0.2.1 install walkthrough on YouTube

Watch the install on YouTube. 20 minutes, clone to working family chat.

If you want more of these as they go up, subscribe on YouTube. The channel is new, so each sub punches above its weight.

The rest of this post is the longer version.

famstack is a batteries-included stack on top of established open source projects (Immich, Paperless, Matrix, MLX). The glue is the point: everything is wired together and accessible through instant messaging, so your family actually uses it instead of just you.

Documents, paperwork, photos from different devices, capturing and conserving memories. These are the things every family has to deal with. That is what famstack focuses on first.

But there is more. Families are like small businesses. They deserve the same infrastructure. We have similar requirements and have to deal with all of it on our own. Someone is the CEO and someone takes the role of IT operations and helpdesk. Typically the parents. This is for you. Stacklet by stacklet.

The vision: turn your Mac into the brain of your household and operate it from your phone. 0.2.1 is the foundation. I am currently experimenting with how to extract knowledge, data and memories out of the “sensor” data the stack produces (document filed, photo uploaded, etc) and combine it into an Obsidian-style family wiki: the memory brain.

It works on my machine. It works on two other Macs I tested it on. If it doesn’t work on yours: shame on me, please come to the Discord and tell me what broke. I want this to actually run for people who are not me.

If you have not set your Mac up as a server before, Set Up Your Mac as a Home Server covers the prep work famstack assumes (sleep settings, OrbStack, the basics). Bought a Mac Mini and not sure what to do with it? Start with You Bought a Mac Mini. Now What? and the power draw guide so you know what you signed up for. The short version: 12 watts on average. Cheaper than my Sonos.

git clone https://github.com/famstack-dev/famstack.git
cd famstack
./stack

Twenty minutes later you have a private family chat running on your Mac (Matrix + Element X), with three rooms set up for you: Family Room, Memories, and a Server Room where you operate the stack from your phone. From there you turn on what you actually want:

stack up docs        # Paperless-ngx + the archivist bot
stack up photos      # Immich
stack up ai          # oMLX, Whisper, TTS, native on your Mac

Each one runs its own first-time setup, you wait a bit while images pull, and you are running.

#The archivist is the part I am proud of

I will explain by example. A letter arrives. I take a photo of it with my phone. I send the photo into the Documents room in our chat. Fifteen seconds later the bot replies: title, category, who it is from, type, and a link. The letter’s content is classified (financial, receipt, etc), persons, correspondents, facts and tags are extracted and formatted as clean markdown. The foundation for the memory brain.

A few real examples from our own archive:

What is happening behind the scenes is that the photo gets uploaded to Paperless-ngx, Paperless does the OCR, the OCR text gets handed to the local LLM running on Metal (oMLX, never leaves the Mac), and the LLM returns structured fields: title, category, date, person, type, correspondent. Tags get created if missing, the raw OCR gets reformatted into clean Markdown, and then the bot writes back into chat.

One thing I had to fight to get right was the tag taxonomy. Without help, an LLM happily produces “Insurance”, “insurance”, “Versicherung”, “INS” and “Health Ins” as five different tags for the same kind of document. So on first start, Paperless gets seeded with a fixed list of tags and types in your language, and the LLM has to pick from that list. Six months later your archive still makes sense.

The archivist also does some things that I needed for my own family and probably you do too:

If you ever tried to convince a non-technical family member to scan a doc, save it as PDF, name it sensibly and drop it in the right folder, you know exactly why this matters more than the underlying tech.

#Photos

The photos stacklet is just Immich with everything wired up. I did not build Immich. The Immich team did, and they are doing a great job. What famstack adds is that you don’t have to think about Postgres, Redis, the reverse proxy, the data directory, or where the .env files live. One command, you get a URL, you put that URL into the Immich app on your phone, photos start syncing in the background.

./stack up photos

Each family member gets their own account and their own library, with shared albums for the family stuff. Face recognition, maps, memories all run locally on the Mac.

For the deeper how-it-works: I wrote up the Immich Mac setup and the family sharing config as separate guides. famstack runs both of those for you in one command, but the guides are useful if you want to understand what is actually happening, or to debug it later.

#Local AI

The ai stacklet turns your Mac into an AI machine. It installs three things native on your Mac, not in Docker:

The model gets picked for your RAM. 16 GB Mac gets a small one. 64 GB Mac Studio gets something proper. Switching is one line in stack.toml and ./stack setup ai.

I picked oMLX over Ollama because it is faster on Apple Silicon and can serve models bigger than your RAM by spilling to SSD. I really wanted Ollama to win that comparison by the way. It did not. Full write-up in two parts: Same Engine, 37% Slower and the follow-up isolating the variables, with another one coming after the r/LocalLLaMA folks pointed me at a few caching bugs I missed.

If any of the above is unfamiliar territory: How Local LLMs Actually Work on Your Mac is the primer I wish someone had given me before I started, and What is Ollama and How Do You Run It on a Mac? covers the simpler path if you just want to play with a chat model first. The Open WebUI + Ollama setup is what chatai is essentially wiring up for you under the hood.

#The Memories room

This is the part I am most excited about, even though almost none of the AI on top of it ships in this release.

The room itself works. Once or twice a week, usually at the dinner table, we record a short voice message into it. What was funny, what the kids said, what we want to remember. Whisper transcribes them automatically. The archive sits on our Mac.

Four weeks of doing this and I already have stuff I would never have gotten otherwise. The kind of small things you forget by Wednesday. We wished we had started this with our first son. We didn’t, and those years are gone. With the second one we are.

What is coming next on top of it: weekly summaries from the voice messages and the photos. A “do you remember” feed. One year ago today the kids said this. Two summers ago at the lake, that happened. Voice and photos matched by day, surfaced by the local LLM. The data is already collecting. The pipeline lands in the next release.

If you are going to do one thing with famstack, do this. Start a memories room. You will wish you had started earlier.

#Stuff under the hood that took me too long

A few things I am happy with after going through more iterations than I would like to admit:

Those four are unsexy and you will not notice them, which is exactly how they were supposed to turn out.

#What is missing or rough

If any of those are blockers for you, this isn’t the release. Wait two months.

#Why I am shipping it

I have been sitting on this for a while. One more polish, one more bug. Going from “runs on my Mac” to “installs on yours” turned out to be more work than building the features. Testing on machines I do not own, chasing the small breakages you only find when someone else opens the install. At some point you put it in front of strangers or it dies on your laptop.

I built famstack because I was manually copying photos off my phone with a cable, like a caveman, while writing automation software for enterprises during the day. That, plus a drawer full of paper, plus the thought of losing more years of voice memories from our kids while I kept telling myself I would get to it next month. The full origin story is over in The €900 NAS I Never Built and continues in I Bought a Mac Studio to Run Local LLMs if you want it.

So if any of that sounds familiar, clone the thing and try it.

git clone https://github.com/famstack-dev/famstack.git
cd famstack
./stack

User guide covers every stacklet. Discord is the fastest way to find me. GitHub repo is here, and a star really does help keep this alive.

Onwards to 0.3.

This code was written with the help of frontier AI. There is simply no other way for a family father on a side project. I refuse to call it vibe coded though. It took too long for that. AIssisted Engineering is closer to the truth.

Hi, I'm Arthur 👋 Interesting? Stuck? Got improvements? Come yell at me or just say hi.

Discord X Bluesky YouTube Reddit

I'm making this reusable for you.

Get notified when the repo goes online. One mail. Promise.