Getting started

Welcome. This walks the config.toml settings, top to bottom. You only set what you change (every section has defaults), so skip what you don't need. Edit it all in the browser on the Config page, then hit Reload. Secrets never go in this file (passwords and tokens live in your OS keyring).

One rule worth saying once: nothing leaves your machine unless you turn it on. The sections below are in the order most people set them.

Mail providers

Each mail provider says how to set itself up, below, in its own words and with a config.toml snippet to start from. Use the ones you need. The password or sign-in for each goes through the provider's own command (oaken PROVIDER auth) and lands in your OS keyring, never in this file.

[plugins.fake]

Check: the account shows up on the Status page under Connected accounts.

Local AI [plugins.ollama] and [ai]

Oaken runs a local Ollama by default, so analysis stays on the machine. Pull the models first (ollama pull nomic-embed-text and your chat model), then name them in [ai]. The default chat model is small on purpose; set a bigger one for better analysis if your machine can carry it. [plugins.ollama] only tunes the connection, and allow_remote stays false unless you really mean to reach off-machine.

[ai]
embed_model = "nomic-embed-text"
llm_model = "qwen2.5:3b"   # bump this for better analysis
allow_remote = false

Check: the Jobs page shows the embed and enrich stages moving, not stuck.

Sync schedule [sync]

How often a new account pulls. The default is every 15 minutes. Mind your provider's quota (that is what min_interval_seconds guards). Set timezone to your own if you use quiet hours or cron schedules.

[sync]
interval_seconds = 900     # every 15 minutes
timezone = "UTC"
max_concurrent = 2

Local API [api]

How the CLI and other local clients reach core. It binds loopback only. Leave port = 0 and it picks a free one. Turn mcp = true on to let a model talk to your mail over MCP on the same listener (its own token).

[api]
port = 0        # 0 = pick a free port
mcp = false     # true mounts the MCP server at /mcp

External agents [swarm]

Off by default, and the one switch to think twice about. Handing a job to an external agent sends that job's mail text to it (and to its provider, if it is hosted). So you opt in one job kind at a time: it stays off until both enabled = true and allowed_kinds is non-empty.

[swarm]
enabled = false
allowed_kinds = []   # e.g. ["ingest.enrich"]

Read state [read_state] and [ui]

Whether opening or summarizing a message marks it read. Leave auto_mark on for normal behavior; turn it off and only explicit mark read/unread counts.

[read_state]
auto_mark = true

[ui]
mark_read_delay_ms = 2000   # how long a message stays open before it counts as read

Logging [log]

Start at INFO. If you run the daemon detached it has no terminal, so set a file to keep its logs. Drop to DEBUG when something is wrong and you want to see the why.

[log]
level = "INFO"      # DEBUG when debugging
format = "console"  # or "json"
file = "oaken.log"

That is the whole file. Edit it on Config, Test, Save, Reload. The full guide (install, keyring, the daemon) lives in the docs.