The Maisnie user guide

Maisnie is a small piece of software you run on your own machine or network. It connects to a few of the services you already use — a calendar, a mailbox, a feed you follow — and turns what happens there into a private, searchable store of plain text files on a disk you own. Nothing you connect is copied to a server run by Maisnie, because there isn’t one: the setup wizard and the search box always run on your box, and the only network calls Maisnie makes on your behalf are the ones you explicitly set up (a calendar feed, a mailbox, the feeds you follow, and whichever model you chose). The model itself runs wherever you pointed it: on your own hardware if you chose the local door, or at the provider you chose for any of the other three — see choose a model and security for exactly what that means per door.

This guide covers the early-access preview. You install it with pip, or with Docker — see install for both — open a browser, and a setup wizard walks you through claiming the box, connecting a place to keep your notes, turning on the sources you want, connecting each one’s account, and picking a model to answer questions about what it has collected. Three connectors ship with this release — a calendar, a mailbox, and the feeds you follow — each syncing on its own schedule once you’ve connected its account (see connect your accounts), and Ask (see daily use) answers a question from what they’ve collected, citing the specific notes it drew from.

Words this guide uses

A handful of names come up before this guide formally introduces them — here’s the short version of each, in one place:

• The box — the whole running Maisnie instance: gatekeeper, Desk, and Surface together, started by one maisnie up.
• Gatekeeper — the one process bound to a network-reachable address; the only place a login is checked. Everything else sits behind it on loopback.
• Desk — the setup wizard’s own HTTP surface (/setup/...): vault, sources, accounts, and AI, and the only component that writes configuration or touches secrets.
• Surface — the Home/Search/Ask pages you use day to day, once setup is done.
• Door / connection — a door is one of the four ways in to a model (your subscription’s CLI, a direct API key, an aggregator, a local model); a connection is one saved, tested setup through a door — you can have several connections through the same door.
• TLS — the encryption behind https://; “plain HTTP” means without it.

See security and the command line for the fuller version of gatekeeper/Desk/Surface, and choose a model for the full door-by-door breakdown.

Who this is for

You don’t need to be a developer to use Maisnie, but this preview assumes you’re comfortable installing a Python package or running a Docker container, reading a short error message, and finding a file on your own machine when a page tells you where to look. If you can do those three things, the rest of the guide is written for you.

Pages, in order

1. Install — get Maisnie running for the first time.
2. First boot — claim the box and understand loopback vs. LAN.
3. Set up your vault — where your notes live.
4. Turn on sources — the Sources step, and what turning one off does.
5. Connect your accounts — the private links and passwords each source needs.
6. Choose a model — the four doors in, and Save and test.
7. Daily use — Home, Today, Coming up, Search, Ask, and where your notes land.
8. The command line — every subcommand, every flag, every exit code.
9. Backup and restore — what to copy, and what it contains.
10. Security — claiming, sessions, CSRF, and what each model door can see.
11. Troubleshooting — symptom, cause, fix.
12. FAQ
13. Privacy — what Maisnie stores, where, and what it never does.