Maisnie

User guide · Software preview

Backup and restore

What to copy

Two things make up everything Maisnie knows: your data directory, and your vault. The vault step in setup takes a free-text path with no default, so the two are wherever you typed them — Maisnie never places the vault inside the data directory for you, even on a fresh box, so expect to copy both directories.

  1. Stop the box first. Run Ctrl+C (or, on Windows, Ctrl+Break works the same way) on the terminal running maisnie up, or otherwise make sure nothing is writing to either location, before you copy anything. Copying files that are being written to at the same time can produce a backup that doesn’t open cleanly.
  2. Copy the whole data directory — the one you pointed --data-dir or $MAISNIE_HOME at, or the per-OS default if you didn’t (see install); maisnie doctor’s data_dir_writable line names it if you’re not sure (maisnie status does not print it). This holds your configuration document, the state every source’s sync keeps between runs, and logs.
  3. Copy the whole vault folder, wherever you pointed it during the vault step. If you enabled version history, this is a git repository — an ordinary file copy still works, but if you’d rather, any way of cloning or copying a git repository works too.

Copy directories, not individual files inside them — a partial copy of a directory that’s supposed to travel as a unit (in particular the search index, if you have one) is more likely to cause a confusing problem later than a clean, whole-directory copy.

Secrets in the backup

Read this before you decide where a backup goes. A private calendar link, a mail app password, a model provider’s API key — every one of these lives in the configuration document, either sealed or as plain text; security has the full table for what protects which and what that does not protect against. Two things matter specifically for a backup, beyond that table:

  • A sealed value only opens where its key is. On Windows and macOS the key is bound to your user account on this one machine (DPAPI, your login keychain) — a data directory copied anywhere else cannot open anything sealed in it. If a backup is headed for a different machine or account, run maisnie secrets open first: it makes its own same-day, plain-text backup before converting anything, so the copy you carry stays readable where it lands, and you can maisnie secrets seal it again once it’s there.
  • On Linux, Docker, and anywhere else the key is a second file (secret.key, beside the configuration document, inside the data directory) — copying the configuration document alone is not enough once anything is sealed. Copying the whole data directory already includes it; a partial copy that leaves secret.key behind opens nothing sealed under it.
  • Without the secrets extra installed, or before anything has been sealed, a secret is still plain text — protected only by the file’s own permissions (0600 on Linux/macOS; an advisory-only note on Windows, whose permission model doesn’t map onto the same bits). A backup of your data directory is, among other things, a backup of every one of those in the clear.

Treat a Maisnie backup the way you’d treat a file that contains all your passwords, because for whatever in it is still plain text, that’s what it is: don’t email it to yourself, don’t drop it in a shared or public cloud folder without separately encrypting it, and don’t hand a copy to someone you wouldn’t hand those individual secrets to directly.

Restore

There’s no restore wizard in this release, and the data directory must go back at the exact same absolute path it was backed up from. The configuration document init wrote bakes in absolute paths — runtime.data_dir/state_dir/log_dir, gatekeeper.state_home, llm.telemetry.dir — and nothing in this release rewrites them on restore. maisnie doctor does not check any of these paths, so it can report every check green while the box is quietly reading and writing the old location (a unlock/unclaim run against a moved data directory acts on the stale path recorded inside the moved copy, not the one you actually pointed --data-dir at).

  1. Put the data directory back at the identical path it was copied from. If that path can’t exist on the new machine (a different username, a different OS), open <data>/config/majordomo.json and edit every one of the paths named above to match the new location by hand — there is no tool that does this for you yet.
  2. Put the vault folder back wherever you’ll point Maisnie at it (it doesn’t have to be the exact same path — the adopt step in set up your vault will read whatever’s there and recognize it as an existing vault).
  3. Run maisnie doctor to confirm the restored configuration document still loads and every port is free, then maisnie up. Remember that doctor’s “OK” here doesn’t cover the paths above — check them yourself first if you moved the data directory at all.

If you’re restoring onto a different machine, secrets that reference something local to the old machine — a subscription CLI’s binary path, in particular — may need re-entering through choose a model, since a path that was valid on the old machine has no reason to exist on the new one. And if the restored data directory ends up at a path the box doesn’t recognize as its own (its claim record didn’t come along, or you started fresh instead of restoring it), the box reads as unclaimed — claim it before putting it anywhere reachable beyond loopback, the same as a brand-new box.

Next

Continue to security.