# Configuration Reference

Configuration is layered from environment, global user settings, project settings, and active TUI state.

## Common Environment Variables

| Variable | Purpose |
| --- | --- |
| `OMNIUS_HOST` | Bind host and port, for example `0.0.0.0:11435` |
| `OMNIUS_REST_API_KEY` | Single admin bearer token for the Omnius REST API |
| `OMNIUS_REST_API_KEYS` | Multi-key REST auth: `key:scope:owner:rpm:tpd:max_jobs` |
| `OMNIUS_PROVIDER_API_KEY` | Upstream model-provider bearer token |
| `OMNIUS_MODEL_API_KEY` | Alternate upstream model-provider bearer token |
| `OMNIUS_UPSTREAM_API_KEY` | Compatibility upstream provider token |
| `OMNIUS_API_KEY` | Legacy fallback for provider auth and legacy REST auth |
| `OMNIUS_API_KEYS` | Legacy multi-key REST auth |
| `OMNIUS_ACCESS` | Network access policy for the daemon |
| `OMNIUS_DAEMON` | Start in daemon mode when set to `1` |
| `OMNIUS_FORCE_NO_THINK` | Force `think: false` for Qwen-style backends |
| `OMNIUS_THINK_AUTO` | Enable opt-in automatic thinking mode trigger |
| `OMNIUS_CPU_OFFLOAD_ALLOWED` | `1` permits native Ollama CPU overflow; any other explicit value disables it. When absent, use saved `cpuOffloadAllowed` (default `false`) |
| `OMNIUS_TG_LATENCY_TARGET_MS` | Desired end-to-end Telegram reply time (default `30000`) |
| `OMNIUS_TG_LATENCY_HARD_MS` | Trial a leaner Telegram chat profile after this total latency (default `60000`) |
| `OMNIUS_TG_LATENCY_MIN_SAMPLES` | Receipt-valid samples required to retain a leaner profile (default `3`) |
| `OMNIUS_TG_LATENCY_SAMPLE_WINDOW` | Per-profile rolling Telegram latency sample count (default `24`) |
| `OMNIUS_TG_WRITE_CAPABILITY_RECHECK_MS` | Minimum read-only Telegram permission-probe interval (default `300000`, minimum `15000`) |
| `OMNIUS_ASR_CUDA_VISIBLE_DEVICES` | Exact CUDA GPU index or UUID used for managed ASR activation; multi-device masks are rejected (Jetson's integrated GPU is `0`) |
| `OMNIUS_VIBEVOICE_PYTHON` | Host Python used to create the VibeVoice venv; its CUDA-enabled Torch is inherited with `--system-site-packages` |
| `OMNIUS_VIBEVOICE_ATTN` | VibeVoice attention implementation (`sdpa` by default; use a host-supported implementation) |
| `OMNIUS_VIBEVOICE_MAX_NEW_TOKENS` | Explicit VibeVoice structured-transcript generation ceiling (default `32768`) |
| `OMNIUS_AUDIO_PYTHON` | Preferred JetPack CPython 3.10 interpreter containing vendor CUDA Torch; bounded workspace discovery is used when unset |
| `OMNIUS_AUDIO_AUTO_SETUP` | Set to `1` to opt into managed YAMNet and speaker-audio runtime provisioning; ordinary audio inference never installs dependencies |
| `OMNIUS_SEMANTIC_AUDIO_AUTO_SETUP` | Set to `1` together with `OMNIUS_AUDIO_AUTO_SETUP=1` to opt into managed CLAP provisioning; semantic audio setup is off by default |
| `JETSON_TORCH_WHEEL` | Optional exact NVIDIA Jetson Torch wheel URL for LuxTTS when automatic L4T, JetPack, CUDA, and Python ABI resolution cannot find a verified wheel; generic PyPI Torch is never used as a Jetson fallback |
| `OMNIUS_VOICE_AUTO_SYSTEM_DEPS` | Set to `1` only for an explicit administrator setup run that may install LuxTTS native build prerequisites; daemon and inference-adjacent calls never use sudo by default |
| `OMNIUS_VISION_AUTO_SETUP` | Set to `0` to disable managed OpenCLIP provisioning on JetPack |
| `OMNIUS_VISION_PYTHON` | Explicit vendor CUDA Python for the isolated OpenCLIP runtime |
| `OMNIUS_VISION_MIN_AVAILABLE_MB` | OpenCLIP-specific Jetson unified-memory admission threshold (default `8192`) |
| `OMNIUS_NEMO_SPEECH_BIN` | Optional existing CUDA-enabled NeMo-Speech.cpp binary; otherwise live diarization builds the pinned source revision |
| `OMNIUS_DIAR_NVCC` | Optional absolute JetPack CUDA compiler; discovery otherwise checks `/usr/local/cuda-12.2/bin/nvcc` then `/usr/local/cuda/bin/nvcc` |
| `OMNIUS_DIARIZATION_AUTO_SETUP` | Set to `0` to disable managed diarizer provisioning; live Sortformer defaults on for JetPack |
| `OMNIUS_HF_TOKEN` | Setup-only Hugging Face token for gated Community-1 download; never persisted or passed to inference |
| `OMNIUS_PYANNOTE_TERMS_ACCEPTED` | Set to `1` only after accepting Community-1 terms; permits gated daemon bootstrap when a token is present |

## Provider Key Precedence

For an upstream inference request, Omnius resolves one credential in this
exact order:

```text
OMNIUS_PROVIDER_API_KEY
  → OMNIUS_MODEL_API_KEY
  → OMNIUS_UPSTREAM_API_KEY
  → OMNIUS_API_KEY
  → VLLM_API_KEY
  → persisted endpoint configuration
```

The first defined value wins. `OMNIUS_REST_API_KEY` and
`OMNIUS_REST_API_KEYS` authenticate callers to the Omnius daemon; they are not
upstream provider credentials.

Linux installations load optional daemon-only overrides from
`~/.config/omnius/daemon.env`. The postinstall creates this file with mode
`0600` and creates or rewrites the systemd unit with
`EnvironmentFile=%h/.config/omnius/daemon.env`.
This is the appropriate place for `OMNIUS_AUDIO_PYTHON` or a setup-only gated
model token; credentials do not need to be embedded in the unit or sent in a
REST request.

## Provider Protocol

Known provider presets select one of `ollama`, `openai-chat`, or
`anthropic-messages`. Custom endpoint configuration must include an explicit
protocol. If a legacy endpoint can be identified unambiguously from its known
provider or saved backend type, Omnius migrates it; otherwise the endpoint
remains saved but disabled until a protocol is selected.

## Runtime State

### GPU selection and CPU offload

Open `/gpu`, use Space to toggle devices or **CPU offload OK**, then Enter to
save. Escape cancels. The ordered `gpuEnabledUuids` setting limits native broker
requests to those devices; enabling two or more lets the broker split a model
across them. The preferred device does not restrict the request to one GPU.

`cpuOffloadAllowed` defaults to `false`. When enabled, native Ollama requests
permit overflow layers in system RAM. The broker still prefers full GPU
placement. A model larger than the enabled GPUs' combined physical capacity
can use an exclusive GPU scope with CPU overflow after host and service memory
checks. GPU selection and CPU permission have independent project/global
settings, and `/gpu reset` resets only the GPU selection. An empty GPU selection
still disables CUDA; CPU permission does not enable CPU-only fallback.

The broker advertises support through its discovery endpoint. Older brokers
must be updated before accepting CPU overflow. Remote OpenAI and Anthropic
providers do not receive this host policy. Changes apply to future requests;
existing model placement is not migrated.

Project runtime state:

```text
.omnius/
  settings.json
  jobs/
  context/
  sponsor/
  scoped-personality/
  telegram-creative/
```

User-global state may live under `~/.omnius/`, including runtime API keys and voice clone references.

The persisted `asrEngine` and `asrModel` settings select one exact entry from
the canonical ASR registry. Selection is not readiness: clients should inspect
`GET /v1/asr/status` before treating a backend as active. Managed VibeVoice
runtime state is stored below `~/.omnius/runtimes/asr/`; its Hugging Face
weights use the unified model cache rather than the project or npm package.

## Auth Key Format

```text
key:scope:owner:rpm:tpd:max_jobs
```

Scopes:

- `read`
- `run`
- `admin`

Rate and concurrency fields are optional.
