Config
Location
Section titled “Location”mxr resolves a runtime identity first, then places config, data, socket,
token, and bridge files under that identity. Release builds default to
mxr; debug cargo run defaults to mxr-dev; demo mode uses
mxr-demo. Override with MXR_INSTANCE only when you want an explicit
profile.
To inspect the resolved path:
mxr config pathmxr status --format jsonFor the active <instance>, the default roots are:
| Kind | Linux / XDG | macOS |
|---|---|---|
| Config | $XDG_CONFIG_HOME/<instance>/config.toml |
~/Library/Application Support/<instance>/config.toml |
| IMAP/SMTP secrets | $XDG_CONFIG_HOME/<instance>/secrets.toml |
~/Library/Application Support/<instance>/secrets.toml |
| Data | $XDG_DATA_HOME/<instance>/ |
~/Library/Application Support/<instance>/ |
| Socket | $XDG_RUNTIME_DIR/<instance>/mxr.sock |
~/Library/Application Support/<instance>/mxr.sock |
MXR_CONFIG_DIR, MXR_SECRETS_PATH, MXR_DATA_DIR, MXR_TOKEN_DIR,
MXR_SOCKET_PATH, MXR_BRIDGE_TOKEN_PATH, and MXR_BRIDGE_PORT_PATH
override individual paths when needed.
MXR_EDITOR, MXR_SYNC_INTERVAL, MXR_DEFAULT_ACCOUNT, MXR_ATTACHMENT_DIR,
MXR_DOWNLOAD_DIR and MXR_SAFETY_POLICY override the matching [general]
keys for the process that reads them. They are never saved into the file.
Settings changes, account forms and mxr config set read config.toml as
written, change only what you asked, and keep the comments and layout of the
keys they leave alone. A save adds a setting your file doesn’t have only when
its value differs from the default, so settings you never wrote keep following
mxr’s defaults; a setting you wrote stays, even at its default value. If there
is no file yet, the first save writes every setting, so mxr config edit opens
a full template. Keys mxr doesn’t recognise are dropped on save. Each save
replaces the file atomically, so an interrupted save leaves the old one.
IMAP/SMTP passwords are stored in secrets.toml at mode 0600, not in
config.toml. The OS keychain is an optional migration fallback. Set
MXR_KEYCHAIN=off when IMAP/SMTP password handling must not touch it, such as
on a headless host. This setting does not change OAuth token storage.
See Security & Privacy
for the storage model and its tradeoff.
MXR_IPC_TIMEOUT_SECS overrides the CLI’s 120-second cap on ordinary requests
(status polls, reads, single mutations); 0 waits indefinitely. Long-running
operations — sync, analytics rebuild, semantic reindex and model installs,
delivery scans — are not capped by it at all: they stream progress and wait for
the daemon however long it takes, so Ctrl-C is the only way out of one (a model
download during mxr semantic profile install, for instance). Reach for this
only when a short call on a slow host is genuinely timing out.
MXR_DAEMON_ADDR selects which transport the mxr CLI dials:
unix://<path> (default), tcp://<host:port>, or cmd://<command> (e.g.
cmd://ssh -T host mxr daemon dial-stdio). MXR_DAEMON_TOKEN supplies the
daemon bearer token for tcp://. Set MXR_DAEMON_AUTOSTART=off when a service
manager owns a foreground daemon; clients can connect to a compatible owner but
will not start or replace one. See transports and the
headless Linux service recipe.
A daemon with no enabled real mail account (none, or only the fake provider
that tests and mxr demo use) stops itself after 30 minutes with no client
connected, so test and demo daemons don’t run forever. The next command starts
it again. A daemon with a real account keeps running. MXR_IDLE_EXIT_SECS
changes the wait in seconds; 0 turns it off.
Top-level sections
Section titled “Top-level sections”[general][render][search][search.semantic][snooze][logging][appearance][bridge][transports.tcp][notifications.chimes][llm][llm.fallback][llm.overrides.answer_coverage][safety.recipients][safety.tone][deliveries][modes][messages][todo][records][updates][reading]
[accounts.work]Annotated example
Section titled “Annotated example”A working config that exercises every section. Drop into the path
that mxr config path prints, then adjust:
[general]editor = "nvim" # or "code -w", "subl -w", "$EDITOR"default_account = "personal" # used when commands omit --accountsync_interval = 60 # seconds; how often the daemon pollshook_timeout = 30 # seconds; max time a shell hook may runsafety_policy = "full" # full | restricted | draft-only | read-onlyattachment_dir = "~/mxr/attachments" # optional internal attachment cache overridedownload_dir = "~/Downloads" # default destination for user-initiated saves
[render]html_command = "w3m -dump" # how plain-text HTML view is renderedreader_mode = true # default to reader on openshow_reader_stats = truehtml_remote_content = true # allow remote images in HTML view; every img is fetched, pixels included
[search]default_sort = "date_desc"max_results = 50default_mode = "lexical" # lexical | hybrid | semantic
[search.semantic]enabled = trueauto_download_models = trueactive_profile = "bge-small-en-v1.5"max_pending_jobs = 256query_timeout_ms = 1500
[snooze]morning_hour = 9evening_hour = 18weekend_day = "saturday"weekend_hour = 10
[bridge]enabled = truebind = "127.0.0.1"port = 42829 # stable local web URL portcors_allowlist = []host_allowlist = []auto_local_token = true # loopback callers can auto-fetch the token# token_path = "/absolute/path/to/custom-bridge-token"
[notifications.chimes]enabled = false # opt-in audio feedback from the daemonvolume = 0.35 # 0.0 .. 1.0new_mail = "bell"sent = "sent"archived = "archive"trashed = "thud"spam = "alert"snoozed = "pop"unsnoozed = "glass"reminder = "bell"error = "alert"
[llm]enabled = falsebase_url = "http://localhost:11434/v1" # Ollama defaultmodel = "qwen2.5:3b-instruct"api_key_env = "" # name of env var; empty for Ollama / LM Studiocontext_window = 8192request_timeout_secs = 120allow_cloud_relationship_data = false # true lets relationship features use a cloud endpoint
# [llm.fallback]# Optional. A hosted model used while base_url is out. Off unless present.# model = "gpt-6-luna" # the default when the table is present# context_window = 128000 # defaults to llm.context_window
[llm.overrides.answer_coverage]# Optional per-feature LLM override. Takes enabled, base_url, model,# api_key_env, context_window and request_timeout_secs; anything left out# comes from [llm]. Useful when answer coverage benefits from a different# model than the default (e.g. a smarter cloud model for the only# LLM-backed safety check). Answer coverage carries relationship data, so# a cloud model here runs only with allow_cloud_relationship_data = true# under [llm].# enabled = true# model = "gpt-6-luna" # key from `mxr llm key set openai`
[safety.recipients]internal_domains = ["company.com"] # paired with internal markers in bodysensitive_domains = ["competitor.com"] # always Blockerwarn_on_first_time_external = true # warn on never-seen-before domains
[safety.tone]formality_delta_threshold = 0.4 # 0.0 = always warn, 1.0 = never
[accounts.personal]name = "Personal"email = "me@example.com"enabled = true # per-account on/off; survives across daemon restarts[accounts.personal.sync]type = "gmail"credential_source = "bundled" # bundled | custom[accounts.personal.send]type = "gmail"
[accounts.work]name = "Work"email = "me@work.example.com"enabled = true[accounts.work.sync]type = "imap"host = "imap.work.example.com"port = 993username = "me@work.example.com"auth_required = trueuse_tls = true[accounts.work.send]type = "smtp"host = "smtp.work.example.com"port = 587username = "me@work.example.com"auth_required = trueuse_tls = truegeneral
Section titled “general”| Key | Type | Default | Purpose |
|---|---|---|---|
editor |
string | $EDITOR |
Used by mxr compose, mxr config edit, and the TUI compose flow |
default_account |
string | first enabled | Account selected when commands omit --account |
sync_interval |
integer (seconds) | 60 |
How often the daemon polls each account |
hook_timeout |
integer (seconds) | 30 |
Max wall-time for a shell hook |
attachment_dir |
path | <data_dir>/attachments |
Internal cache for opened/inline attachments |
download_dir |
path | platform downloads dir | Default destination for user-initiated attachment saves |
safety_policy |
enum | full |
Daemon-wide guardrail — see below |
safety_policy
Section titled “safety_policy”Caps which IPC categories the daemon will service. Useful when running mxr inside a CI sandbox or behind an agent you don’t fully trust:
| Value | Allows |
|---|---|
full |
All categories (default) |
restricted |
All except destructive / mutation IPCs |
draft-only |
Read + compose; no provider sends |
read-only |
Read-only IPCs only — no mutations, no sends |
“Read-only” covers every request that doesn’t change state: listing and
reading mail and threads, search and aggregation, exports, draft and reply
previews, local AI analysis (summaries, briefings, sender/relationship
profiles, humanizer scoring), and read access to the calendar-invite list,
the activity log, saved searches, and saved activity filters. Requests that
fetch remote content (HTML image assets, attachments) are not read-only
— they trigger network egress, so an agent under read-only can’t be used
to load tracking pixels. Every request is assigned its category by a single
exhaustive classifier in the daemon, so a new request type can never slip
through a policy by being forgotten in an allowlist.
The TUI greys out mutation actions when the policy disallows them.
agents.profiles
Section titled “agents.profiles”Profiles constrain cooperative daemon clients by the identity declared during
connection setup. agent selects [agents.profiles.agent]; mxr mcp serve
declares mcp and selects [agents.profiles.mcp]. The identity stays fixed
until disconnect. Missing profiles are rejected before ordinary requests or
events, including on event-only connections.
Configure the profile on the selected daemon host. Paired HTTPS agent/MCP
calls must satisfy both this host profile and the registration’s grants. A
profile can narrow those grants, never broaden them. Missing-profile errors
name the required TOML section: add it to the host configuration, restart the
host daemon through its service manager or mxr restart, then reconnect.
Client kinds are self-declared. These profiles guide cooperative clients;
a hostile same-user process can still declare itself cli.
[agents.profiles.agent]safety_policy = "draft-only"allowed_accounts = ["work"]allow_send = falseallow_destructive = false
[agents.profiles.mcp]safety_policy = "read-only"allowed_accounts = ["personal@example.com"]allow_send = falseallow_destructive = falseFields:
| Key | Meaning |
|---|---|
safety_policy |
Same enum as [general].safety_policy; default profile value is read-only |
allowed_accounts |
Account keys, account ids, or emails this origin may touch |
allow_send |
Required for SendStoredDraft, scheduled sends, and non-dry-run RSVP sends |
allow_destructive |
Required for mutations outside read/draft/send buckets |
allowed_destructive_actions |
Optional fine-grained allowlist within the destructive gate. When set, a destructive request is permitted only if its action is listed (and allow_destructive is still true). Empty/omitted = no per-action restriction. |
allowed_destructive_actions values: archive, trash, spam, move,
delete_label, remove_account, unsubscribe, redact_activity,
prune_activity. Benign mailbox mutations (star, mark read, label tagging)
are never restricted by this list — only the coarse allow_destructive
gate applies to them.
# An agent that may archive and unsubscribe, but never trash or delete.[agents.profiles.agent]safety_policy = "full"allowed_accounts = ["work"]allow_send = falseallow_destructive = trueallowed_destructive_actions = ["archive", "unsubscribe"]MCP tools also require explicit confirm=true before send or mutation tools
apply changes.
accounts
Section titled “accounts”Each [accounts.<key>] is a TOML subtable. Required:
name— display name in the sidebaremail— canonical account email and default From for account-key selectionenabled(defaulttrue) — whenfalsethe daemon skips the account on sync. Useful for keeping a dormant account configured without paying its sync cost.
Optional:
color— the account’s colour slot:sky,amber,green,yellow,blue,vermilion,purpleorslate. The daemon gives each account a slot when it is created and keeps it. Setcolorto pick another. Two accounts may share a colour; the tag then tells them apart.tag— one to three letters or digits, shown on the account’s mail wherever a list mixes accounts. Case does not matter; it is stored in uppercase. The default comes from the name: the first letter of each of its first two words, so “Work” isWand “Planetary Escape” isPE. Two accounts cannot share a tag. The daemon ignores a configured tag that another account already holds, whether configured or stored, and logs a warning that names the account. It uses that account’s stored tag instead. The file keeps the value as written. A colour or tag that is not valid is ignored the same way, and the warning lists the allowed values. The default tag is stored when the account is created, so renaming an account does not change it.
[accounts.work]name = "Work"email = "bk@work.example"color = "amber"tag = "W"Sub-tables:
[accounts.<key>.sync]— inbound provider;type = "gmail" | "imap" | "outlook_personal" | "outlook_work" | "fake"[accounts.<key>.send]— outbound provider;type = "gmail" | "smtp" | "outlook_personal" | "outlook_work" | "fake"
The fake provider is a deterministic in-memory adapter used by mxr demo
and the test suite — useful when you want a dry-run install without real credentials.
Gmail sync provider
Section titled “Gmail sync provider”[accounts.personal.sync]type = "gmail"credential_source = "bundled" # bundled | customclient_id = "..." # only when credential_source = "custom"client_secret = "..." # only when credential_source = "custom"token_ref = "gmail:personal" # keychain entry name; auto-setcredential_source = "custom" is the official Gmail v1 recommendation: use
your own Google Cloud project’s client ID/secret. bundled uses the OAuth
client mxr ships when present; treat it as an unverified fallback that may show
Google’s warning screen.
IMAP sync provider
Section titled “IMAP sync provider”[accounts.work.sync]type = "imap"host = "imap.example.com"port = 993username = "me@example.com"auth_required = true # set to false for relays that pre-authenticateuse_tls = truepassword_ref = "imap:work"# tls_cert_sha256 = "<64 hex digits>" # optional, see belowHow IMAP is secured depends on use_tls and port:
use_tls |
Port | Connection | Certificate check |
|---|---|---|---|
true |
anything except 143 (normally 993) | TLS from the first byte | System trust store and hostname, or the tls_cert_sha256 pin |
true |
143 | Plain connect, STARTTLS, then TLS |
Same as above, applied after the upgrade. Refused if the server does not advertise STARTTLS; mxr never continues in plaintext |
false |
any | No encryption | None. Allowed only for loopback hosts (127.0.0.0/8, ::1, localhost); any other host is refused before connecting |
tls_cert_sha256 is the SHA-256 of the server’s leaf certificate (DER), as 64
hex digits; : separators are accepted. When it is set, mxr accepts exactly
that certificate, including a self-signed one, and nothing else. The chain and
hostname are not checked, because the pin replaces them. When it is unset, the
certificate is verified normally. Use it for a local bridge with its own
certificate. mxr accounts test <account> prints the fingerprint the server
presents without authenticating on the inspection connection. This fingerprint
is unverified: check it against the bridge’s own certificate before copying it
into the config. The account test separately attempts a verified sync. A server
that changes its certificate fails
until the pin is updated.
For scripts, mxr accounts --format json test <account> and --format jsonl
include tls_cert_sha256 in the result. A failed certificate check still exits
with an error after printing the result, so you can inspect the fingerprint
before configuring trust.
An implicit TLS connection to a server that answers in plaintext fails with an error that names the mismatch and the fix, instead of a bare “record overflow”.
SMTP send provider
Section titled “SMTP send provider”Same shape as the IMAP block but with the SMTP host/port and
password_ref. auth_required = false is the rare relay case where
the SMTP server accepts the message without credentials.
With use_tls = true, port 465 uses implicit TLS and other ports use
STARTTLS. With use_tls = false, the transport is plaintext; mxr refuses that
combination when auth_required = true so credentials cannot be submitted over
an unencrypted connection.
render
Section titled “render”| Key | Type | Default | Purpose |
|---|---|---|---|
html_command |
string | w3m -dump |
Shell command to render HTML to plain text |
reader_mode |
bool | true |
Default to reader mode when opening a message |
show_reader_stats |
bool | true |
Display word/reading-time on opened messages |
html_remote_content |
bool | true |
Allow remote image fetches in HTML view; every <img> in the message is fetched, tracking pixels included |
search
Section titled “search”default_sortmax_resultsdefault_mode
default_sort and max_results apply to user searches that leave the sort or page size out: mxr search, the TUI search screen, the web /search API and the MCP mxr_search tool. The web app’s search page follows them too until you pick a sort: its Sort control starts at Default. max_results defaults to 50. max_results is the default page size, not a cap, and an explicit --limit or --sort always wins. The daemon reads these values when it starts, so run mxr restart after changing them.
Example:
[search]default_sort = "date_desc"max_results = 50default_mode = "lexical"default_mode may be lexical, hybrid, or semantic.
search.semantic
Section titled “search.semantic”[search.semantic]enabled = trueauto_download_models = trueactive_profile = "bge-small-en-v1.5"max_pending_jobs = 256query_timeout_ms = 1500enabledauto_download_modelsactive_profilemax_pending_jobsquery_timeout_ms
Current runtime meaning:
enabled = false- sync still prepares semantic chunks for changed messages
- embeddings are not generated
- dense retrieval stays off
enabled = true- mxr installs the active local model if needed
- generates embeddings from stored chunks
- rebuilds/uses the dense ANN index
- hybrid/semantic search falls back to lexical ranking if dense retrieval is unavailable or errors
The built-in default is enabled = true, but default_mode remains lexical. Semantic retrieval is used only for requests that ask for hybrid or semantic mode.
Current profiles:
bge-small-en-v1.5multilingual-e5-smallbge-m3
Notes:
- embeddings stay local
- OCR is not used for semantic indexing
- semantic readiness is opportunistic and must not block sync, read, send, or lexical search
max_pending_jobsandquery_timeout_msare currently parsed config fields, not active runtime guarantees yet
snooze
Section titled “snooze”morning_hourevening_hourweekend_dayweekend_hour
logging
Section titled “logging”| Key | Default | Meaning |
|---|---|---|
level |
"info" |
Startup tracing level; RUST_LOG takes precedence. |
max_size_mb |
250 |
Per-file cap in MiB, positive. Oversized records become bounded JSON diagnostics. |
max_files |
10 |
Positive total number of owned text files, including active mxr.log. |
stderr |
true |
Mirror tracing JSON to stderr only when the CLI/foreground daemon owns that output; never protocol stdout or TUI output. |
event_retention_days |
90 |
Days of event and sync history to keep. The daemon prunes older rows once a day; 0 keeps everything. Sync history keeps the newest 50 rows per account. Unsubscribe receipts are never pruned. |
Size/count/stderr changes are read on subsequent writes. Archives use
mxr.<20-digit sequence>.log; the shared .mxr-log.lock is never purged.
Unknown files and symlinks are excluded. Zero/unrepresentable caps fail instead
of disabling bounds. The default named-file budget is 2,500 MiB. See
text logs and purge preview for
64 KiB record limits, reduced-cap behavior, failure and follow semantics.
activity
Section titled “activity”Controls the user-activity log (user_activity table). Strictly local; never transmitted off-device. See the Activity Log guide for the full design.
[activity]enabled = truetrack_link_clicks = false # opt-in; URLs reveal a lottrack_subjects = truetrack_recipient_handles = truetrack_search_queries = true
[activity.retention]ephemeral_days = 30standard_days = 90important_days = 365enabled— global switch. Whenfalse, no new activity rows are written, including forced pause/resume markers.MXR_ACTIVITY=offoverrides enabled config.track_link_clicks— allowlink.clickrows and URL metadata. Defaultfalse. No current producer emits link-click rows; enabling this does not add tracking.track_subjects— keep email subjects incontext_json. Defaulttrue. Flip off if you’d rather not retain message subjects in the audit trail.track_recipient_handles— keep email handles and recipient blocks incontext_jsonand sender-address targets. Defaulttrue. Counts, opaque IDs, folder destinations and rule names remain when disabled.track_search_queries— keep search query text verbatim. Defaulttrue. Flip off for high-sensitivity work.retention.ephemeral_days/standard_days/important_days— daily prune sweep hard-deletes rows older than this. Defaults 30 / 90 / 365.
Restart the daemon after changing enablement or metadata controls. They apply to new entries, including nested metadata from direct recorder calls, not existing rows. Disabled or paused recording also stops Reading engagement; saving Later items and highlights still works.
Verify it’s wired:
mxr activity status # paused state + recent-30d row countmxr activity prune --before 30d --dry-runHard kill at startup:
MXR_ACTIVITY=off mxr daemon # recorder is spawned but writes are droppedappearance
Section titled “appearance”theme
appearance.sidebar, appearance.date_format, appearance.date_format_full,
appearance.subject_max_width and humanizer.apply_to_summaries were retired in
v0.6.125 and no longer do anything. A config file that still sets one keeps
loading; mxr logs a warning once, config keys ignored: no longer used, that
names the keys. mxr config get and mxr config set on a retired key fail with
`appearance.sidebar` was retired and no longer does anything; remove it from config.toml.
Find out whether your file sets one:
grep -nE '^(sidebar|date_format|date_format_full|subject_max_width|apply_to_summaries)\b' "$(mxr config path)"bridge
Section titled “bridge”HTTP bridge configuration.
enabled— start the bridge alongside the daemon (defaulttrue).bind— bind address (default127.0.0.1).port— fixed TCP port for the local web URL (default42829).mxr webfails onEADDRINUSEby default and can opt into walking up with--auto-port. The actual bound port is written to<config_dir>/bridge-portfor clients to discover.cors_allowlist— additional origins (defaults already cover loopback).host_allowlist— additional hostnames for future non-loopback bridge mode; the managed daemon refuses non-loopback binds today.auto_local_token— whentrue(default),GET /api/v1/auth/local-tokenreturns the bridge token to callers whose TCP peer is a loopback IP. Lets the web SPA bootstrap on the same machine without a paste prompt. Set tofalsefor paranoid setups that want strict bearer auth even on loopback. Non-loopback peers never receive the token regardless of this setting.token_path— path to the auth token file. Omit it to use<config_dir>/bridge-tokenfor the active runtime identity.
transports
Section titled “transports”The daemon always serves a Unix domain socket. Additional client transports are
opt-in here. Only the CLI dials tcp:// / cmd://; the TUI, web bridge, and MCP
server use unix:// only.
[transports.tcp]enabled = false # opt-in; when true, bind a loopback TCP listenerbind = "127.0.0.1" # loopback only — 127.0.0.1 or ::1; non-loopback is refusedport = 42830 # default; one above the bridge's 42829transports.tcp.enabled— bind a loopback TCP listener (defaultfalse).transports.tcp.bind— loopback address only; a non-loopback bind is refused at startup.transports.tcp.port— TCP port (default42830).
TCP has no OS-level peer identity, so it requires a bearer token. A client sends
an in-band Authenticate handshake first; until it succeeds the daemon answers
every request with an auth error and sends no events. Connect with:
MXR_DAEMON_ADDR=tcp://127.0.0.1:42830 MXR_DAEMON_TOKEN=… mxr statusThis IPC token is a different secret from the HTTP bridge token: the bridge
hands its token to any loopback caller (GET /api/v1/auth/local-token) to
bootstrap the web SPA, so it must not double as the raw-IPC credential.
Precedence: MXR_DAEMON_TOKEN (env) beats the dedicated file at
<config_dir>/daemon-token (mode 0600, created on first daemon start;
MXR_DAEMON_TOKEN_PATH overrides). The client also refuses to dial a
non-loopback tcp:// address, so the token is never sent to a remote host in
plaintext.
For off-machine access there is no in-daemon remote transport by design; tunnel
over SSH with cmd://:
MXR_DAEMON_ADDR="cmd://ssh -T host mxr daemon dial-stdio" mxr statuscmd:// splits its command on whitespace only — no shell quoting; wrap a command
that needs quoted arguments in a script.
notifications.chimes
Section titled “notifications.chimes”Daemon-side audio feedback for local events and successful actions. Chimes are off by default. Manage them without restarting the daemon:
mxr chimes status --format jsonmxr chimes enablemxr chimes set archived glassmxr chimes test archivedmxr chimes disableSupported events: new-mail, sent, archived, trashed, spam,
snoozed, unsnoozed, reminder, error.
Supported sounds: none, bell, glass, pop, sent, archive,
thud, alert.
The web app reads and writes the same setting (Settings > Sound, or
GET/POST /api/v1/platform/notifications/chimes on the bridge) and plays
sent, archived and snoozed in the browser. For requests that come from
the web app the daemon plays nothing, so a sound never plays twice. See
Sound, key hints and touch.
Optional LLM features (thread summarisation, draft assist). Disabled by default. Speaks the OpenAI Chat Completions schema, so any of these backends works:
- Ollama (local):
http://localhost:11434/v1, no API key - LM Studio (local):
http://localhost:1234/v1, no API key - OpenAI:
https://api.openai.com/v1,OPENAI_API_KEY - Groq:
https://api.groq.com/openai/v1,GROQ_API_KEY - OpenRouter:
https://openrouter.ai/api/v1,OPENROUTER_API_KEY - Together AI, Mistral La Plateforme, etc.
Some model names ignore base_url and api_key_env and go to a hosted
provider with its own key:
model |
Goes to, in order | Key |
|---|---|---|
claude-*, such as claude-haiku-5-5 |
Anthropic, then OpenRouter | mxr llm key set anthropic (or ANTHROPIC_API_KEY), mxr llm key set openrouter (or OPENROUTER_API_KEY) |
gpt-<number>, such as gpt-6-luna |
OpenAI, then OpenRouter | mxr llm key set openai (or OPENAI_API_KEY), then the OpenRouter key |
anthropic/<model> |
OpenRouter | the OpenRouter key |
<vendor>/<model> with the default base_url, for the vendors openai, google, meta-llama, mistralai, deepseek, x-ai, qwen, cohere, perplexity, amazon, nvidia and microsoft |
OpenRouter | the OpenRouter key |
When base_url points at a server off this machine, a gpt-* model goes to
that server instead, and so does a <vendor>/<model> id from that list. With
a base_url on this machine other than the default (LM Studio, another port),
a <vendor>/<model> id goes to base_url, since local servers name some
models that way. So a model id like qwen/qwen3-8b reaches Ollama only when
you change base_url; with the default it goes to OpenRouter.
See Use Claude and Use GPT models.
[llm]enabled = truebase_url = "http://localhost:11434/v1"model = "qwen2.5:3b-instruct"api_key_env = "" # name of the env var; empty = no auth headercontext_window = 8192request_timeout_secs = 120background_request_timeout_secs = 45allow_cloud_relationship_data = false# Shared catalogue for the assistant and compose pickers.models = ["gemma4:latest", "gpt-6-luna", "gpt-5.6-terra", "claude-haiku-5-5", "claude-sonnet-5-5"]
[llm.compose]# Omit to inherit llm.model. A per-draft choice never changes this default.model = "gemma4:latest"
[llm.fallback]# Omit the table for no fallback. Used while base_url is out.model = "gpt-6-luna" # the default when the table is present# context_window = 128000 # defaults to llm.context_windowThe API key is read from api_key_env at runtime and is never persisted
to the config file. Empty api_key_env means no Authorization header
is sent — correct for Ollama and LM Studio.
request_timeout_secs bounds a request you started. background_request_timeout_secs
(default 45) bounds the daemon’s own background work, such as relationship
summaries, so a dead endpoint can’t hold a background
worker for the full foreground wait.
models lists the model ids the assistant and compose pickers offer. The old
assistant_models key still loads and is saved as models. Compose uses
[llm.compose] model as the default for each new draft; omit it to inherit
llm.model. mxr config set llm.compose.model <id> sets it, and
mxr config get llm.compose.model reads it. Use mxr config set llm.compose.model <id> --dry-run to preview the same catalogue-checked change
without writing it. Legacy drafting overrides keep working when this setting
is absent and warn that [llm.compose] model is the replacement.
[llm.fallback] puts a hosted model behind a model that base_url serves.
When base_url is unreachable, times out, is rate limited (408, 429, 529),
returns a server error (5xx), or rejects the key or model (401, 402, 403,
404, or a 400 naming the model), the request goes to the fallback through the
providers in the routing table above (gpt-6-luna: OpenAI, then OpenRouter,
each with a stored key or the provider’s environment variable). Any other
error, such as another 400 or an empty reply, is returned without trying the
fallback. base_url is tried again after a cooldown that starts at one
minute and doubles to 30 minutes (one hour after a key or model error), with
a cheap GET /models check first.
model defaults to gpt-6-luna and must be an id the routing table sends to
a hosted provider with the default base_url: gpt-<number>, claude-*,
anthropic/<model>, or a <vendor>/<model> id from the listed vendors.
context_window defaults to the feature’s own context_window (its
override’s, if it sets one), and prompts are built to fit the smaller of the
two. context_window = 0 is rejected. Relationship features use the fallback
only with allow_cloud_relationship_data = true.
mxr config set llm.fallback.model <id> sets it and refuses an id mxr can’t
route; an empty value removes the table. A bad [llm.fallback] in a
hand-edited file doesn’t stop the daemon or hold back the rest of [llm]: it
runs without the fallback, logs why, mxr llm status prints fallback not used: <reason>, and mxr config set llm.<key> prints the reason after
applying a change. See Fall back to a cloud model.
gist_concurrency (default 1, at most 8) sets how many list-row gists the
daemon writes at once in the background. A local model does best one at a
time; raise it for a hosted endpoint.
allow_cloud_relationship_data = false keeps your wider mail history off any
endpoint that isn’t on this machine. Only localhost, a 127.x.x.x address
or ::1 count as local. A server on your home network or tailnet counts as
cloud, and so does every model in the routing table above, whatever
base_url says. With the setting off, mxr:
- refuses the history features listed under Per-feature overrides on a non-local endpoint;
- keeps them off
[llm.fallback], so they wait forbase_url; - leaves your other mail, relationship summaries and sent-mail habits out of drafting prompts sent to a non-local endpoint;
- marks cloud models unavailable in the assistant’s model picker.
Set it to true only when the provider’s data terms cover mail other people
wrote to you.
mxr config set changes these llm keys on a running daemon without a
restart: llm.enabled, llm.base_url, llm.model, llm.compose.model,
llm.models, llm.api_key_env, llm.context_window,
llm.request_timeout_secs, llm.allow_cloud_relationship_data and
llm.fallback.model. Any other llm key, including
background_request_timeout_secs, gist_concurrency,
fallback.context_window and overrides.*, is refused as an unknown key.
Edit those in config.toml and run mxr restart. If the daemon can’t apply
a change, the command says Restart the daemon to apply: mxr restart.
Use mxr llm status --format json to inspect the running provider, model,
context window, timeout, and whether the configured API-key environment variable
is present. It lists each feature’s model and, for a model in the routing
table, the providers in order with their health. With [llm.fallback] it
shows base_url’s health first, named by its URL, and the fallback’s
providers after it. With [llm.compose] model set, the drafting rows
(draft_assist, draft_new, draft_refine, humanize_rewrite) show the
compose model. When every route is out, status names the one a command you run
would still try once. Status also reports process-local
request outcomes per feature (default for the base model): initially no
observation, then a typed success or failure. A success on one feature does
not clear another feature’s failure, and a provider reload clears the old
outcomes. While background calls are paused after repeated endpoint failures,
status says until when (background_paused_until in JSON). Status never probes the model endpoint. Feature health reports the
same observations; core mail stays usable when an optional model is
unavailable.
The web app’s Settings > LLM panel edits the same keys through the daemon and
reloads the provider immediately after save. background_request_timeout_secs,
gist_concurrency and [llm.fallback] are config-file only; the panel keeps
them as they are.
Per-feature overrides
Section titled “Per-feature overrides”Every LLM-backed feature can override [llm] independently. Useful
when one feature benefits from a different model — for example, you
might run thread summaries through a local 3B model but want
answer-coverage on a smarter cloud model.
[llm.overrides.answer_coverage]enabled = truemodel = "gpt-6-luna" # key from `mxr llm key set openai`An override takes enabled, base_url, model, api_key_env,
context_window and request_timeout_secs. Any field you leave out comes
from [llm]. Any other key in an override table, or a feature name not
listed here, is ignored and named once in the daemon log. Feature keys: summarize (also row gists and mxr triage),
relationship_summary, commitments, draft_assist, draft_new,
draft_refine, humanize_rewrite, answer_coverage,
archive_ask, decision_log, briefing,
delivery_extraction (confirm/enrich for delivery tracking),
and assistant (the assistant, which needs a model that
can call tools, and whose model you can pick from a list, and summarises older messages once a conversation nears
context_window). The old voice_match and expert keys are retired:
voice matching and expert lookup run locally, so mxr ignores those tables and
logs their names once. With [llm.compose] model set, drafts
use that model and the draft_assist, draft_new, draft_refine and
humanize_rewrite overrides are ignored.
relationship_summary, commitments, answer_coverage, archive_ask,
decision_log, briefing and assistant carry
relationship data, so the daemon refuses them on a non-local endpoint unless
allow_cloud_relationship_data = true. The answer_coverage example above
needs that setting to run.
safety
Section titled “safety”Pre-send safety pipeline tuning. See the Pre-send safety guide for the full check inventory and the override-token flow.
The daemon reads [safety] when it starts. Edit config.toml, then run
mxr restart; the running daemon keeps the values it loaded until then.
safety.recipients
Section titled “safety.recipients”[safety.recipients]internal_domains = ["company.com"]sensitive_domains = ["competitor.com"]warn_on_first_time_external = true| Key | Type | Default | Purpose |
|---|---|---|---|
internal_domains |
string[] | [] |
Domains flagged as internal. Body markers like INTERNAL or CONFIDENTIAL paired with a recipient OUTSIDE this list trigger a Blocker. |
sensitive_domains |
string[] | [] |
Any recipient at one of these domains is a Blocker. Common use: known competitors, regulators, journalists, ex-employers — anywhere a misfire would be expensive. |
warn_on_first_time_external |
bool | false |
Warn when sending to a domain you have no prior history with. Cheap nudge that catches “did I get the right alice?” cases. |
safety.tone
Section titled “safety.tone”[safety.tone]formality_delta_threshold = 0.4| Key | Type | Default | Purpose |
|---|---|---|---|
formality_delta_threshold |
float [0.0, 1.0] | 0.4 |
How different the draft’s formality score must be from the recipient’s baseline before the warning fires. 0.0 = always warn (every send vs. baseline). 1.0 = never warn. Lower it if you want stricter checking, raise it to mute noise. Values outside the range are clamped into it. |
Tone match needs at least 3 prior messages to a recipient — fewer than that and the check silently skips (no point warning when there’s no stable baseline to compare against).
deliveries
Section titled “deliveries”Controls package/shipment detection. See the Deliveries guide for the full pipeline.
[deliveries]enabled = trueenabled— scan new mail for deliveries during the post-sync pass. Defaulttrue. Detection is local and cheap; turn it off to skip it entirely. The optional LLM confirm/enrich step is gated separately by[llm](and itsdelivery_extractionoverride) — with no LLM configured, detection still runs heuristics plus checksum-valid tracking numbers.
mxr deliveries scan --since-days 30 --dry-run # preview detection without writingmxr deliveries list # what's been found[modes]archive_on_last_done = trueWhen the last active mode finishes with a conversation, also archive it at
the provider. With false, finishing only changes mode state; provider
archiving stays a separate action. Preview with
mxr modes done THREAD_ID --mode messages --dry-run.
messages
Section titled “messages”[messages]large_thread_recipients = 10recent_days = 30Threads with more than large_thread_recipients recipients go to Updates
unless you wrote in the thread and a later reply is addressed to you.
recent_days bounds the Recent/Quiet window; conversations whose turn it
is and ones brought back by your timers can be older. Explicit corrections
still take precedence. See Messages.
[todo]enabled = truecatchup_days = 14enabled controls automatic task detection. catchup_days sets the
first-run window for older undated work offered in the bounded catch-up.
Use mxr todo catchup to review it. See To do.
records
Section titled “records”[records]enabled = truepdf_prefetch = truepdf_budget_mb = 512pdf_max_file_mb = 15enabled controls automatic record filing and history scanning.
pdf_prefetch downloads record PDFs into the managed attachment cache for
offline reading and text extraction. pdf_budget_mb limits the total
prefetch budget; PDFs larger than pdf_max_file_mb wait until you open
them. Detection is local rules/schema.org processing, not smart-tier model
extraction. See Archive.
Edit these sections in mxr config edit, then restart the daemon with
mxr restart. The CLI’s config set command does not expose every TOML key.
updates
Section titled “updates”When the Updates digest is gathered each day, in your local time.
[updates]cuts = ["08:00", "16:30"]auto_todo_alerts = true-
auto_todo_alerts: defaulttrue. Allows automatic alert to-dos only with genuine receiver evidence, earlier sender history and a fresh unread inbox arrival outside backfill. Current live adapters cannot attest to that evidence and hold creation with an explanation.falsedisables this path; manualtremains available. See Updates. -
cuts: one to fourHH:MMtimes, each once. Default["08:00", "16:30"]. The digest holds what arrived by the latest cut; mail after it waits for the next. An empty list, more than four times, a value that isn’tHH:MMor a time listed twice falls back to the default, and the daemon logs a warning.
mxr updates --format json | jq '.cut' # the cut in use, and every cut of the dayreading
Section titled “reading”Where Reading items open with O: Marginalia. Set
by mxr reading marginalia connect or Settings → Marginalia, which
check the token with Marginalia first.
[reading]marginalia_url = "https://reader.example.com/"marginalia_url: Marginalia’s address. Unset by default, and nothing is sent anywhere. The token is kept in the secrets file, never here.
Custom keybindings
Section titled “Custom keybindings”keys.toml sits beside the file mxr config path prints. Two parts of it apply in the TUI and the web app alike: [actions], which gives an action its own keys, and single_keys, which turns single-character shortcuts off. The daemon reads the file each time a client asks for its keys, so the web app uses a change when it next loads and the TUI when it next starts. The other sections are the TUI’s own.
You don’t have to edit the file by hand. Settings → Keyboard in the web app and mxr keys set, mxr keys reset and mxr keys single-keys write it through the daemon, check the change first, and keep your comments.
Keys for every client
Section titled “Keys for every client”[actions] names an action id from mxr keys and the keys it should have, primary first. They replace the action’s default keys wherever it has keys: every web scope, and in the TUI the mail list, the reader and the modes. [] leaves the action to the palette.
[actions]"mail.archive" = "%" # one key"mail.star" = ["s", "Mod+Shift+s"] # several; Mod is Cmd on a Mac, Ctrl elsewhere and in the TUI"mail.trash" = [] # no key; the palette still runs itmxr keys set mail.archive % --dry-run # what would change, and any conflictmxr keys set mail.archive %mxr keys set mail.trash --nonemxr keys reset mail.archive # back to eA key another action already has in the same place is a conflict: nothing is written, and the message names the other action, so you can give it another key first. Keys the browser keeps (Mod+w, Mod+t, Mod+f and the rest) and keys a terminal can’t send (Ctrl+i, Ctrl+Shift+…) are refused too. The sidebar, the screener and overlays keep their own keys. A mode section or a [mail_list] entry below wins over [actions] for that key in the TUI.
Turning single-key shortcuts off
Section titled “Turning single-key shortcuts off”single_keys = falseThis turns off every shortcut that starts with a single character, such as e, E, # and g i, in both clients (WCAG 2.1.4). Use it with speech input, or if you press keys by accident. Modifier chords (Mod+k, Ctrl-d), Esc, Enter, Space, Tab and the arrows keep working, text fields keep their letters, and an open menu or picker still takes its letters. The palette (Mod+k, or Ctrl-k in the TUI) runs every action. mxr keys single-keys off and the Single-key shortcuts switch in Settings → Keyboard set it; mxr keys marks the keys it turns off.
The TUI’s mail-pane sections
Section titled “The TUI’s mail-pane sections”These sections apply to the TUI’s mail panes, including Search results and preview; they do not replace text-field, modal, sidebar, or other screens’ controls.
Use [mail_list] for lists, [message_view] for a reader containing one message, and [thread_view] for a reader containing multiple messages:
[mail_list]"j" = "move_down""k" = "move_up""Ctrl-g" = "open_tab_6" # open Analytics from a mail list";" = "archive" # replaces e in mail lists"wq" = "trash" # replaces # in mail lists
[message_view]"R" = "toggle_reader_mode""H" = "toggle_html_view"
[thread_view]"E" = "export_thread"Remapping an action removes its old shortcuts in that context. To keep an alias, list it explicitly too (for example, both "e" = "archive" and ";" = "archive"). Other actions keep their defaults unless you reuse their key. To disable a key without replacing it, set its action to "".
These sections cover the mail list and the reader, not the modes: remapping archive here leaves e meaning Done in Now and To do. A chord also reserves its prefix: "ra" = "archive" replaces the single-key r reply shortcut. Avoid overlapping user bindings such as "w" and "wq"; the TUI ignores that context’s overrides rather than choosing an ambiguous action.
Remapping a mode’s keys
Section titled “Remapping a mode’s keys”Now, Messages, To do (with [catchup] and [expired]), Updates, Reading and Archive each have a section of their own. Keys are spelled the way mxr keys prints them (x, g x, Ctrl+d, Escape), and each names an action id from mxr keys --client tui --context <mode>:
[todo]"x" = "todo.done" # tick off with x; e no longer does it in To do"Z" = "" # unbind Z in To do"d d" = "todo.edit" # a sequence of your own
[now]"x" = "now.done"Moving an action to a new key retires its default keys in that mode only. The hint bar shows the key you chose.
Key-string grammar
Section titled “Key-string grammar”- Bare characters:
"j","E","#",";","," - Modifier prefixes:
Ctrl-,Alt-, andShift-. Bare uppercase letters imply Shift. Most terminals sendCtrl-Shift-AasCtrl-aandCtrl-i,Ctrl-m,Ctrl-has Tab, Enter and Backspace, so avoid binding those. - Special keys:
Enter,Esc,Escape,Tab,Space,Up,Down,Left,Right,Home,End,PageUp,PageDown,Backspace, andDelete. - Character chords: concatenate without separators, such as
"gg","wq", or"wqr". Press each next key within four seconds; after 300 ms the TUI lists the keys that can follow. A timeout discards the prefix, and a next key that completes nothing cancels it and runs nothing.
Action names
Section titled “Action names”Bindings reference names registered in crates/tui/src/keybindings.rs. These include navigation, mail mutations, screen switching (open_tab_1–open_tab_6), reader-mode toggles, and the standard chords. Deferred pattern-selection and count-prefix features are not enabled by this file.
Unknown action names and invalid key strings are ignored, leaving their defaults unchanged. mxr keys check lists everything mxr would ignore, and exits non-zero when it finds something. If the file is malformed TOML or contains a non-string action value, the TUI uses defaults for the whole file. The daemon reads single_keys and [actions] from it; the pane and mode sections stay with the TUI.
Reading what’s bound
Section titled “Reading what’s bound”mxr --help # command surface# In the TUI:? # context-aware help modal: (or Ctrl-k) # command palette searches by action nameHelp, the command palette and mail-pane hints show the effective bindings for the focused view. After restarting with the example above, help in a mail list shows ; for Archive and wq for Trash; e and # no longer run those actions there. mxr keys lists the keys with [actions] applied and marks yours (yours); the keybindings reference lists the defaults. The web app follows [actions] and single_keys, not the TUI’s pane and mode sections.
- Runtime account inventory is not identical to config entries.
- Gmail browser-auth accounts may exist at runtime without being editable config-backed entries.
- IMAP/SMTP entries are the main editable config-backed account type.
Receiver authentication for structured To do fields
Section titled “Receiver authentication for structured To do fields”todo.trusted_authentication_services maps exact account IDs to trusted receiver
authserv-id values and defaults to {}. Edit it with mxr config edit and
restart the daemon. For example:
[todo.trusted_authentication_services]"ACCOUNT_ID" = ["mx.example.net"]This setting asserts that the account’s receiving server strips forged
Authentication-Results headers claiming its configured IDs. Configure it only
after the server administrator confirms that boundary. Sender names, sender
domains, raw pass strings and Received headers do not establish trust. The
first matching receiver report must contain an aligned DKIM or SPF pass before
mxr uses structured bill fields. Other accounts remain unknown. This changes
field provenance, never the existing Open email payment action.