Security & Privacy
mxr is local-first by design.
Mail syncs from the provider into SQLite on your machine. Search runs against the local index. The daemon and its clients use that state; a client can still send returned mail to an external model or another service. There is no hosted mxr relay in the middle.
What stays local
Section titled “What stays local”- SQLite is the canonical store
- Tantivy index is local and rebuildable
- The daemon runs on your machine
- The TUI and CLI talk to the daemon over a local Unix socket
- The web app talks to the same daemon through a loopback HTTP/WebSocket bridge
What still talks to a provider
Section titled “What still talks to a provider”- Sync
- Send
- Provider-side mutations like archive, trash, labels, and spam
- Browser handoff for HTML or unsubscribe pages when needed
There is no mxr-operated service in that list. Six other things can reach the network, each because you configured or asked for it:
- The model endpoint under
[llm], when you turn model features on and point them at a cloud provider. - The semantic search model weights, downloaded once from Hugging Face unless
search.semantic.auto_download_models = false. Embedding runs on your CPU after that. - Remote images in HTML mail, unless
render.html_remote_content = false(the web app has its own Remote images toggle). - The unsubscribe endpoint a sender chose, when you run
mxr unsubscribe. - Marginalia, once you connect it.
Oon an item, ormxr reading marginalia send, sends the item’s text there. Marginalia may embed its opening text with the embedding provider your library is set up with. Sync then reads highlights back from it. Nothing is sent until you pressOor runsend. - The site a newsletter links to, when you fetch its article in Reading (
L, the reader’s Article tab,bon a link,Oon a digest link whose article isn’t saved, ormxr reading open ITEM --article). The client names the site first. The fetch refuses this machine and private networks by name and by every resolved address, checks each redirect, uses no proxy and stops at 5 MB. Nothing fetches an article on its own.
The daemon also downloads one kind of attachment before you open it: the PDFs of
emails Archive filed as records, from your own provider,
newest first, up to records.pdf_budget_mb (512 MB) in total and skipping
any PDF over records.pdf_max_file_mb (15 MB). They go to the same
attachment cache as the files you open, so they open offline and their text
is searchable. Set records.pdf_prefetch = false to download them only when
you open them.
Records themselves are local rows in SQLite, read from your mail by rules and schema.org markup on your machine; no model sees them. The activity log records no record fields: Archive’s requests are not written to it.
For agents has the config that turns the last three off.
Model features are off by default and go only where you point them
Section titled “Model features are off by default and go only where you point them”[llm] enabled defaults to false, and the default endpoint is a model server on localhost. With a local endpoint and a model it serves, prompts stay on your machine: mxr calls a loopback endpoint directly, ignoring HTTP_PROXY, and never follows a redirect from an LLM endpoint. Two settings send prompts elsewhere even with a local base_url. A Claude, GPT or OpenRouter-style model name goes to that hosted provider (the routing table lists them). And [llm.fallback] sends the features that don’t carry your wider history to a hosted model while the local endpoint is out. Only localhost, 127.x.x.x and ::1 count as local: a server on your home network or tailnet counts as cloud.
A cloud endpoint receives the mail each feature works on, and that is mail other people wrote to you. Use a provider whose API data terms cover that mail, with an API key you supply: in the environment variable named by api_key_env, or for routed models stored with mxr llm key set (piped in, kept in secrets.toml at mode 0600 and never in config.toml) or read from ANTHROPIC_API_KEY, OPENAI_API_KEY or OPENROUTER_API_KEY. Claude models go to Anthropic and OpenRouter, and GPT models to OpenAI and OpenRouter unless base_url is a server of your own off this machine. These models always count as cloud. mxr ships no key and runs no relay. Besides the commands you run and the threads you open, two background jobs reach a cloud endpoint without a separate opt-in: row gists for conversations from people that a client shows (and for automated mail while the web app’s Updates page is open), and confirmation of mail the delivery heuristic shortlisted. Features that carry your wider history (relationship summaries, commitments, answer coverage, briefings, decisions, mxr ask and the assistant) are refused on a cloud endpoint, and kept off [llm.fallback], unless you set llm.allow_cloud_relationship_data = true. Assistant conversations, including the mail text it read, are kept in your local database, left out of portable backups, and deleted with mxr assistant delete. Apart from saving new drafts, every change the assistant makes waits for your approval unless you let a conversation run reversible changes (archive, read, star, moves) on its own; sending, deleting, trash, spam and rules always ask. LLM features lists what each request sends.
mxr llm status --format jsonenabled says whether model features are on. Each entry in features says where that feature goes: cloud is true for anything off this machine, base_url or routes names where it goes (the hosted providers in order), and blocked says why privacy settings keep it from its model. With [llm.fallback], endpoint shows base_url’s health, fallback lists the providers behind it, and fallback_withheld says why a history feature stays on base_url alone.
Released mxr contains no tracing code. A developer can build mxr with the langfuse feature to record each model call, prompt and reply included, in a Langfuse they run themselves. That build sends traces only to a Langfuse on the same machine and refuses any other address, Langfuse Cloud included.
Email modes already place messages using deterministic rules and stored
assessment data during sync. The fast and smart model tiers described in
the plan are future work; they are not the current classification path or
configuration keys. Other configured background model calls, such as
delivery confirmation and row gists, have separate timing and data scopes
listed in LLM features.
Deleting an email removes most of what mxr derived from it
Section titled “Deleting an email removes most of what mxr derived from it”When your provider deletes or expunges a message and mxr syncs that change, the daemon deletes the local message and clears derived database state in the same transaction. It also queues cleanup outside SQLite so a restart does not lose track of files and index entries that still need removing.
| Data | What deletion does |
|---|---|
| Body, headers, labels, flags, snooze, reply-later state, pins, invites and reply timing pairs | Removed with the message |
| Thread summaries, row gists, recipient briefings and affected relationship summaries | Invalidated; later requests can rebuild them from remaining mail |
| Extracted promises | Removed when their source message is deleted |
| Decisions and deliveries | Lose the deleted evidence; removed when no evidence remains |
| Archive records | Lose fields from that source; recomputed from remaining sources, or deleted with their last source |
| Automatically detected tasks | Removed with their source; tasks you made, edited or scheduled remain, with copied evidence and source pointers cleared |
| Reading items and their dependent data | Removed with their source message |
| Semantic chunks and embeddings in SQLite | Removed with the message |
| Keyword and in-memory semantic index entries, managed attachment cache files | Cleaned by sync and the durable cleanup queue |
File/index cleanup is not a secure-erasure guarantee. Failed file cleanup uses bounded retries and is reported in daemon logs; a file the daemon cannot remove may remain. If the in-memory semantic index cannot forget a message, its next rebuild or daemon restart drops the entry. Copies you exported or saved outside the managed cache are yours to remove.
User-authored drafts and corrections, tasks you chose to keep, and no-text
operation/receipt identities are retained deliberately. A record with other
source mail can keep your corrected field values. Contacts with remaining
mail are not deleted merely because one message is gone. Assistant
conversation history is separate: use mxr assistant delete to remove a
conversation and its transcript.
Moving mail to Trash is not a delete: on Gmail the message keeps its derived data until Gmail empties the trash and reports the deletion. mxr has no command that deletes a message permanently.
To remove everything at once, preview the reset first:
mxr reset --hard --dry-runA hard reset deletes the database, both indexes, the model cache, logs, and the attachment cache when it lives inside the data directory. It keeps config.toml unless you add --including-config, and it leaves secrets.toml alone either way.
New stores must define how they follow message deletion. That rule is implemented for the derived data above; it does not mean deleting your own writing, exported files or the retry identities needed to prevent duplicate effects.
Guardrails that exist today
Section titled “Guardrails that exist today”--dry-runon risky mutation commands (includingmxr sendandmxr unsnooze --all)- Interactive confirmation for destructive and batch mutation flows unless
--yesis set - Undoable mutations:
archive,trash,spam,read,read-archiveprint amutation_idyou can pass tomxr undofor ~60s - Persisted mutation history through
mxr history - Event and log views through diagnostics and CLI commands
- Plain-text-first reader mode, with browser escape hatch for original HTML
- Daemon IPC socket permissions are set to
0600on Unix. - The bridge requires bearer auth for every authority-bearing route. Only
/api/v1/healthand/api/v1/auth/local-tokenare unauthenticated bootstrap routes; a request a browser marks as cross-site is refused even with a valid token. - The bridge checks Host/CORS allowlists and adds frame, content-sniffing, and referrer-policy headers.
- Saved attachments and rendered HTML assets are written
0600on Unix. - User-initiated attachment downloads are limited to the configured downloads directory, the current directory, or the system temp directory.
- Remote HTML assets are capped before writing, even when the server omits
Content-Length.
Where credentials live
Section titled “Where credentials live”IMAP/SMTP passwords are stored on disk, keychain-optional. They live in
<config_dir>/secrets.toml — a plaintext TOML file at mode 0600 (owner
read/write only), keyed by password_ref + username. This is the same model
normal CLIs use (~/.aws/credentials, ~/.config/gh/hosts.yml): the deliberate
tradeoff is plaintext-at-rest, protected only by filesystem permissions rather
than OS encryption. mxr chose disk-first because an ad-hoc-signed release binary
loses its OS-keychain read access on every upgrade — which used to hard-fail
daemon startup for password accounts. A 0600 file survives upgrades untouched
and is readable only by your own processes.
The OS-native secret store is an optional fallback:
- macOS: Keychain (Keychain Access)
- Linux: Secret Service (e.g. GNOME Keyring, KWallet)
On the first read after upgrading from a keychain-only version, an IMAP/SMTP
credential found in the keychain is automatically migrated (mirrored) into
secrets.toml and served from disk thereafter. mxr accounts add and
mxr accounts repair NAME write secrets.toml (disk-authoritative) with a
best-effort keychain mirror that never blocks the operation. The on-disk
config.toml only references credentials by password_ref; it never stores the
password itself.
Password lookup happens when an account connects or syncs, not while the daemon
is being constructed. An unreadable password should fail that account’s
operation without preventing the daemon or other configured accounts from
starting. Set MXR_KEYCHAIN=off to disable keychain reads and writes for
IMAP/SMTP passwords; with that setting, secrets.toml is their only source.
The setting does not affect Gmail or Outlook OAuth token storage.
Gmail OAuth refresh tokens are stored in the OS keychain with a private disk
fallback under the active token dir, so a noninteractive keychain failure does
not strand an otherwise valid account. Outlook OAuth tokens are JSON files under
the active token dir (<data_dir>/tokens by default, MXR_TOKEN_DIR when set).
secrets.toml lives in the config dir, so mxr reset and mxr reset --hard
preserve it — your credentials survive a runtime-state wipe. Override its
location with MXR_SECRETS_PATH. Protect it like any dotfile secret: keep the
0600 mode and do not commit it to version control.
Backup and restore
Section titled “Backup and restore”mxr does not run a hosted backup service. Use its stopped-profile backup workflow instead of copying a live database. Backups preserve cached mail, drafts, and managed attachment bytes, but exclude credentials and tokens. Restored drafts remain held; activation permits new work after review but does not release original draft IDs or resume old schedules. See Back up and restore a workspace for the full procedure and limits.
Bridge and local IPC boundary
Section titled “Bridge and local IPC boundary”The Unix socket is a local user boundary. Any process that can connect as the same OS user can drive the daemon with that user’s authority, so mxr keeps the socket owner-only and expects it to live under a user-owned runtime directory.
The HTTP bridge is broader because browsers cannot open Unix sockets. It binds to loopback by default, uses a bearer token stored under the active profile config directory, rejects DNS-rebinding-shaped Host headers, and keeps API docs behind the same auth gate as the rest of the API.
Attachments and remote content
Section titled “Attachments and remote content”Attachment names are sanitized before mxr writes local files, including
Windows reserved names such as CON and LPT1. Explicit downloads are
constrained to safe destination roots. Inline and remote HTML assets live
under mxr’s attachment cache, get private file permissions, and remote
asset fetches have a fixed body-size cap.
Attachment transfers return bounded chunks with message and attachment IDs, then clients verify the complete length and SHA-256. CLI and TUI save/open operations write on the client machine. The browser verifies the assembled bytes before downloading or opening a passive text or raster image in a separate tab; HTML, SVG, PDF and other types download instead. Provider fetches still materialize a complete byte vector on the daemon, and browser transfers assemble a complete Blob in memory.
Agent and MCP boundaries
Section titled “Agent and MCP boundaries”The first-party MCP server and agent-origin permission profiles now run through
the daemon’s normal IPC boundary. Configure read-only, draft-only,
restricted, or full policy per origin; limit accessible accounts; and gate
send or destructive operations separately. MCP send and mutation tools also
require confirm=true.
[agents.profiles.mcp]safety_policy = "draft-only"allowed_accounts = ["work"]allow_send = falseallow_destructive = falseThese controls reduce blast radius. They do not make email trustworthy. Every email field and attachment remains untrusted data, so an agent must never treat mail content as permission or instructions. See For agents for the operating rule and worked examples.
Practical advice
Section titled “Practical advice”- Use
--dry-runbefore any batch mutation. - Use app passwords or provider-specific credentials where your provider recommends them.
- Keep
secrets.tomlat mode0600, and keep any fallback keychain entries scoped to the accounts you use. - If an agent is involved, prefer workflows that search, read, export, and draft before workflows that mutate.
Supplied HTML
Section titled “Supplied HTML”mxr accepts a designed HTML email and preserves it exactly. That means it does not sanitise it either, so validation is a gate rather than a filter:
- Active content —
<script>,<object>,<embed>,<applet>,<iframe>,<form>, inlineon*handlers,javascript:/vbscript:URLs,<style>blocks containingexpression(), and anything of the sort hidden inside a conditional comment — is reported and refused. The draft is not created and the document is not modified. data:URLs are allowed only fordata:image/*.- The check runs in the daemon, not only in the CLI, so an IPC client cannot route around it.
- Validation parses with html5ever to inspect the document. A hostile document could in principle be parsed differently by a specific mail client, so this is a strong gate rather than a proof.
Content IDs supplied via --inline are restricted to letters, digits and
. _ - +, which keeps a CR/LF out of a Content-ID header.
Web previews of an HTML draft render in a sandboxed frame with a policy that blocks remote loads, so opening a draft does not phone home to a sender’s server.
What HTML drafts put in the activity log
Section titled “What HTML drafts put in the activity log”The activity log records the content kind (markdown or html) and the number
of inline assets. It does not record the HTML, the text alternative, inline
asset paths, recipient addresses, or any template property value. See
the activity log.