# Server mode

akou also runs as a self-hosted transcription server: one Docker image on linux/amd64 and linux/arm64, running the same core as the desktop app. A program uploads an audio file, gets a job id back at once, and reads one result with text, language, words, segments and the engine that made it, by long-poll, by an event feed, or by a signed webhook. The server also speaks the OpenAI transcription endpoint, `POST /v1/audio/transcriptions`, so a program written for OpenAI's speech-to-text can point at it instead. It also speaks the Wyoming protocol, for Home Assistant Assist, and Bazarr's `/asr`, each one setting away ([Home Assistant](<#home-assistant>), [Bazarr](<#bazarr>)). There is no akou cloud and no relay: the server is your own box, reached by your own programs.

You do not need server mode to transcribe a file on your own Mac: the desktop app takes `akou transcribe FILE` with its own token ([Usage](<https://geiserx.github.io/akou/usage/#transcribing-a-file>)). Server mode is for other programs and other machines, with keys.

The steps below cover the image, the models, the first start and the keys. [GPUs and presets](<https://geiserx.github.io/akou/server-hardware/index.md>) covers the GPU images, the `best` preset and a large backlog.

## Running the image

[ux/SERVER.md](<https://github.com/GeiserX/akou/blob/main/docs/ux/SERVER.md>) has the design. The image is `drumsergio/akou`, tagged with each release (`drumsergio/akou:1.7.6` today; use the current release in the commands below), built from the [Dockerfile](<https://github.com/GeiserX/akou/blob/main/Dockerfile>) for linux/amd64 and linux/arm64, with `-vulkan` and `-cuda` variants for a GPU ([A GPU](<https://geiserx.github.io/akou/server-hardware/#a-gpu>)). There is no `latest` tag: name the version you want.

The server runs as an unprivileged user, uid 1000, keeps its settings, keys and jobs under `/data` and the models under `/models`. Both must be writable by uid 1000, `/models` too even when every model is already in it: the pull and the server write downloads and the models' `usage.json` there. Named volumes, as below, already are. A bind-mounted folder in place of a volume must belong to uid 1000 (`chown 1000:1000` it on the host), and a read-only mount (`:ro`) does not work: the pull stops with exit 70 and the server with exit 77, both naming the folder and `EROFS`.

Pull the models into their volume first, so the first start is not a 3.0 GB download. No server needs to run for this.

The speaker model is Nemotron by default, and that needs no step. Only to use pyannote (`asr.diarizer` `embeddings`) instead, set it on the data volume before the pull; without it the pull fetches Nemotron. Skip this on a volume whose models are already pulled for Nemotron: with it the pull fetches pyannote too.

```
docker run --rm -v akou-data:/data --entrypoint sh drumsergio/akou:1.7.6 -c \
  'mkdir -p /data/.config/akou && echo "{ \"asr.diarizer\": \"embeddings\" }" > /data/.config/akou/config.json'
```

Then pull. Mount the data volume too, since the pull reads `asr.diarizer` from the settings there:

```
docker run --rm -v akou-data:/data -v akou-models:/models drumsergio/akou:1.7.6 models pull fast
```

`fast` fetches everything the server loads before it transcribes: Parakeet TDT 0.6B v3, the voice-activity model and the two speaker models (Nemotron 3 Diarization and TitaNet; pyannote in place of Nemotron with `asr.diarizer` set to `embeddings`). A second run checks every file's SHA-256 and downloads nothing. `akou models pull MODEL` fetches one model by the id `akou models list` shows.

`best` is the other preset with an engine: Qwen3-ASR-1.7B, run by llama.cpp's `llama-server`, with the same speaker models when a job asks for speakers. `models pull best` fetches Qwen (2.5 GB), the llama-server build for this machine and the speaker models, and leaves Parakeet out. Without the pull, the first `best` job fetches them. A model stays loaded for 10 minutes after its last job, so a run of jobs loads it once, and then its memory comes back; `server.model_idle_minutes` sets that time, and 0 lets it go once no queued job needs it. See [The best preset](<https://geiserx.github.io/akou/server-hardware/#the-best-preset>) for where it runs fast.

Inside a container akou listens on every address, and it refuses to start that way (exit 78) until you say a reverse proxy with TLS is in front of it, because akou has no TLS of its own. Say it with `AKOU_BEHIND_PROXY=true`, which sets `server.behind_proxy`, and publish the port on this machine's loopback only, for the proxy to reach:

```
docker run -d --name akou -e AKOU_BEHIND_PROXY=true -p 127.0.0.1:8476:8476 \
  -v akou-data:/data -v akou-models:/models drumsergio/akou:1.7.6
```

`curl -s http://127.0.0.1:8476/healthz` answers `{"ok":true,…,"models_ready":true}` once the models of `server.default_model` are found (a server with only `best` pulled is ready without Parakeet). The server decodes any audio file with the ffmpeg inside the image, and `docker stop` ends it cleanly.

Every program that sends jobs needs its own key. Create one in the running container, with a `jobs` scope and every host its `callback_url` may name:

```
docker exec akou akou keys create --name archive --scope jobs --callback-host telegram-viewer
```

It prints the `ak_` API key and the `whsec_` webhook secret once, and never again: give the key to the program as its bearer token, and the secret to whatever checks the signed callbacks. The key works at once, with no restart. Repeat `--callback-host` for each host; `*` allows any public host, but a callback to a private address, such as another container by its name, needs that host named. A key with no callback host submits jobs and reads the event feed, and a submit that names a `callback_url` is refused with 422 `callback_not_allowed`. `akou keys list` and `akou keys revoke ID` manage them the same way. To change the hosts of a key a program already uses, run `akou keys update ID --callback-host HOST ...`: the key, its secret and its jobs stay, and the server uses the new hosts from the next request. Each key edit, and each job, is a line in the server's log (`key.created`, `key.updated`, `key.revoked`, `job.created`, `job.done`, `job.failed`), never with the audio or the text.

akou keeps a job, its result and its events for `server.retain_days` (default 7), counted from the job's creation; `GET /v1/server` answers the number as `retain_days`. Once that time passes, or a client deletes the job, its id answers `410 Gone` with `retain_days` in the body, so a program can tell a job it must submit again from an id it got wrong, which answers `404`. The [OpenAPI file](<https://github.com/GeiserX/akou/blob/main/docs/api/openapi.json>) describes every job route.

To run it beside [Telegram-Archive](<https://github.com/GeiserX/Telegram-Archive>), use the compose file in [examples/compose/telegram-archive](<https://github.com/GeiserX/akou/tree/main/examples/compose/telegram-archive/>) and the one-time setup in [ux/SERVER.md section 12.5](<https://github.com/GeiserX/akou/blob/main/docs/ux/SERVER.md#125-one-compose-file-for-both>).

Without Docker, run `bun src/main/cli/cli.ts serve` in a source checkout. That is `akou serve`, the same server in the foreground. The single-file `akou` CLI runs `akou serve` too, on Linux x64 and arm64 and on macOS. It carries no speech engine, so it answers the API but cannot transcribe, and it says so: at start, in `/healthz` (503, `models_ready: false` and a `reason`), and by refusing a job or a live session at once with `no_engine`. Its `GET /v1/server` lists no installed engine, and to another akou's probe (which sends an `akou-forwarded` header) no job capability and no available preset, so another akou that names it in `server.remotes` sees it down and sends it nothing, even when it is a front end. With `server.remotes` of its own it is a front end: it takes the jobs those remotes offer and sends every one there, and `/healthz` is 200 while an up remote takes a job that names no model. A job another akou forwards to it is refused with a 422 `no_engine`, since a forwarded job is never forwarded again. A job a server with an engine left queued on the same home is ended with `no_engine` when it was to run on that server (a dictation, or a job another akou forwarded) or when there is no `server.remotes`. One only a remote could run waits for a remote, as it did before. Any other goes to a remote that offers it, and is ended with `no_engine` once every remote has answered a probe, or failed one, and none has offered it. A server with an engine likewise offers another akou's probe only the presets it runs itself, never those its own remotes offer, since it would refuse such a job.

`akou serve` binds every address by default too, so on a plain machine it refuses to start (exit 78) until you choose. Put `{ "api.bind": "127.0.0.1" }` in `~/.config/akou/config.json` to serve this machine only, or set `server.behind_proxy` to `true` once a reverse proxy with TLS is in front of it.

## A reverse proxy in front

akou has no TLS of its own, so a reverse proxy terminates it. Three things matter, and the blocks below set all three. Uploads are large: the proxy's body limit must be at least `server.max_upload_mb` (512 MiB by default). The event feed (`GET /v1/events` with `Accept: text/event-stream`) and the streaming answers are Server-Sent Events, so the proxy must pass each event on at once instead of filling a buffer first. And a long-poll (`?wait=60`) holds a request for up to 60 seconds with no bytes, so the proxy's read timeout must be longer. The live door (`GET /v1/live`, below) is a WebSocket, so the proxy must pass the upgrade and keep a quiet socket open; akou pings an idle socket and closes it after two minutes without an answer. In akou's settings, set `server.behind_proxy` to `true`, `server.public_host` to the name clients use, and `server.trusted_proxies` to the proxy's address, so the client's own address reaches the audit lines and the rate limits. Once `server.public_host` is set, akou answers `403 bad_host` to any other name, so containers that reach it by its service name (`http://akou:8476`, as the compose example does) must go through the public name instead, or leave `server.public_host` empty.

Caddy passes events on, holds long requests and passes WebSockets through by default; it only needs the body limit:

```
akou.example {
    request_body {
        max_size 512MiB
    }
    reverse_proxy 127.0.0.1:8476 {
        flush_interval -1
    }
}
```

nginx needs each of them said, the WebSocket's `Upgrade` and `Connection` headers included:

```
map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

server {
    listen 443 ssl;
    server_name akou.example;
    ssl_certificate     /etc/ssl/akou.example.crt;
    ssl_certificate_key /etc/ssl/akou.example.key;

    client_max_body_size 512m;

    location / {
        proxy_pass http://127.0.0.1:8476;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_request_buffering off;
        proxy_buffering off;
        proxy_read_timeout 300s;
        proxy_send_timeout 300s;
    }
}
```

If you raise `server.max_upload_mb`, raise `max_size` or `client_max_body_size` with it. Then `curl https://akou.example/v1/server` answers the server's description.

## A phone or another live client

A client that records, such as a phone, gets two things from a server: the words while it records, from `GET /v1/live`, and the transcript of record once it stops, from a job. Its recording stays its own until the job has it, so a dropped connection costs a gap in the live words, never audio.

**Live words.** Open a WebSocket to `wss://akou.example/v1/live` with `Authorization: Bearer <key>` on the upgrade request; any key reaches it. A missing, wrong or revoked key gets a plain 401 answer, never a socket. `GET /v1/server` says whether it works here: `capabilities.live`, and `live.engines` lists the streaming models on disk (`akou models pull nemotron-3.5-560` fetches one). On a server, akou loads the streaming model a `hello` with no language opens at start, so the first session does not wait for it.

Text frames are JSON, binary frames are audio:

| From | Message | What it says |
| --- | --- | --- |
| client | `{"type":"hello","v":1,"codec":"ogg-opus","language":"auto","model":"auto"}` | First, once. `codec` is `ogg-opus` or `pcm16`; `language` is `auto` or a BCP 47 tag, and picks the model as a call's languages do (`en`: `nemotron-en-560`, `es`: `nemotron-3.5-1120`, else `nemotron-3.5-560`), among the models on disk; `model` names one instead |
| server | `{"type":"ready","engine","lang","tier_ms","load_ms"}` | The stream is open. `tier_ms` is how far behind the audio a word can come |
| client | binary | With `ogg-opus`, exactly one Ogg page per frame, the bytes the client appends to its own file: the OpusHead page, the OpusTags page, then the audio pages in order, mono. With `pcm16`, raw 16 kHz 16-bit little-endian samples (for tests and measurements). At most 64 KB a frame, and at most 30 s of audio the model has not decoded yet: a client that sends faster is closed with 4400 `too_fast` |
| server | `{"type":"words","tokens":[{"text":" hola","t":1.23,"conf":0.91}]}` | The model's tokens as it gives them, append-only: a token is never taken back. A token with a leading space starts a word. `t` is seconds into the recording |
| client | `{"type":"stop"}` | The end: the server sends the last words, then `{"type":"closed"}`, and closes with 1000 |
| server | `{"type":"error","code","message"}` | A refusal, then a close: 4400 for a message or page that is not valid (`bad_message`, `bad_page`, `too_fast`, `unknown_model`, `unsupported_language`), 4401 `key_revoked`, 4409 `engine_busy`, 4500 `stream_lost`, 4503 `no_live_engine` |

A server holds one streaming model at a time, so while a session is open, a `hello` that resolves to another model is refused with 4409; one that resolves to the same model runs beside it. A key revoked while its session is open closes it with 4401 within about a second, whether or not the client is sending.

There is no resume. A new socket is a new session: send `hello`, the OpusHead and OpusTags pages again, then the pages from where the recording is now. The server places the words on the recording's timeline from the first audio page's granule position, so `t` stays seconds into the file across reconnects; the pages sent while the connection was down are in the file, and the job covers them. Opus at 16 kHz, 24 kbit/s VBR and 20 ms frames, in pages of 200 ms, is about 11 MB an hour on the socket (a minute of speech measured 178 KB), against 115 MB for `pcm16`.

`bun scripts/live-client.ts FILE --codec ogg-opus --pace realtime` streams a file the way a client records it and prints the words with their times, for a check against a server: `AKOU_URL` and `AKOU_API_KEY` name the server and the key, and `ffmpeg` converts a file that is not Ogg Opus.

**The recording, kept.** At the end, upload the file as a job: `POST /v1/jobs` with `keep_audio=true`, an `Idempotency-Key` header of the recording's own id (a retried upload gets the first job back), and `metadata` for what the client files it under, such as `{"workspace": "home", "recording_id": "…"}`, which every job answer carries back. A kept job keeps its upload after it ends, `GET /v1/jobs/{id}/audio` serves it back byte for byte (with `Range`, so a player can seek), and `server.retain_days` never removes it: the job, its result, its events and its audio stay until a client deletes the job. The job's `keep_audio` says whether the server keeps it, so a client deletes its own copy only once it reads `true`. The words with times come from `GET /v1/jobs/{id}/result`.

## The desktop app's history on your phone

The desktop app can let a phone, or another computer, read its calls, dictations and file jobs with an API key, as the window shows them. It is off until you turn it on. The network side takes keys only, so the app's own token never leaves the machine.

1. Make a key on the Mac. Give the phone a `read` key; add `jobs` only if it records to that machine; never `admin`. `read` sees every call, dictation and job, with transcripts, summaries, notes and kept audio, and changes nothing. A phone that also uploads its recordings here gets both:

```
akou keys create --name iphone --scope read --scope jobs
```

It prints the `ak_` key once. The key lives in `keys.json` beside the app's settings, and `akou keys list` and `akou keys revoke ID` manage it as on a server.

1. Turn the listener on in the window's settings (Advanced, Server mode) or in `~/.config/akou/config.json`, then quit and open akou again. [Configuration](<https://geiserx.github.io/akou/configuration/#network>) lists the three settings.

```
{ "network.enabled": true }
```

By default it listens on this Mac's tailnet address, port 8478, and the log says where (`network: listening on http://100.x.y.z:8478/v1`). The tailnet encrypts the traffic. With no tailnet address yet, as when Tailscale starts after akou, the app logs one line and looks again every 30 s until it can listen. Set `network.bind` to `lan` to listen on the Mac's private LAN address instead. That is plain HTTP, readable by anyone on that network. An IPv4 address names one address exactly. `network.port` moves the port.

1. On the phone, add the server as `http://<the Mac's tailnet name or address>:8478` with the key. `GET /v1/keys/me` tells a client which scopes its key holds, so it shows the history only to a key that may read it.

A `read` key on any route that changes something, or on settings, keys, models or quit, gets 403. The app's own token gets 401 there. A refused key is a `key.refused` line in the app's log, with the key's first characters and the address it came from. The listener stops when the app quits. In server mode the `network.*` settings do nothing, since the server already listens where `api.bind` says.

## Home Assistant

Home Assistant's Wyoming integration adds akou as a speech-to-text engine for Assist, by host and port. Turn the listener on with `AKOU_WYOMING=true` (the `server.wyoming` setting), publish its port (`server.wyoming_port`, 10300) where Home Assistant can reach it, and add the Wyoming integration with akou's host and that port. The protocol has no key and no TLS, so keep the port on your own network. See `server.wyoming` in [Configuration](<https://geiserx.github.io/akou/configuration/index.md>) for how it binds.

With `server.auto_download` on (the default), the first utterance after you turn on a preset that is not downloaded yet waits for the download, and Home Assistant may hit its 300-second pipeline timeout once. After a new preset is installed, reload the Wyoming entry in Home Assistant: it reads the list of languages once, at setup.

## Translation into English

A job can give its speech in English instead of in the language spoken. Three doors take it:

- `POST /v1/jobs` with `task=translate` and `language` set to the source (an ISO code such as `es`, or `auto`).
- `POST /v1/audio/translations`, OpenAI's translation endpoint: `file`, `model`, `prompt` (read by Whisper only; Canary takes none), `temperature` and `response_format`, plus `language`, which OpenAI's request lacks. Without it the source is `auto`. Any other field answers 400 `unknown_field`.
- Bazarr's `POST /v1/asr?task=translate`.

The source language picks the engine:

- **Canary-1b-v2** for the 25 European languages it reads (Spanish, French, German, Italian, Portuguese and the rest of Parakeet's list).
- **Whisper large-v3** for every other language it reads, such as Japanese, and for `auto`, since only Whisper can work out the source for itself.
- `model` may name either one. Any other model answers 422 `bad_field`; Canary with `auto` or with a language it does not read answers 422 `unsupported_language`.
- A language neither engine reads answers 422 `unsupported_language`. `GET /v1/server` lists the ones they read in `translate_languages`, and `capabilities.translate` says the server takes the task.

The result's `language` is `en`, its `source_language` is the source (the one Whisper detected on `auto`) and its `task` is `translate`. Segments keep their times, so subtitles come out of it as from any job, but neither engine gives word times: `words` have `s` and `e` null. A line's times come from the voice-activity pieces the audio is cut into, a few seconds each.

Why Canary first: it trades a little accuracy for speed. On three 10-minute European film clips scored against the films' own English subtitles, Whisper scored higher BLEU on every clip (pooled 24.4 against 22.1, a significant gap, p=0.04), and the two did not differ significantly on chrF (48.9 against 48.4, p=0.17). Canary was 8.8 to 9.6 times faster on a Mac's Metal GPU (real-time factor 0.020 to 0.030 against 0.176 to 0.272) and used 1.4 GB against 2.3 GB. Over music and noise Whisper wrote ten lines that nobody said in 30 minutes of audio; Canary wrote none. To get Whisper's accuracy for a European language, name it: `model=whisper-large-v3`.

Where `asr.accelerator` runs Qwen on Vulkan or the CPU, both translate engines run on the CPU: on an Intel integrated GPU, Vulkan was slower than the CPU for both (Whisper at 10.2 times real time against 3.2, Canary 0.31 against 0.26). A discrete card on Vulkan is not measured. Canary runs at about 0.3 times real time there and Whisper at about 3, so on such a box send Whisper only what Canary cannot translate.

Both models are downloaded on first use (Canary 1.14 GB, Whisper 1.67 GB) unless `server.auto_download` is off, load with the job, stay loaded across a batch and are freed after `server.model_idle_minutes` with nothing to do. A cancelled job stops the decode in flight and frees the engine.

## Bazarr

Bazarr's Whisper provider sends each video's audio to `POST /v1/asr` and gets an SRT back, and asks `POST /v1/detect-language` which language a track is in. akou answers both once `server.bazarr` is on. Set it with `AKOU_BAZARR=true` on the container, or in the config file; the API cannot turn it on, since these two routes take jobs with no key. Off, both answer 404.

In Bazarr, under Settings, Providers, Whisper, set the endpoint to **`http://akou:8476/v1`**, with the `/v1`. Without it the request goes to the web UI, not the API, and Bazarr shows "Invalid subtitle". Bazarr sends no key, and anyone who reaches the port can send jobs, so keep the port on your own network. A key sent as `Authorization: Bearer` is honoured, but Bazarr cannot send one.

Bazarr sends `Host: akou:8476`. akou accepts that with `server.behind_proxy` on, as the container above has it, while `server.public_host` is empty. With `server.public_host` set to your proxy's name, other names get `403 bad_host`: set it to `akou:8476` instead, or point Bazarr at the public name.

Each request is one job on `server.default_model`, in the language Bazarr asks for, deleted once the subtitle is sent. Cues hold at most 42 characters and keep the audio's own times. A track with no speech, or a stretch of one, gets no cue: akou returns an empty subtitle rather than inventing a sentence from the noise. A film can take a while: Bazarr waits up to its read timeout, and if it hangs up first, akou cancels the job, so set Bazarr's timeout above your longest film's transcription time.

`task=translate`, which Bazarr sends when it wants English subtitles for audio in another language, gives an English SRT from the language Bazarr names, as described in [Translation into English](<#translation-into-english>). A language neither translation engine reads answers 422 and writes a `bazarr:` warning line in akou's log.

Two things do not work, on purpose:

- **Language detection without Qwen.** `/detect-language` transcribes the first 30 seconds under the `best` preset, whose Qwen model names the language. That cap is on Bazarr's raw PCM: with `encode=true`, which Bazarr never sends, the whole file is decoded. The first call downloads Qwen (2.5 GB) unless `akou models pull best` ran first; with `server.auto_download` off and Qwen missing, akou answers 409 and Bazarr marks the detection failed.
- **Test Connection.** Bazarr's button calls `GET /status` on the host, which akou does not answer, so it never turns green. Check the endpoint with a request of Bazarr's shape instead:

```
ffmpeg -i sample.mkv -f s16le -acodec pcm_s16le -ac 1 -ar 16000 sample.pcm
curl -A Subliminal/2.1 -F "audio_file=@sample.pcm;filename=audio_file" \
  "http://127.0.0.1:8476/v1/asr?task=transcribe&language=en&output=srt&encode=false"
```

Bazarr reads only the body of an answer, so any refusal (a full queue, a missing model, a file too long) becomes "Invalid subtitle" there. Each one is also a `bazarr:` warning line in akou's log, with the error code.

## A Mac as the server

Docker on a Mac has no Metal, so on a Mac the server runs natively, from a source checkout at the release tag. The single-file `akou` CLI cannot transcribe, as above. You need [Bun](<https://bun.sh>) at the version in `.bun-version`, and ffmpeg for anything but a 16 kHz WAV (`brew install ffmpeg`):

```
git clone --branch v1.7.6 https://github.com/GeiserX/akou.git && cd akou
bun install --frozen-lockfile
bun src/main/cli/cli.ts models pull fast
bun src/main/cli/cli.ts models pull best   # Qwen3-ASR and its Metal llama-server, for the best preset
bun src/main/cli/cli.ts serve
```

It keeps its settings, keys and jobs in `~/.config/akou` and the models in `~/Library/Application Support/akou/models`.

Two limits refuse long recordings by default. `server.max_upload_mb` is 512 MiB, which is less than a long meeting video, and `server.max_audio_minutes` is 240. For long meetings, raise both in `~/.config/akou/config.json`, for example `{ "server.max_upload_mb": 2048, "server.max_audio_minutes": 360 }`, and restart the server.

Speaker labels (`diarize`) with Nemotron, the default speaker model, run in the `akou-diarize` helper, which the app carries and a source checkout does not; `models pull` does not fetch it. Download `akou-diarize-<version>-darwin-arm64.tar.gz` from the release, unpack it, and put `akou-diarize` on the server's `PATH`, or set `asr.diarizeHelper` to its path in `~/.config/akou/config.json`, for example `{ "asr.diarizeHelper": ["/Users/YOU/bin/akou-diarize"] }`. The app's release zip carries it too, at `akou.app/Contents/Resources/app/bun/akou-diarize`. Releases up to 0.5.4 have no such file: take it from the zip, or build it from the checkout with Rust 1.88 or newer (`cargo build --locked --release --manifest-path native/akou-diarize/Cargo.toml`). Or set `asr.diarizer` to `embeddings`, which needs no helper. Without either, a job that asks for `diarize` fails with `diarize_unavailable` and says the same.

To reach it from another machine, put a proxy with TLS in front of it (a `tailscale serve` of port 8476 on a tailnet works) and set `{ "api.bind": "127.0.0.1", "server.behind_proxy": true }` in `~/.config/akou/config.json`.

To start it at boot, with no one logged in, save this as `/Library/LaunchDaemons/io.github.geiserx.akou.serve.plist` with your user name, the checkout's path and Bun's path filled in, then run `sudo launchctl bootstrap system /Library/LaunchDaemons/io.github.geiserx.akou.serve.plist`:

```
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key><string>io.github.geiserx.akou.serve</string>
  <key>UserName</key><string>YOU</string>
  <key>WorkingDirectory</key><string>/Users/YOU/akou</string>
  <key>ProgramArguments</key>
  <array>
    <string>/Users/YOU/.bun/bin/bun</string>
    <string>src/main/cli/cli.ts</string>
    <string>serve</string>
  </array>
  <key>EnvironmentVariables</key>
  <dict>
    <key>HOME</key><string>/Users/YOU</string>
    <key>PATH</key><string>/opt/homebrew/bin:/usr/bin:/bin</string>
    <key>MallocLargeCache</key><string>0</string>
  </dict>
  <key>RunAtLoad</key><true/>
  <key>KeepAlive</key><true/>
  <key>StandardErrorPath</key><string>/Users/YOU/Library/Logs/akou-serve.log</string>
</dict>
</plist>
```

`MallocLargeCache` set to `0` turns off macOS's large-allocation cache, which otherwise keeps about 550 MB of a released model in the server's memory after every unload; the desktop app sets the same in its `Info.plist` and its login item. A server started without it, by an older plist or from a shell, starts itself again once with it, on the same pid. `KeepAlive` starts it again if it stops; `sudo launchctl bootout system/io.github.geiserx.akou.serve` stops it for good. Started this way, with no one logged in, it still runs `best` on Metal: `GET /v1/server` shows `accelerator.active` as `metal`. After a reboot, check it came back with:

```
curl -s http://127.0.0.1:8476/healthz
```

which answers `{"ok":true,…,"models_ready":true}` once the models a job with no `model` runs (`server.default_model`, its helpers, and the speaker models when `server.default_diarize` is on) are on disk, nothing is loading, and the live recognizer did not fail to load the default's model (only Parakeet, when the default runs it, is tracked), or once a remote that is up takes those jobs (see [Sending jobs to another akou](<#sending-jobs-to-another-akou>)). If it answers nothing, the log is the `StandardErrorPath` file.

## Sending jobs to another akou

An akou server can hand jobs to other akou servers, for example a container that sends `best` to a Mac mini with a GPU, while its clients keep talking to it alone. [ux/SERVER.md section 14](<https://github.com/GeiserX/akou/blob/main/docs/ux/SERVER.md#14-sending-jobs-to-another-akou>) has the design. On the remote, make a `jobs` key for the server that will send it jobs:

```
akou keys create --name primary --scope jobs
```

On the sending server, save the printed `ak_` key in a file only the server's user can read (in the container, under `/data`, owned by uid 1000, mode 0600), and name the remote in `config.json` with the URL, the key file and, optionally, the presets to send there first:

```
{ "server.remotes": ["https://mini.example /data/remotes/mini.key best"] }
```

Restart the server. `GET /v1/server`, asked with a key, then lists the remote under `remotes` with its state (`up`, `down` or `refused`) and the presets it offers, and a preset a remote offers shows as available (except to another akou's probe, which marks itself with the `akou-forwarded` header: a job it forwards is never forwarded again, so it is offered only what this server runs itself). A job for a preset this server cannot run goes to a remote that offers it; one for a preset the entry names goes there first and runs here while the remote is down; everything else runs here. A remote that goes down leaves its jobs queued, never failed, until it or another remote that offers them is back.

A remote holds two of this server's jobs at a time: the one it runs and the next. When every remote an entry names is busy, a job for that preset waits for one by default, which is right when this server is too slow to run it. When this server is a good worker itself, set `{ "server.remotes_overflow": true }`: the job then runs here instead, so this server and all its remotes work through a backlog at once. A job this server cannot run still waits for a remote, and right after a start a job waits until every remote it names has answered its first probe, since one that has not may have room. Changing the setting over the API routes the waiting jobs at once.

## The command line against a server

The CLI and `akou mcp` talk to a remote akou when `AKOU_URL` is set. The key comes from `AKOU_API_KEY`, or from a file named by `AKOU_API_KEY_FILE`, never from a flag:

```
export AKOU_URL=https://akou.example
export AKOU_API_KEY_FILE=~/.config/akou/remote.key
akou transcribe note.ogg --preset best
akou jobs list
```

`akou transcribe` uploads the file, waits for the job and prints the transcript; on a server the job is deleted once the text is printed, so it does not stay in `akou jobs list` there. Without `AKOU_URL` the same commands go to the desktop app on this machine, which runs the job itself.

With `AKOU_URL` set, akou never looks for the app on this machine and never starts it. A server that refuses the connection, or answers nothing within the request's time, exits 69 and names `AKOU_URL`; a wrong key exits 77. `akou quit` refuses to run, since it stops only the app on this machine, and `akou doctor` reports the server it reaches. `AKOU_API_KEY_FILE` may start with `~/`, as `docker -e` and a systemd unit pass it unexpanded.
