# Configuration

akou keeps its settings in one file, `~/.config/akou/config.json`: a JSON object with the dotted keys below, for example `{"asr.segmentPause": 0.8, "api.port": 8476}`. You rarely need to open it. The Settings page in the window changes the common ones and saves on its own, and the command line reads and writes any of them:

```
akou config show                        # every setting, its value and what it does
akou config set user.name "Jordan Lee"  # change one; it is checked before it is saved
akou config unset user.name             # back to the default
```

A key that is unknown, of the wrong type or out of range is refused with a message, and its default is used; the rest of the file still applies. A file that is not JSON is refused whole. Some settings take effect at the next start of akou, and `akou config set` says so when it saves one of them.

The `network.*` settings put the desktop app's history within reach of a phone with an API key; [Server mode](<https://geiserx.github.io/akou/server/#the-desktop-apps-history-on-your-phone>) walks through it.

Keys marked *file only* name a program akou runs or an address your audio or transcripts go to. They are read from the file and never written over the local API, so the API token cannot become a way to run a chosen command or send your calls elsewhere. Keys marked *window or file* can also be set on the Settings page. Secrets, such as `provider.apiKey`, are never shown back; on macOS the API key is kept in the Keychain.

## Environment variables

| Variable | What it does |
| --- | --- |
| `AKOU_HOME` | Moves akou's home folder, and with it the config folder and the recordings. Meant for tests |
| `AKOU_MODELS_DIR` | Overrides `asr.modelsDir`, the folder the speech models live in |
| `AKOU_HEADLESS` | Sets `app.headless`: run with no window |
| `AKOU_SERVER` | Sets `server.enabled`: server mode, with per-key access |
| `AKOU_BEHIND_PROXY` | Sets `server.behind_proxy`: a reverse proxy with TLS is in front of akou. See [Server mode](<https://geiserx.github.io/akou/server/index.md>) |
| `AKOU_ACCELERATOR` | Sets `asr.accelerator`: the GPU the large speech model runs on. See [GPUs and presets](<https://geiserx.github.io/akou/server-hardware/index.md>) |
| `AKOU_URL` | Points the command line and `akou mcp` at a remote akou instead of the app on this machine |
| `AKOU_API_KEY` | The key for `AKOU_URL` |
| `AKOU_API_KEY_FILE` | A file holding the key for `AKOU_URL`, read instead of `AKOU_API_KEY` |
| `AKOU_ALLOW_HTTP` | `1` (or `true`) lets `akou mcp` use a plain `http` `AKOU_URL` on another machine; without it, the key would cross the network unencrypted and it refuses |
| `AKOU_MCP_READONLY` | `1` or `true` makes `akou mcp` list only the tools that change nothing, as `--read-only` does |

## Every setting

The tables below are generated from the settings registry in [src/main/config/schema.ts](<https://github.com/GeiserX/akou/blob/main/src/main/config/schema.ts>), which is the one source of truth; `bun scripts/settings-doc.ts` refreshes them, and `bun run check` fails when they drift. Defaults that depend on the machine are shown for macOS.

### recordings

| Key | Default | What it does |
| --- | --- | --- |
| `recordings.root` | `"~/Recordings/akou"` | Folder that holds a subfolder per workspace, each holding one folder per call. Applies at the next start; calls already recorded stay in the old folder until you move them. Set in the window, the file or with `akou config set` on this computer; an API key cannot set it, since it decides where your calls are recorded. |

### user

| Key | Default | What it does |
| --- | --- | --- |
| `user.name` | `""` | Your name, written into every call and used for the mic channel's label. |

### api

| Key | Default | What it does |
| --- | --- | --- |
| `api.port` | `8476` | Port of the local API on 127.0.0.1. 0 picks a free port; runtime.json has the one in use. |
| `api.bind` (file only) | `""` | Address the API listens on in server mode: 127.0.0.1, 0.0.0.0 or ::, the binds akou's CLI on the same box reaches. Empty: 0.0.0.0. 0.0.0.0 and :: need `server.behind_proxy`. The app always listens on 127.0.0.1. |

### app

| Key | Default | What it does |
| --- | --- | --- |
| `app.headless` | `false` | Run with no window. Selected by the environment, never by command-line arguments. |
| `app.hotkey` | `""` | Global shortcut that starts and stops a call, in accelerator form (`Control+Shift+F9`). Empty: `Option+Command+R` on macOS, `Control+Shift+F9` elsewhere (never `Control+Alt`, which is AltGr on many layouts). |
| `app.floatingIndicator` | `true` | While a call records and the akou window is closed or minimized, a small always-on-top bar with the time, the levels, Mute, Ask and Stop. It shows no transcript text, so it can stay up during a screen share. |
| `app.showOnAgentStart` | `true` | When an agent, the command line or the API starts a call, show the akou window in front, on the desktop you are on, without taking the keyboard from the app you are typing in. |
| `app.openAtLogin` | `false` | Start akou, with no window, when you log in, so the hotkey and the tray are always there. |

### share

| Key | Default | What it does |
| --- | --- | --- |
| `share.bind` | `"tailnet"` | Where a share link listens: `tailnet`, `lan` (plain HTTP, visible to that network) or an IPv4 address. Never every interface unless you type `0.0.0.0`. |
| `share.port` | `8477` | Port of the read-only share link. 0 picks a free port. |

### network

| Key | Default | What it does |
| --- | --- | --- |
| `network.enabled` (window or file) | `false` | The desktop app also listens on `network.bind` for API keys (`akou keys create`), so a phone or another computer reads what each key's scopes allow: a `read` key sees every call, dictation and job. The app's own token is refused there. Server mode ignores it. Applies at the next start. |
| `network.bind` (window or file) | `"tailnet"` | Where the network listener listens: `tailnet` (the tailnet encrypts it; with no tailnet address yet, it looks again every 30 s), `lan` (plain HTTP, visible to that network) or an IPv4 address. Applies at the next start. |
| `network.port` (window or file) | `8478` | Port of the network listener. 0 picks a free port. Applies at the next start. |

### server

| Key | Default | What it does |
| --- | --- | --- |
| `server.enabled` (file only) | `false` | Server mode: per-key access instead of the one token, bound to `api.bind`, for other programs to call over the network. |
| `server.behind_proxy` (file only) | `false` | A reverse proxy in front of akou terminates TLS. Required for any bind that is not loopback; with no `server.public_host`, any Host header is accepted. |
| `server.bazarr` (file only) | `false` | Bazarr's whisper endpoints, `POST /v1/asr` and `POST /v1/detect-language`, with no key: point Bazarr's whisperai endpoint at http://host:8476/v1. Applies at the next start. |
| `server.public_host` (file only) | `""` | The host name clients use (`akou.example`, or with a port). Set: server mode accepts that Host header and loopback only. |
| `server.trusted_proxies` (file only) | `[]` | Addresses or CIDR blocks of the proxies whose X-Forwarded-For is believed for rate limits and audit. From any other peer the TCP address is the source. |
| `server.max_upload_mb` | `512` | Largest upload an upload route takes, in MiB. Every other route keeps the 64 KB JSON cap. |
| `server.max_audio_minutes` | `240` | Longest audio a file job transcribes, in minutes. A longer file fails as `too_long` before it is held in memory. |
| `server.retain_days` | `7` | Days a file job and its result are kept before they are deleted, as a client's delete would. The upload itself is deleted as soon as the job ends. A job submitted with `keep_audio=true` keeps its upload and is never deleted by this: only a client's delete removes it. |
| `server.concurrency` | `1` | File jobs run at once. Each running job has its own Worker with its models loaded and `asr.threads` threads, so keep this times `asr.threads` under the cores, and the memory for that many copies of the model. |
| `server.model_idle_minutes` | `10` | Minutes an idle file-job Worker, a dictation lane's included, keeps its model loaded after its last job, so consecutive jobs pay one model load; then it lets the model and its memory go. A long value keeps a 1 to 3 GB process (Qwen3-ASR's llama-server, or the Worker's models) resident all that time with nothing queued. The desktop app keeps none: it lets a model go as soon as no queued job needs it. 0: let go as soon as no queued job needs it. At most 1440 (a day); a larger value in config.json is refused and the default is used. |
| `server.queue_max` | `1000` | File jobs queued or running at most, across keys. A submit past it is refused with 429 `queue_full` and `Retry-After`. 0: no limit. |
| `server.queue_max_per_key` | `500` | File jobs one key may have queued or running, so one client cannot fill the queue. A submit past it is refused with 429 `queue_full` and `Retry-After`. 0: no limit. |
| `server.default_language` | `"auto"` | The language a file job is transcribed in when its request sends `language: auto` or none, as Telegram-Archive does. A BCP-47 tag such as `es`, or `auto` to detect it. |
| `server.default_diarize` | `false` | Label speakers in a file job whose request has no `diarize` field. A request that sends `diarize: false` gets no labels. |
| `server.default_model` | `"auto"` | The model a file job runs when its request names none (`preset: auto` and no `model`): a preset name or an engine id from the model catalog. `auto`: `best` (Qwen3-ASR) wherever it is downloaded, else `fast` (Parakeet) when that is, else `best` on a GPU with 16 GB of memory and `fast` elsewhere; `GET /v1/server` `auto` says which and why. |
| `server.auto_download` | `true` | What a job naming a model that is not on disk gets. On (the default): it waits while akou downloads the model, each file checked against its pinned SHA-256, then runs. Off: it is refused with 409 `preset_unavailable` and the `akou models pull` line. Download on the Models page and `akou models pull` fetch either way. |
| `server.models_max_gb` | `40` | Largest the models folder may grow through downloads of one model (a job's, or Download on the Models page), in GB (10^9 bytes). 0: no cap. A download that would pass it is refused with 409 `preset_unavailable`, `reason: models_max_gb`. |
| `server.models_unused_days` | `30` | Days a model may go unused before akou deletes it, in the desktop app and in server mode. The default model, any model in use (a job, a worker, the recognizer) and one downloading are never deleted. 0: never delete. |
| `server.remotes` (file only) | `[]` | Other akou servers this one sends jobs to, one entry each: `<url> <key file> [names]`, the key file holding a `jobs` key of that server. A job goes to a remote when this server cannot run it, or first when `names` (presets or model ids, comma-separated, `*` for all) lists it; the client still sees only this server. |
| `server.remotes_overflow` | `false` | What a job a `server.remotes` entry names does when every remote that offers it is busy. Off (the default): it waits for one, so a primary too slow for that preset never runs it. On: it runs here, so a primary that is a good worker itself and its remotes all take a backlog at once. A job this server cannot run waits for a remote either way. |
| `server.admin_password_hash` (file only) | `""` | The web UI's admin password, hashed. Set it with `akou admin set-password`. |
| `server.dictation_slots` | `1` | Workers kept for dictating clients (`interactive=true`): they never take queued jobs, and a dictation is never refused by the queue limits. 0: a dictation queues like any job. Applies at the next start. |
| `server.dictation_engine` | `"auto"` | The preset or model a dictating client's request runs when it names none. `auto`: the server's default. |
| `server.wyoming` (file only) | `false` | Home Assistant's Wyoming protocol on `server.wyoming_port`, bound where the API binds (127.0.0.1 in the app). No key and no TLS: keep the port on your network. Applies at the next start. |
| `server.wyoming_port` (file only) | `10300` | Port of the Wyoming listener. 0 picks a free port (tests). Applies at the next start. |

### capture

| Key | Default | What it does |
| --- | --- | --- |
| `capture.helper` (file only) | `[]` | Command that starts the capture helper, before its own arguments. Empty: the akou-capture bundled with the app, else the one on PATH. |
| `capture.mic` | `"default"` | Microphone: `default`, `none`, or a device id (akou cannot list the ids yet). |
| `capture.call` | `"system"` | Call audio: `system` (the whole computer), `none`, or `app:<id>[,<id>]` for only those apps. An app id is a bundle id on macOS (`us.zoom.xos`) and an executable name without `.exe`, or a process id, on Windows; Linux records the whole computer only. Any other value is refused when saved, and one already in the file is replaced by `system` at load with a warning. |
| `capture.warmStartSeconds` | `3` | Wait for the helper to report capturing, after a helper has captured once this run. |
| `capture.coldStartSeconds` | `10` | Wait for the helper to report capturing on the first start of a run. |
| `capture.stopSeconds` | `5` | How long a helper may take to stop before it is killed. |
| `capture.stallSeconds` | `10` | No packet at all for this long means the helper is wedged and is restarted. |
| `capture.deadRestartSeconds` | `60` | A dead call side that lasts this long restarts the helper. |
| `capture.queueSeconds` | `600` | Audio kept per channel for the recognizer when it falls behind. |

### asr

| Key | Default | What it does |
| --- | --- | --- |
| `asr.modelsDir` (window or file) | `"~/Library/Application Support/akou/models"` | Folder the speech models are downloaded into and loaded from. Set it in the akou window or the config file, never over the API: akou runs the speech programs kept in it. |
| `asr.threads` | `2` | Threads per recognizer. |
| `asr.diarizer` | `"nemotron"` | Who speaks when on the call channel: `nemotron` (NVIDIA Nemotron 3 Diarization, live at 2 s latency and in the final pass, through the akou-diarize helper) or `embeddings` (voice-embedding clusters live, pyannote in the final pass). `akou models pull` fetches what the choice needs; takes effect at the next start. |
| `asr.accelerator` | `"auto"` | The GPU the large speech model (Qwen3-ASR, on llama-server) runs on: `auto`, `cpu`, `metal`, `vulkan` (Intel and AMD, and NVIDIA without CUDA), `cuda`, `sycl` (Intel oneAPI) or `rocm` (AMD). `auto` picks Metal on Apple silicon, CUDA for an NVIDIA card, Vulkan for an Intel or AMD GPU, else the CPU, and never SYCL or ROCm. A build that cannot open the GPU falls back to the CPU; `GET /v1/server` says which runs and why. Natively it picks which pinned llama-server build to download; an image runs the build it carries. Natively `sycl` and `rocm` download llama.cpp's SYCL or ROCm build, which needs Intel's oneAPI or AMD's ROCm runtime on the host. `asr.llamaServer` runs an own build instead. Applies to the next job that starts llama-server. |
| `asr.parakeet.decoding` | `"greedy"` | How Parakeet decodes, live and in the final pass: `greedy` (the default) or `beam`. Beam search also steers decoding toward the call's vocabulary at boost 1.5, but on some meeting audio it returns whole spans empty. Vocabulary correction when reading and after the call applies with either. Takes effect at the next start. |
| `asr.languages` | `[]` | The languages Qwen3-ASR may choose among when a job's language is `auto`, as ISO 639 codes (for example `en` and `es`). An answer in another language is replaced by the decode, forced into one of these, that the model scores higher; a no-speech answer stays empty. Empty: whatever language the model names. |
| `asr.llamaServer` (file only) | `[]` | Command that starts an own llama-server for Qwen3-ASR, before the arguments akou adds (for example a build compiled on this machine). With `asr.accelerator` set to `cpu`, akou adds `--device none`, so the build must accept `--device` (llama.cpp from late 2024 on). Empty: the pinned llama-server release for this platform and `asr.accelerator`, downloaded like a model. |
| `asr.diarizeHelper` (file only) | `[]` | Command that starts the diarization helper, before its own arguments. Empty: the akou-diarize bundled with the app, else the one on PATH. |
| `asr.live` | `"auto"` | The model that writes the live transcript of a call: `auto`, or a model's id (`nemotron-3.5-560`, `nemotron-3.5-1120`, `nemotron-en-560`, `parakeet-tdt-0.6b-v3-fp32`, or another chunk size of a streaming Nemotron: `nemotron-en-80`, `nemotron-en-160`, `nemotron-en-1120`, `nemotron-3.5-80`, `nemotron-3.5-160`, `nemotron-3.5-320`), as the Record row's Live panel saves it. `nemotron`: streaming Nemotron (`asr.live.engine` picks which), a word shown is never taken back. `parakeet`: Parakeet re-decodes each stretch between pauses, and words on screen can change. `auto` picks `nemotron` when its model is downloaded, else `parakeet`. A model that is not downloaded never runs. `upgrade`, the old value, is read as `nemotron` with `asr.review.model` `qwen`, and saved that way. `akou start --live` sets it for one call. A change applies from the next call; a running call keeps its model. |
| `asr.review.model` | `"none"` | A second pass during a call, `none` or a model's id (`qwen3-asr-1.7b`, `parakeet-tdt-0.6b-v3-fp32`; `qwen` and `parakeet` name the same): every `asr.review.everySeconds`, the sentences Nemotron finished since the last review are decoded again, whole, and the new words replace the live lines once. `qwen`: Qwen3-ASR, the most accurate, about 10 to 13 GB of memory during a call; it needs its llama-server, and it goes off for the rest of a call it cannot keep up with. The window offers it only on a machine with a GPU for it and 16 GB of memory; set here, it runs anyway. `parakeet`: Parakeet, on the processor, with at most about 100 MB more memory. `none`: the live lines stay as Nemotron wrote them. It reviews Nemotron's lines only, so a call whose live model is Parakeet runs none. A line someone edited, or fixed a word on, keeps their text. `akou start --review` sets it for one call. A change applies from the next call. |
| `asr.final.model` | `"auto"` | The model that writes the final transcript after a call: `auto`, a model's id (`qwen3-asr-1.7b`, `parakeet-tdt-0.6b-v3-fp32`; `qwen` and `parakeet` name the same), or `fusion`. `qwen`: Qwen3-ASR on its llama-server, the most accurate; it gives no word times, so each line keeps the times of the stretch it was cut from. While the pass runs it holds about 3 GB of memory and the GPU when there is one. Without a GPU it decodes on the processor, much slower, and a pass gets half the call's length plus 300 s before it is stopped as stuck, so on such a machine a long call can fail: set `parakeet` there. One Qwen pass runs at a time; another waits for it. `parakeet`: Parakeet, on the processor. `auto` picks `qwen` whenever its model and its llama-server are downloaded, else `parakeet`. A model that is not downloaded never runs: the setting falls back to the other model and says why in the log, and with neither downloaded no pass runs. On Qwen the pass does not need Parakeet on disk. Speaker labels are the same with either. A Qwen that cannot start, or fails twice in a row, fails the pass, and `akou finalize --force` runs it again. `akou finalize --model` sets it for one run, and is refused when that model is not downloaded; a pass stopped by a quit runs again at the next start on this setting's model. `fusion`: the `fusion` preset's engines (`asr.final.engines`, joined by `asr.fusion`) each decode the whole call, one after another, and their words are combined, as a file job on that preset; slower, by about one pass per engine, and more accurate. While it runs, the pass also holds every piece of the call's audio, about 0.25 GB per hour of a two-channel call, on top of the engines; `asr.memoryBudgetMb` does not count it. Of the list, the engines that are downloaded run and the rest are named in the pass's result as not downloaded; with none downloaded the pass runs what `auto` runs. `akou start --final` sets it for one call. A change applies from the next pass. |
| `asr.final.engines` | `[]` | The engines of the `fusion` preset's pass, in priority order: the order the fuser breaks ties in. Every engine decodes every piece of the file, one engine after another so one GPU model is loaded at a time, and the fuser (`asr.fusion`) joins their words. Ids: `qwen3-asr-1.7b`, `whisper-large-v3`, `parakeet-tdt-0.6b-v3-fp32`, `canary-1b-v2`. Empty: the preset's own, `qwen3-asr-1.7b`, `whisper-large-v3`, `parakeet-tdt-0.6b-v3-fp32`, the three the benchmark measured best together; add `canary-1b-v2` for a fourth. With no job language, the first engine that identifies languages decodes first and the others are given the language it heard. An engine that cannot load, or fails, is left out and the job goes on with the rest; the result's `engine.fusion` says which ran and which were left out, and why. A call's final pass runs the same list when `asr.final.model` (or the call's `--final`) is `fusion`. Applies to the next job and the next pass. |
| `asr.fusion` | `"rover-conf"` | How the `fusion` preset joins its engines' words: `rover-conf` (the default) aligns them and keeps, word by word, the one most engines wrote, weighted by each engine's confidence in it; `rover-freq` counts engines only, and loses words past three engines; `first` keeps the first engine's text and uses the others only where it failed. Needs no provider. The fusers that ask a language model (`llm-pick`, `llm-free`) are not built. |
| `asr.memoryBudgetMb` | `0` | Memory, MB, an engine of the `fusion` preset may need: an engine whose estimate (its model files and a fifth more) is over it is left out of the pass and the result says so. The engines load one at a time, so each is held against the budget alone. 0: 60 % of this machine's memory. |
| `asr.review.everySeconds` | `60` | How often the second pass (`asr.review.model`) reviews, seconds: the reviewed text lands about this long after the words. `akou start --review-every` sets it for one call. |
| `asr.live.engine` | `"auto"` | The streaming model that writes the live transcript when `asr.live` resolves to `nemotron`: `auto` picks by `asr.languages` (English only: `nemotron-en-560`; Spanish only: `nemotron-3.5-1120`; anything else: `nemotron-3.5-560`, which follows a switch of language), or name one. The other chunk sizes (`nemotron-en-80`, `nemotron-en-160`, `nemotron-en-1120`, `nemotron-3.5-80`, `nemotron-3.5-160`, `nemotron-3.5-320`) run only when named: a shorter chunk writes a word sooner, and `auto` never picks one. A word it shows is never taken back. Its model is fetched with `akou models pull <name>`; while none is downloaded, live lines come from Parakeet re-decoding pauses. A change applies from the next call; a running call keeps its model. |
| `asr.segmentPause` | `0.7` | Silence that closes a live segment, seconds. Must be below `asr.segmentWindow`. |
| `asr.segmentWindow` | `12` | Longest live segment, seconds. |
| `asr.modelIdleMinutes` | `5` | Let go of the speech models the live recognizer loaded after this many minutes with no call and no dictation, to get their memory back. Each loads again at its next use: the first dictation after that waits about 1 to 2 s for its streaming model. A model a dictation warm-up loaded at start or after a call goes the same way. On a server the streaming model loaded at start goes the same way when no live client comes. A long value keeps about 1 to 2 GB resident with nothing in use. 0: as soon as nothing uses them; at most 1440 (a day), and a larger value in config.json is refused and the default is used. |
| `asr.warmAtStart` | `"off"` | Load the live models when the app starts instead of when a call starts. `off` (the default) loads nothing ahead: a call loads its streaming model as it starts, which on a busy M-series Mac ended before the call's first sentence did. `auto` loads the streaming model a call runs (Nemotron, about 1.9 GB) when at least 4 GB of memory is available, for a machine where that load is slow. `on` loads it and Parakeet too (about 2 GB more), whatever the memory; a call decodes on Parakeet only with Parakeet as its live model or its second pass. Once loaded, the memory is read every minute, and below 1.5 GB available the models are let go while no call or dictation uses them. Once let go, here or by `asr.modelIdleMinutes`, they load at their next use. Takes effect at the next start. |
| `asr.qwenIdleMinutes` | `10` | Stop the Qwen3-ASR server kept warm for dictation after this many idle minutes, to get its memory back (about 3 GB); the next dictation starts it again and waits a few seconds for it. 0: never. |

### provider

| Key | Default | What it does |
| --- | --- | --- |
| `provider.kind` | `"harness"` | What answers questions and writes enhanced notes: your own Claude Code or Codex (`harness`), an OpenAI-compatible server, the Anthropic API with your key, a program you name in `provider.command` (`command`), or `none` (excerpts only). With `none`, an agent following the call can still answer the ask box (`ask.agentWaitSeconds`). |
| `provider.harness` | `"auto"` | Which harness `harness` runs. `auto`: Claude Code if found, else Codex. |
| `provider.harnessPath` (file only) | `""` | Pin the harness program by absolute path. Empty: look it up on PATH and through the login shell. |
| `provider.command` (file only) | `[]` | With `provider.kind` `command`: the program and its arguments, as a list, run with no shell. The prompt goes on stdin as plain text and stdin is then closed; the answer is what it prints on stdout. `{system}`, `{question}`, `{call}`, `{ask}` and `{task}` inside an argument are replaced (the system prompt goes at the top of stdin when no argument has `{system}`), and the same values are in AKOU\_QUESTION, AKOU\_CALL\_ID, AKOU\_ASK\_ID and AKOU\_TASK. A non-zero exit fails the run, with the last line of stderr as the reason. Set it in the config file only. |
| `provider.commandLabel` | `""` | The name the window shows for `provider.command` in "answered by" and when it did not answer. Empty: the program's file name. |
| `provider.baseUrl` (window or file) | `""` | Server address for `openai-compatible` (Ollama: `http://127.0.0.1:11434/v1`), or another Anthropic API address. Set it in the akou window or the config file, never over the API: it decides where your key and transcripts are sent. |
| `provider.model` | `""` | Model id for `openai-compatible` (required) and `anthropic` (empty: the default model). |
| `provider.apiKey` | `""` | API key for `openai-compatible` (optional) or `anthropic` (required). On macOS it is saved in the Keychain, never in the config file; elsewhere in the config file. Never shown back or logged. |
| `provider.timeoutSeconds` | `60` | How long an answer may take before akou shows the excerpts instead and says why. |
| `provider.harnessResume` | `false` | Reuse one Claude Code session for follow-up questions on a call (`--resume`), sending only what is new since the last question. Off until measured to cut the tokens per follow-up by at least 40 % (docs/providers.md). With it on, Claude Code keeps those sessions in its own history. |

### memo

| Key | Default | What it does |
| --- | --- | --- |
| `memo.provider` | `"auto"` | Whether the configured provider keeps the rolling memo during a call, every few minutes of new speech. `auto`: on for `openai-compatible` and `anthropic`, off for `harness` and `command`, because it would run your subscription unattended; `on`: the harness too; `off`: never. An agent can always write it with `akou_memo_put`. |

### ask

| Key | Default | What it does |
| --- | --- | --- |
| `ask.agentWaitSeconds` | `30` | When an agent is following the call (its `akou events -f` watch includes `ask`), how long a question typed in the ask box waits for that agent to answer it before akou's own provider runs. 0: never wait for an agent. An agent's answer that comes later is still added to the card. |

### agent

| Key | Default | What it does |
| --- | --- | --- |
| `agent.summary_every_minutes` | `10` | How often an agent following a live call (the `akou` skill) may post a summary of it, in minutes: it reads this once when the call starts and never posts more often. 0: no summaries, only answers, health warnings and mentions of your name. |

### export

| Key | Default | What it does |
| --- | --- | --- |
| `export.dir` | `""` | Folder finished calls are exported into, one subfolder per workspace: Markdown with frontmatter, the event log and the audio. Empty: no export until you set it. Set in the window, the file or with `akou config set` on this computer; an API key cannot set it, since it decides where your transcripts are written. |
| `export.audio` | `"link"` | How the export carries the audio: a link to the call's file, a copy, or nothing. |

### hooks

| Key | Default | What it does |
| --- | --- | --- |
| `hooks` (file only) | `[]` | Commands run after a call, each given the call as JSON on stdin: `[{"stage": "call.ended" \\| "final.done" \\| "enhanced", "command": "…", "timeoutSec": 600, "workspace": "work"}]`. File only: they are programs akou runs. |

### webhook

| Key | Default | What it does |
| --- | --- | --- |
| `webhook.url` (file only) | `""` | Address the call is POSTed to at every hand-off stage, signed with `webhook.secret`. Empty: off. File only: it decides where your transcripts are sent. |
| `webhook.secret` | `""` | Secret for the webhook's HMAC-SHA256 signatures: `X-Akou-Signature` over the body, and `X-Akou-Signature-V2` over `<X-Akou-Delivery>.<X-Akou-Timestamp>.<body>`, which lets a receiver refuse a replay. The webhook stays off until it is set. Never shown back or logged. |

### vocab

| Key | Default | What it does |
| --- | --- | --- |
| `vocab.extraFiles` | `[]` | Extra vocabulary files layered over the global and workspace files. |
| `vocab.languages` | `[]` | Languages whose word lists tell a real word from a mishearing, so a vocabulary file never "corrects" a real word. Empty: every list akou ships (en, es). A language the recognizer detects in a call is added. |

### dictation

| Key | Default | What it does |
| --- | --- | --- |
| `dictation.enabled` | `false` | Dictation: hold the dictation key, speak, and the text is inserted where the cursor is (docs/ux/DICTATION.md). Off: the helper's dictate process is not started and no key is taken. |
| `dictation.activation` | `"hold-or-toggle"` | How the dictation key works: `hold-or-toggle` (a press of 300 ms or more is push-to-talk, a shorter tap latches listening on until the next tap), `hold` (push-to-talk only) or `toggle` (a tap starts, the next tap stops). |
| `dictation.hotkey` | `""` | The dictation key: a modifier alone with its side (`RightCommand`, `RightControl`, `RightOption`, `RightShift`, the Left ones, `Fn`) or a chord (`Control+Shift+Space`). Empty: `RightCommand` on macOS, `RightControl` on Windows, `Control+Shift+Space` on Linux, where the desktop's shortcut portal binds chords only. A change applies at once; a key the helper cannot bind is refused and the old one stays. |
| `dictation.hotkeyFixLast` | `""` | Opens the last dictation in the draft box to correct it and teach akou the word. Empty: Shift held before a modifier-only dictation key goes down (`Shift+RightCommand`), else `Control+Shift+Period`. |
| `dictation.hotkeyDraft` | `""` | A second key that dictates into the draft box instead of the app, so you read the text before it goes anywhere. Empty: none. |
| `dictation.hotkeyPasteLast` | `""` | Inserts the last dictation's text again. Empty: none. |
| `dictation.silenceStopSeconds` | `30` | A latched dictation (tapped on, not held) stops after this many seconds without speech, and its audio is still transcribed. 0: never. |
| `dictation.maxMinutes` | `20` | Any dictation stops at this length, with a warning a minute before; its audio is still transcribed. |
| `dictation.mic` | `""` | The microphone dictation listens on, a device id from `GET /devices`. Empty: the system default. |
| `dictation.preferBuiltInOverBluetooth` | `true` | When the default microphone is a Bluetooth headset and the built-in one is there, dictate on the built-in one, so the headset keeps its good sound profile. |
| `dictation.warmMic` | `"auto"` | How long the microphone stays open. `auto`: from the first press until 30 s after each dictation, so a quick follow-up keeps its first syllable; `always`: while dictation is on; `off`: only while the key is down. Never kept open on a Bluetooth microphone. |
| `dictation.engine` | `"auto"` | What decodes a dictation. `fast`: Parakeet, about 0.1 s for 5 s of speech, once it is downloaded (`akou models pull fast`; a Mac with room for Qwen gets none by default); `best`: Qwen3-ASR, kept warm while dictation is on, falling back to fast when it fails or is too slow, and downloaded when missing (fast until it lands); `auto`: what `dictation.final` names (`live` by default: the streaming model's words); `remote`: another akou (`dictation.remote.url`), with no local model needed. |
| `dictation.final` | `"live"` | The text a dictation inserts, while `dictation.engine` is `auto` (`fast`, `best` and `remote` there win; the Dictation page sets both). `live`, the default and the fastest: the words the streaming model showed as you spoke, inserted the moment you let go, with no second decode, and less accurate than Parakeet; while no streaming model is downloaded, Parakeet inserts. `parakeet`: Parakeet decodes the whole recording at the release, with your word list. `qwen`: Qwen3-ASR, the most accurate, kept warm while dictation is on, as `dictation.engine` `best`. Whatever this says, the words while you speak come from the streaming model when one is downloaded (`akou models pull nemotron-3.5-560`), else from Parakeet twice a second. |
| `dictation.localTimeoutSeconds` | `10` | How long a local `best` may take, plus 0.2 s per second of audio, before the dictation is decoded with `fast` instead and says so. |
| `dictation.remote.url` (window or file) | `""` | The other akou a `remote` dictation is sent to: an `https` address, or `http` to a loopback, private or Tailscale address only. Set it in the akou window or the config file, never over the API: it decides where your dictation audio goes. |
| `dictation.remote.key` | `""` | A `jobs` key of the remote akou, sent as the bearer of every remote dictation. Never shown back or logged; applies to the next dictation. |
| `dictation.remote.fallback` | `"local"` | When the remote gives no transcript: `local` decodes on this machine and says so; `error` shows the error with Retry, Copy and Open draft. With no local model installed it is `error`. |
| `dictation.remote.timeoutSeconds` | `6` | How long the remote may take before any audio, plus 0.25 s per second of audio, before the fallback runs. |
| `dictation.language` | `"auto"` | The language of a dictation: `auto` lets the engine choose among `dictation.languages`; a code (`en`) forces it on `best` and on a remote. `fast` picks the language itself. |
| `dictation.languages` | `[]` | The languages an `auto` dictation may choose among. Empty: `asr.languages`, so editing this never changes how calls are transcribed. |
| `dictation.glossary` | `"off"` | Send your learned dictation words to the recognizer as context. Off until a measured evaluation shows it helps without inventing names; learned words are always applied as replacements either way. |
| `dictation.glossaryMax` | `24` | The most learned words sent as context, by recency and use; 24 is what the decoder and the remote route take. |
| `dictation.insert` | `"paste"` | How the text goes in: `paste` through the clipboard, which comes back afterwards; `type` as key presses, for remote desktops and fields that refuse a paste (a text with a line break is pasted, so no Return is pressed); `clipboard` only, and you paste. |
| `dictation.sendKey` | `"Enter"` | The key pressed to send after the text is in, once the app has read it: on Enter during a dictation, Ctrl+Enter in the draft box, or after every dictation with `dictation.sendAlways`. `none`: never. |
| `dictation.sendAlways` | `false` | Press the send key after every direct dictation. |
| `dictation.restoreClipboard` | `true` | Put the old clipboard back once the app has read the dictation. Off: the dictation stays in the clipboard. |
| `dictation.smartSpacing` | `true` | Add the spaces around the text, and lower-case its first word mid-sentence, from the text around the cursor. |
| `dictation.trailingSpace` | `false` | Where the text around the cursor cannot be read, end every dictation with a space. |
| `dictation.spokenPunctuation` | `false` | Replace spoken punctuation (`comma`, `new line`; Spanish `coma`, `nueva línea`) when it stands alone between pauses. Off until measured, since both engines punctuate already and `period` is often just a word. |
| `dictation.fillers` | `true` | Leave out filler words (`um`, `uh`; Spanish `eh`, `este` alone) from the inserted text; history keeps what was said. |
| `dictation.spokenSend` | `false` | A dictation ending in `send it` (Spanish `envíalo`) leaves those words out and presses the send key. |
| `dictation.format` | `"off"` | `provider`: pass the text through your configured provider first, with the prompt `dictation.formatPrompt`, to fix punctuation and casing. History keeps the raw text; a provider past the timeout is skipped. It runs on Retry and on every clip sent to `POST /v1/dictations` (`akou dictate FILE`) too, so a script posting clips asks the provider once per clip. |
| `dictation.formatPrompt` | `"default"` | The formatting prompt: `default`, or the name of a file in `dictation-prompts/` in the config folder, without `.md`. |
| `dictation.formatTimeoutSeconds` | `0` | How long the formatting pass may take before the raw text is inserted. 0: 15 s for Claude Code, 4 s for an API or a local model. |
| `dictation.muteMedia` | `false` | Pause playing media while you dictate, through the system's media controls, and resume only what akou paused. Linux, and Windows (not yet checked with a real player); macOS lets no app see what another one is playing, so on a Mac it does nothing yet. |
| `dictation.learn` | `"ask"` | When you fix a word akou heard wrong: `ask` offers to learn it once, and ignoring the offer changes nothing; `auto` learns it with an Undo; `off` never looks. |
| `dictation.readField` | `true` | Read the field you dictated into, for smart spacing and to learn from your fixes there. Never a password field or a terminal; on macOS only once the Accessibility grant the paste needs is there. |
| `dictation.learn.audioCheck` | `true` | Before offering a word, decode the dictation again with it on Qwen3-ASR and offer it only if the audio agrees. Where Qwen3-ASR does not run here, the offer says it was not checked. |
| `dictation.apps` | `[]` | Per-app dictation rules, matched on the app that had the keyboard: `[{"app": "com.example.chat", "mode": "draft-send", "insert": "paste", "sendKey": "Enter", "engine": "auto", "language": "en", "format": "off"}]`. `app` is a bundle id (macOS), an executable name (Windows) or a window class (Linux); `name`, optional, is the name of the app the rule is shown by (`Slack`) and is never matched; a field left out follows the global setting. `mode`: `draft` opens the draft box instead of inserting, `draft-send` too with Enter there pressing the send key. |
| `dictation.pill` | `"top"` | Where the dictation pill shows `listening` and `transcribing`: `top` is the island at the top centre of the display. Off by default on Linux, where a compositor may give the pill the keyboard and the text would land in it, so turn it on there knowingly; the tray and the sounds carry the state instead. |
| `dictation.pillPreview` | `true` | Show the words as you speak on the pill's island. akou cannot hide its windows from screen capture yet (DK-P3), so a screen share shows them too: turn this off before sharing your screen if that matters. |
| `dictation.sounds` | `"auto"` | Cues at start, stop, cancel and done. `auto`: `soft` while the pill is off, silent while it shows, so a dictation is never both silent and invisible. |
| `dictation.retainDays` | `30` | Days a dictation's text and audio are kept; older ones leave only a tombstone. 0: only the last one, for paste last and fix last. |
| `dictation.keepAudio` | `true` | Keep each dictation's audio, as Opus at about 180 KB a minute, for Retry and for checking a learned word. Off: deleted once the offer to learn is closed. |
