Self-host on a Mac (native)
The setup the author runs at home: a Mac mini in a cupboard, the server as a background service, local AI on Apple silicon. About fifteen minutes.
last updated 07 Jul 2026 · applies to server 0.x (pre-1.0)Prefer containers? The Linux guide uses Docker Compose. On a Mac, though, the native install is the better path: it gets Apple Vision OCR and Metal-accelerated AI, which Docker on macOS cannot pass through.
What you need
Any Mac with Apple silicon works. The archive itself is small — the letters of a household for a decade fit in a few gigabytes; the AI models take the most room.
You also need the command-line basics: Homebrew, plus git and uv (both installable with Homebrew).
Install
First the AI runtime. Ollama runs the vision and embedding models locally; the two pulls are the only downloads the pipeline ever needs:
brew install ollama uv
brew services start ollama
ollama pull qwen3-vl:4b-instruct
ollama pull bge-m3Then the server itself. The install script registers it as a login service (launchd) bound to this Mac's LAN address, so it starts with the machine and restarts if it crashes:
git clone https://github.com/nielsfilmer/briefkist.git
cd briefkist
bash deploy/install.sh # binds this Mac's primary LAN IP
# or pin an explicit address:
bash deploy/install.sh 192.168.1.76Check it's alive — the web app is served on port 8484 (a 401 from the API also means alive; every endpoint is authenticated):
curl -i http://<LAN-IP>:8484/api/statusThe server binds one specific address and refuses wildcard binds by design — your archive is never exposed on every interface. Keep it on the LAN (or a Tailscale/WireGuard address); don't port-forward it to the internet. If the Mac's LAN IP changes, re-run bash deploy/install.sh — and give the machine a static IP in your router so it stops happening.
Updating later is the same two commands: git pull, then re-run bash deploy/install.sh. Logs live at ~/Library/Logs/briefkist/server.log.
Pair your phone
Each device gets its own token, minted on the Mac. From the repo directory:
uv run python -m server.tokens_cli add "my-iphone"The token is shown exactly once — copy it. On the phone (same Wi-Fi): open http://<LAN-IP>:8484, tap the settings gear, paste the token, save — then use the share sheet's "Add to Home Screen" so the archive sits next to your other apps. This phone talks only to your own server; the token works nowhere else, and you can revoke it at any time with uv run python -m server.tokens_cli revoke "my-iphone".
File your first letter
Photograph any letter from today's pile. Processing is asynchronous — roughly twenty to thirty seconds per page on a Mac mini — and the recent-uploads list updates live until the letter is filed with a sender, date, summary and keywords, all extracted on the Mac in the cupboard. Nothing left the house. Any field the model got wrong can be corrected inline in the letter's detail view.
Back it up
Everything lives under the data directory (default data/archive/ in the repo): one SQLite database plus the image folders. Copying that folder to an external disk is a complete backup — do it periodically until scheduled encrypted backups land.