Skip to content

Config

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:

Terminal window
mxr config path
mxr status --format json

For 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.

[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]

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 --account
sync_interval = 60 # seconds; how often the daemon polls
hook_timeout = 30 # seconds; max time a shell hook may run
safety_policy = "full" # full | restricted | draft-only | read-only
attachment_dir = "~/mxr/attachments" # optional internal attachment cache override
download_dir = "~/Downloads" # default destination for user-initiated saves
[render]
html_command = "w3m -dump" # how plain-text HTML view is rendered
reader_mode = true # default to reader on open
show_reader_stats = true
html_remote_content = true # allow remote images in HTML view; every img is fetched, pixels included
[search]
default_sort = "date_desc"
max_results = 50
default_mode = "lexical" # lexical | hybrid | semantic
[search.semantic]
enabled = true
auto_download_models = true
active_profile = "bge-small-en-v1.5"
max_pending_jobs = 256
query_timeout_ms = 1500
[snooze]
morning_hour = 9
evening_hour = 18
weekend_day = "saturday"
weekend_hour = 10
[bridge]
enabled = true
bind = "127.0.0.1"
port = 42829 # stable local web URL port
cors_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 daemon
volume = 0.35 # 0.0 .. 1.0
new_mail = "bell"
sent = "sent"
archived = "archive"
trashed = "thud"
spam = "alert"
snoozed = "pop"
unsnoozed = "glass"
reminder = "bell"
error = "alert"
[llm]
enabled = false
base_url = "http://localhost:11434/v1" # Ollama default
model = "qwen2.5:3b-instruct"
api_key_env = "" # name of env var; empty for Ollama / LM Studio
context_window = 8192
request_timeout_secs = 120
allow_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 body
sensitive_domains = ["competitor.com"] # always Blocker
warn_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 = 993
username = "me@work.example.com"
auth_required = true
use_tls = true
[accounts.work.send]
type = "smtp"
host = "smtp.work.example.com"
port = 587
username = "me@work.example.com"
auth_required = true
use_tls = true
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

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.

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 = false
allow_destructive = false
[agents.profiles.mcp]
safety_policy = "read-only"
allowed_accounts = ["personal@example.com"]
allow_send = false
allow_destructive = false

Fields:

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 = false
allow_destructive = true
allowed_destructive_actions = ["archive", "unsubscribe"]

MCP tools also require explicit confirm=true before send or mutation tools apply changes.

Each [accounts.<key>] is a TOML subtable. Required:

  • name — display name in the sidebar
  • email — canonical account email and default From for account-key selection
  • enabled (default true) — when false the 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, purple or slate. The daemon gives each account a slot when it is created and keeps it. Set color to 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” is W and “Planetary Escape” is PE. 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.

[accounts.personal.sync]
type = "gmail"
credential_source = "bundled" # bundled | custom
client_id = "..." # only when credential_source = "custom"
client_secret = "..." # only when credential_source = "custom"
token_ref = "gmail:personal" # keychain entry name; auto-set

credential_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.

[accounts.work.sync]
type = "imap"
host = "imap.example.com"
port = 993
username = "me@example.com"
auth_required = true # set to false for relays that pre-authenticate
use_tls = true
password_ref = "imap:work"
# tls_cert_sha256 = "<64 hex digits>" # optional, see below

How 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”.

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.

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
  • default_sort
  • max_results
  • default_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 = 50
default_mode = "lexical"

default_mode may be lexical, hybrid, or semantic.

[search.semantic]
enabled = true
auto_download_models = true
active_profile = "bge-small-en-v1.5"
max_pending_jobs = 256
query_timeout_ms = 1500
  • enabled
  • auto_download_models
  • active_profile
  • max_pending_jobs
  • query_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.5
  • multilingual-e5-small
  • bge-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_jobs and query_timeout_ms are currently parsed config fields, not active runtime guarantees yet
  • morning_hour
  • evening_hour
  • weekend_day
  • weekend_hour
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.

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 = true
track_link_clicks = false # opt-in; URLs reveal a lot
track_subjects = true
track_recipient_handles = true
track_search_queries = true
[activity.retention]
ephemeral_days = 30
standard_days = 90
important_days = 365
  • enabled — global switch. When false, no new activity rows are written, including forced pause/resume markers. MXR_ACTIVITY=off overrides enabled config.
  • track_link_clicks — allow link.click rows and URL metadata. Default false. No current producer emits link-click rows; enabling this does not add tracking.
  • track_subjects — keep email subjects in context_json. Default true. Flip off if you’d rather not retain message subjects in the audit trail.
  • track_recipient_handles — keep email handles and recipient blocks in context_json and sender-address targets. Default true. Counts, opaque IDs, folder destinations and rule names remain when disabled.
  • track_search_queries — keep search query text verbatim. Default true. 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:

