Configuration

OpenASR stores all configuration, models, and local state under a single home directory. Nothing in this directory is synced to any server; there is no telemetry.

Home directory

The home directory resolves in this order:

OPENASR_HOME environment variable, if set and non-empty.
$HOME/.openasr (Linux/macOS) or %USERPROFILE%/.openasr (Windows).

If neither is resolvable, OpenASR exits with: Could not determine the OpenASR home directory. Set OPENASR_HOME to a writable directory.

Directory layout

~/.openasr/
├── config.json              # settings and preferences
├── apikeys.json             # API key store (hashes only)
├── catalog.json             # cached model catalog
├── pairing-registry.json    # device pairing registry (remote-compute)
├── tls-identity.json        # generated self-signed TLS identity
├── models/                  # installed .oasr model packs
├── history/                 # transcription/live history
└── diarize/
    └── voiceprints.json     # speaker voice-match profiles (embeddings only)

`openasr config`

Read and write the four CLI-settable keys in config.json.

openasr config list              # print saved config
openasr config get <key>         # print one value
openasr config set <key> <value> # save one value
openasr config unset <key>       # remove a value (reverts to default)

Settable keys

Key	Description	Default
`default_model`	Model id for transcription. Validated against the model registry on set.	`qwen3-asr-0.6b`
`default_backend`	Inference backend. Only `native` or `mock` accepted.	`native`
`media.ffmpeg_bin`	Path to an ffmpeg binary.	(none)
`download_source`	Model download mirror: `auto`, `hf`, `hf-mirror`, or `weights`.	`auto`

Setting an unknown key prints: Unknown config key '<key>'. Use one of: default_model, default_backend, media.ffmpeg_bin, download_source.

Preferences

config.json also contains a preferences object managed by the desktop app and the server’s PUT /v1/config endpoint — these fields are not settable via openasr config set. Notable preferences include history_retention (default last5), idle_unload (default 10m), inference_threads (1–256), diarize, word_timestamps, and UI settings like theme and density. See openasr doctor or the desktop app for current values.

Environment variables

Environment variables override their corresponding config-file or flag values. Only the user-facing variables are listed here; internal debug and per-model tuning variables are not part of the public contract.

Variable	Purpose	Notes
`OPENASR_HOME`	Override the home directory.
`OPENASR_MODEL`	Default model id for `transcribe`, `live`, and `serve`.	Same as `-m/--model`.
`OPENASR_ADDR`	Bind address for `openasr serve`.	Default `127.0.0.1:8080`.
`OPENASR_ASSUME_YES`	Auto-confirm missing-model downloads.	Same as `-y/--yes`. Truthy: `1`, `true`, `yes`, `on`.
`OPENASR_OFFLINE`	Never download; fail if the model is missing.	Same as `--offline`/`--no-pull`.
`OPENASR_FFMPEG_BIN`	Path to an ffmpeg binary.	Checked before the `media.ffmpeg_bin` config key.
`OPENASR_DOWNLOAD_SOURCE`	Download mirror (`auto`/`hf`/`hf-mirror`/`weights`).	Overrides the config key.
`OPENASR_HF_TOKEN`	Hugging Face auth token for gated downloads.	Also reads `HF_TOKEN` and `HUGGING_FACE_HUB_TOKEN`.
`OPENASR_CATALOG_URL`	Override the model catalog URL or local path.	Same as `--catalog-url` on `pull`.
`OPENASR_API_KEYS_PATH`	Override the API key store location.	Default `OPENASR_HOME/apikeys.json`.
`OPENASR_SPEAKER_PROFILES`	Override the voiceprint store path.	Default `OPENASR_HOME/diarize/voiceprints.json`.
`OPENASR_PULL_CONNECTIONS`	Parallel connection count for model downloads.
`OPENASR_GGML_CPU_THREADS`	Override ggml CPU thread count.	Mirrors `preferences.inference_threads`.

API key management

openasr apikey manages Bearer tokens for openasr serve. Loopback callers need no key by default; creating a key forces every caller (including loopback) to present one.

Only a key’s SHA-256 hash is persisted — the plaintext is shown once at creation and is not recoverable.

openasr apikey create [--name <LABEL>]   # prints the key once
openasr apikey list                       # id, name, created, preview
openasr apikey revoke <id>                # e.g. key_1a2b3c4d5e6f7a8b

The key store lives at OPENASR_API_KEYS_PATH if set, otherwise OPENASR_HOME/apikeys.json.

Diagnostics

openasr doctor prints the resolved configuration, runtime capabilities, and device details:

openasr doctor

Output includes the home directory path, config file path, model registry status, default model/backend validation, ggml backend and CPU feature information, per-device memory details, and ffmpeg status. ffmpeg is optional for WAV input; it is used to prepare non-WAV formats for the native backend.

Precedence

For settings that can appear in multiple places, the resolution order is:

CLI flag (e.g. --model, --ffmpeg-bin)
Environment variable (e.g. OPENASR_MODEL, OPENASR_FFMPEG_BIN)
config.json value (e.g. default_model, media.ffmpeg_bin)
Built-in default

See the CLI reference for flag details, the Server API for the HTTP management endpoints, and the Models page for available model packs.