Maisnie

User guide · Software preview

First boot

Write the config, then bring it up

maisnie init
maisnie doctor
maisnie up

maisnie init writes one configuration document, with every path already filled in, to your data directory. Run it again with --force if you ever want to start over from a blank document (this does not touch your vault or your notes, only the configuration document itself). --port changes the front port (default 8080); the two ports behind it are --port + 1 and --port + 2 (so 8081 and 8082 by default), and you don’t set those separately.

It also tries to record your own time zone from the computer it runs on, so Maisnie can show meeting times in it later — read from $TZ, from /etc/localtime on Linux and macOS, or, on Windows, from a short list of common zones. When none of those gives a real answer (Windows keeps no full list of them at all, so an uncommon zone there is simply not one this list recognizes), it leaves this unset rather than writing a guess, and you can set it any time from Settings.

maisnie doctor is a pre-flight check: is the Python version new enough, is the data directory writable, does the configuration document load correctly, are the ports free, is git on your PATH if you plan to use it, does your Python have a time zone database, does your SQLite build support full-text search. Run it before up and after any change you’re unsure about. It exits with a non-zero status if anything is actually broken; a missing time zone database or an advisory-only file permission check on Windows shows as a note, not a failure.

maisnie up starts the box in the foreground and prints the URL to open. Leave this terminal open — it’s how the box stays running, restarts a piece that crashes, and shuts everything down cleanly on Ctrl+C (or, on Windows, Ctrl+Break, which shuts down exactly the same way). Running it a second time against the same data directory refuses, because the first up is already holding the instance lock; that’s normal, not a bug, if you meant to have only one box.

Loopback by default

The address maisnie up prints — http://127.0.0.1:8080 with the default port — only answers requests from the same machine. That’s 127.0.0.1, the loopback address: nothing on your network, not even another device in the same room, can reach it. This is deliberate and it’s the default for a reason: the very first thing you do is set a passphrase, and until that’s done, anyone who can reach the box owns it. Keeping the box loopback-only for that first minute means the only “anyone” who can reach it is you, sitting at the keyboard.

Open http://127.0.0.1:8080 (or whatever port you chose) in a browser on the same machine.

Claiming the box

The page you land on is titled “Welcome to Maisnie”: a passphrase field (at least 12 characters — a shorter one is refused) and a field to confirm it, with one button, Set passphrase and continue. Beside the form, a short “What happens next” list previews the whole wizard — Vault, Sources, Accounts, Model — so the very first page already says where this is going. Claiming happens exactly once — the first browser to submit a valid claim becomes the owner, and every visitor after that gets a login form instead. There’s no way to add a second owner or recover a lost passphrase except starting over (see troubleshooting for maisnie unclaim), so choose a passphrase you’ll actually remember, or write it down somewhere safe. It’s checked with a slow, deliberately expensive comparison (600,000 rounds of PBKDF2), so a guesser trying passphrases against your box pays a real cost per guess; a login also locks out after five wrong tries for 15 minutes, so guessing isn’t a productive way in either way.

Once you’ve claimed the box, you land on Home, which — until setup is finished — shows a checklist headed “Let’s finish setting up Maisnie” instead of your notes: Vault, Sources, and AI model, each marked “To do” or “Done”, with one button, Continue setup, that takes you into the wizard wherever it left off. The rest of this guide walks through that wizard, starting with set up your vault.

What the page says about your connection depends on how you can actually reach it, and it never overstates the risk or plays it down:

  • Loopback (the default for a plain install, and what this page assumes): a plain notice, “Only this computer can open this page” — Maisnie is only answering this computer, so nothing you type crosses a network at all. This is the case the rest of this section describes.
  • Reachable, but you opened it from this computer (the Docker install’s own default — see install): a caution, “Other devices may reach this page” — what you type stays on this computer, but the box is also set to answer other devices, unless the way you started it keeps it to this one, the way Docker’s own default port mapping does. Whoever sets a passphrase first becomes the owner, so the notice tells you to set yours now.
  • Actually reachable from another device on your network: the strong warning — “This connection isn’t encrypted” — anything you type, including the passphrase, crosses your network in the clear, and anyone who can reach the box before you claim it can claim it instead. This is the case when to use --lan exists to keep you out of by default; see also install for the one way a container’s own port publish can end up here.

Claiming the box does not give it a certificate. Whichever notice you saw explains why there wasn’t one yet — but there still isn’t one afterward either, so the box stays plain HTTP until you add your own (see “Bring your own certificate,” below); claiming only closes the window against everyone else claiming it first.

When to use --lan

maisnie up --lan binds the front port to all network interfaces instead of just loopback, so other devices on your network — your phone, another computer — can reach it. It’s refused outright until the box has been claimed: there is no way to expose an unclaimed box, on purpose. Once claimed:

maisnie up --lan

maisnie up --lan still prints the loopback URL (http://127.0.0.1:<port>) even though it’s now also listening on every interface — that’s not the address to use from another device. To reach it from your phone or another computer, find this machine’s own LAN address first (ipconfig on Windows, ip addr or ifconfig on Linux/macOS, or Settings > Network on either) and open http://<that-address>:<port> instead. The first time you do this, your OS’s firewall will likely prompt you to allow the connection — accept it for the network you’re actually on.

Two things to know about this flag:

  • It’s a runtime choice, not a saved setting. It doesn’t change your configuration document; run maisnie up without --lan next time and you’re back to loopback-only.
  • It’s still plain HTTP unless you’ve added a certificate (bring-your-own; see below). Every passphrase, every note you view, crosses your LAN unencrypted. On a home network you trust, this is a real but usually acceptable tradeoff; treat it differently on a network you share with people or devices you don’t. Don’t forward this port to the internet — plain HTTP carrying your passphrase and your notes has no business leaving your LAN at all, and reaching the box from outside your own network isn’t something this preview supports anyway — the Settings page says as much under its own “Remote access” heading, and lets you choose in advance how much a remote session may do once that arrives (see daily use).

Bring your own certificate

Maisnie doesn’t generate certificates for you. If you have a certificate and key — from your own CA, a reverse proxy, or a service you already use for LAN certificates — edit the configuration document at <data directory>/config/majordomo.json (see the command line for where your data directory is) and add a tls key inside the existing gatekeeper object — merge it in alongside bind, routes, and state_home, which are already there; a second, separate top-level "gatekeeper" key is invalid and only the last one written would count:

{
  "gatekeeper": {
    "bind": { "host": "127.0.0.1", "port": 8080 },
    "routes": [ ... ],
    "state_home": "...",
    "tls": { "cert": "/path/to/fullchain.pem", "key": "/path/to/privkey.pem" }
  }
}

On Windows, write the paths with forward slashes or doubled backslashes — plain single backslashes aren’t valid inside a JSON string: "C:/Users/<you>/certs/fullchain.pem" or "C:\\Users\\<you>\\certs\\fullchain.pem".

Stop the box first if it’s running, save the file, then start it again (maisnie up, or docker compose restart under Docker) — the front door reads its TLS settings only when it starts. Once it’s back up, the claim caveat and the plain-HTTP language above stop applying: the URL becomes https://..., the session cookie gains the Secure flag, and traffic is encrypted in transit.

Next

Continue to set up your vault.