Terminal window
mxr activity status # paused state + recent-30d row count
mxr activity prune --before 30d --dry-run

Hard kill at startup:

Terminal window
MXR_ACTIVITY=off mxr daemon # recorder is spawned but writes are dropped
  • 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:

Terminal window
grep -nE '^(sidebar|date_format|date_format_full|subject_max_width|apply_to_summaries)\b' "$(mxr config path)"

HTTP bridge configuration.

  • enabled — start the bridge alongside the daemon (default true).
  • bind — bind address (default 127.0.0.1).
  • port — fixed TCP port for the local web URL (default 42829). mxr web fails on EADDRINUSE by default and can opt into walking up with --auto-port. The actual bound port is written to <config_dir>/bridge-port for 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 — when true (default), GET /api/v1/auth/local-token returns 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 to false for 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-token for the active runtime identity.

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 listener
bind = "127.0.0.1" # loopback only — 127.0.0.1 or ::1; non-loopback is refused
port = 42830 # default; one above the bridge's 42829
  • transports.tcp.enabled — bind a loopback TCP listener (default false).
  • transports.tcp.bind — loopback address only; a non-loopback bind is refused at startup.
  • transports.tcp.port — TCP port (default 42830).

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:

Terminal window
MXR_DAEMON_ADDR=tcp://127.0.0.1:42830 MXR_DAEMON_TOKEN=… mxr status

This 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://:

Terminal window
MXR_DAEMON_ADDR="cmd://ssh -T host mxr daemon dial-stdio" mxr status

cmd:// splits its command on whitespace only — no shell quoting; wrap a command that needs quoted arguments in a script.

Daemon-side audio feedback for local events and successful actions. Chimes are off by default. Manage them without restarting the daemon:

Terminal window
mxr chimes status --format json
mxr chimes enable
mxr chimes set archived glass
mxr chimes test archived
mxr chimes disable

Supported 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 = true
base_url = "http://localhost:11434/v1"
model = "qwen2.5:3b-instruct"
api_key_env = "" # name of the env var; empty = no auth header
context_window = 8192
request_timeout_secs = 120
background_request_timeout_secs = 45
allow_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_window

The 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 for base_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.

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 = true
model = "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.

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]
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]
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).

Controls package/shipment detection. See the Deliveries guide for the full pipeline.

[deliveries]
enabled = true
  • enabled — scan new mail for deliveries during the post-sync pass. Default true. Detection is local and cheap; turn it off to skip it entirely. The optional LLM confirm/enrich step is gated separately by [llm] (and its delivery_extraction override) — with no LLM configured, detection still runs heuristics plus checksum-valid tracking numbers.
Terminal window
mxr deliveries scan --since-days 30 --dry-run # preview detection without writing
mxr deliveries list # what's been found
[modes]
archive_on_last_done = true

When 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]
large_thread_recipients = 10
recent_days = 30

Threads 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 = true
catchup_days = 14

enabled 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]
enabled = true
pdf_prefetch = true
pdf_budget_mb = 512
pdf_max_file_mb = 15

enabled 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.

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: default true. 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. false disables this path; manual t remains available. See Updates.

  • cuts: one to four HH:MM times, 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’t HH:MM or a time listed twice falls back to the default, and the daemon logs a warning.

Terminal window
mxr updates --format json | jq '.cut' # the cut in use, and every cut of the day

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.

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.

[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 it
Terminal window
mxr keys set mail.archive % --dry-run # what would change, and any conflict
mxr keys set mail.archive %
mxr keys set mail.trash --none
mxr keys reset mail.archive # back to e

A 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.

single_keys = false

This 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.

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.

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.

  • Bare characters: "j", "E", "#", ";", ","
  • Modifier prefixes: Ctrl-, Alt-, and Shift-. Bare uppercase letters imply Shift. Most terminals send Ctrl-Shift-A as Ctrl-a and Ctrl-i, Ctrl-m, Ctrl-h as Tab, Enter and Backspace, so avoid binding those.
  • Special keys: Enter, Esc, Escape, Tab, Space, Up, Down, Left, Right, Home, End, PageUp, PageDown, Backspace, and Delete.
  • 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.

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.

Terminal window
mxr --help # command surface
# In the TUI:
? # context-aware help modal
: (or Ctrl-k) # command palette searches by action name

Help, 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.