--- title: "Configuration" canonical: https://docs.qvac.tether.io/sdk/configuration/ collection: "SDK" package: "@qvac/sdk" line: v0.21 current_line: true --- # Configuration (/sdk/configuration) ## Overview QVAC configuration is loaded once during initialization and remains immutable for the lifetime of the SDK instance. The schema and options below are shared across clients; how the config reaches the worker is client-specific — see [JS/TS SDK — Configuration](/sdk/js-ts-sdk#configuration) and [Python SDK — Configuration](/sdk/python-sdk#configuration). Providing a configuration is optional; when omitted, the SDK uses the default settings. ## Example Values marked with `` should be replaced with your actual values. ```json title="Configuration schema" lineNumbers { "plugins": ["", ""], "loggerConsoleOutput": true, "loggerLevel": "info", "swarmRelays": ["", ""], "cacheDirectory": "", "httpDownloadConcurrency": 3, "httpConnectionTimeoutMs": 10000, "requireHttpChecksum": false, "requireSecureTransport": false, "registryDownloadMaxRetries": 3, "registryStreamTimeoutMs": 60000, "fitStubBudgetMs": 40000, "rpcInitTimeoutMs": 30000, "deviceDefaults": [ { "name": "Samsung Galaxy force CPU", "match": { "platform": "android", "deviceBrand": "samsung" }, "defaults": { "llm": { "device": "cpu" } } } ], "bareRuntimeVersion": "", "serve": { "cors": { "origins": ["https://app.example.com"] }, "models": { "": { "model": "", "default": true, "preload": true, "config": {} } } } } ``` ## Options The following table lists all supported configuration options for `qvac.config.*`: | Option | Description | Type | Required | Default | | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | -------- | ----------------------------------------------------------- | | [`plugins`](/sdk/configuration/plugins) | Plugin specifiers to bundle (built-in and/or custom). | `string[]` | No | [All built-in plugins](/sdk/configuration/plugins#built-in) | | `loggerConsoleOutput` | Enable or disable console output for SDK loggers. | `boolean` | No | `true` | | `loggerLevel` | Global log level for all SDK loggers. | `"error" \| "warn" \| "info" \| "debug"` | No | `"info"` | | `swarmRelays` | Hyperswarm relay public keys (hex strings) for improved P2P connectivity (blind relays). | `string[]` | No | — | | `cacheDirectory` | Absolute path to the directory where models and other cached assets are stored. | `string` | No | `~/.qvac/models` | | `httpDownloadConcurrency` | Maximum number of concurrent HTTP downloads for sharded models. | `number` | No | `3` | | `httpConnectionTimeoutMs` | Timeout in milliseconds for HTTP connection establishment (applies to HEAD and GET requests). | `number` | No | `10000` | | `requireHttpChecksum` | Reject a Hugging Face download that exposes no usable SHA-256 (instead of downloading it unverified). Hugging Face downloads are always verified when a hash is available regardless of this flag. | `boolean` | No | `false` | | `requireSecureTransport` | Reject plaintext `http://` and HTTPS→HTTP downgrade redirects for **every** HTTP source (loopback exempt). When off, this is enforced only for Hugging Face sources; bring-your-own HTTP is left as-is. | `boolean` | No | `false` | | `registryDownloadMaxRetries` | Maximum retry attempts for registry (P2P) downloads on timeout. | `number` | No | `3` | | `registryStreamTimeoutMs` | Timeout in milliseconds for stalled registry (P2P) download streams. Raise on slow or high-latency connections where the default triggers spurious retries. | `number` | No | `60000` | | `fitStubBudgetMs` | Budget in milliseconds for the registry fetch of a model's weightless description during [`assessModelFit()`](/sdk/models/assess-model-fit). One budget covers the lookup and the whole companion set; past it the assessment falls back to the computed floor. Raise on slow or high-latency connections. | `number` | No | `40000` | | `rpcInitTimeoutMs` | Timeout in milliseconds for the worker RPC handshake performed when the SDK initializes. Raise on slow storage or embedded hardware where the first worker start legitimately exceeds the default. Overridden by the `QVAC_RPC_INIT_TIMEOUT_MS` environment variable. | `number` | No | `30000` | | `deviceDefaults` | Override loaded model config for specific devices. First matching pattern wins. Use it to optimize for different hardware. | [`DevicePattern[]`](#devicepattern) | No | — | | `ragTurbovec` | Store built-in [RAG](/sdk/ai-capabilities/rag) workspace vectors in a TurboVec index instead of the default HyperDB. Applies only to workspaces created after the flag is set, and the choice is one-way per workspace (existing workspaces keep their adapter). Requires embedding dimension divisible by 8 and ≤ 1024 (fits the default `GTE_LARGE_FP16` at 1024). | `boolean` | No | `false` | | `bareRuntimeVersion` | Bare runtime version used for native addon ABI verification during bundling (`qvac bundle sdk` / `qvac verify bundle`). When omitted, the bundler auto-detects it from `node_modules` (`bare-runtime`, then `bare`). | `string` | No | Auto-detected | | `serve` | Configuration for the [HTTP server](/cli/http-server). | [`ServeConfig`](#serveconfig) | No | — | ### `DevicePattern` | Field | Description | Type | Required | | ---------- | ----------------------------------------------------------- | ----------------------------------------------- | -------- | | `name` | Human-readable label for this pattern (used in logs). | `string` | Yes | | `match` | Which device(s) to target. All specified fields must match. | [`DeviceMatch`](#devicematch) | Yes | | `defaults` | Model config overrides to apply when matched. | [`DeviceConfigDefaults`](#deviceconfigdefaults) | Yes | #### `DeviceMatch` | Field | Description | Type | Required | | --------------------- | ---------------------------------------------------------------------------------------------- | -------------------- | -------- | | `platform` | Target platform. | `"android" \| "ios"` | Yes | | `deviceBrand` | Case-insensitive exact brand (e.g., `"samsung"`, `"google"`). | `string` | No | | `deviceModelPrefix` | Case-sensitive prefix match on the device model (e.g., `"Pixel 10"` matches `"Pixel 10 Pro"`). | `string` | No | | `deviceModelContains` | Substring match on the device model (e.g., `"Galaxy"` matches `"Samsung Galaxy S25"`). | `string` | No | #### `DeviceConfigDefaults` Maps each model-type key to a model config object. For example (inside `DevicePattern.defaults`): ```json { "llm": { "device": "cpu", "ctx_size": 1024 }, "embeddings": { "device": "cpu", "flashAttention": "off" } } ``` Model types (allowed keys): `llm` | `embeddings` | `whisper` | `parakeet` | `bci` | `nmt` | `tts` | `ocr` **Important:** for the exact config fields supported by each model type (key), see [`modelConfig` — `loadModel()` at `@qvac/sdk` API reference](/sdk/reference/api#loadmodel). ### `ServeConfig` | Field | Description | Type | Required | Default | | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | -------- | ------- | | `models` | Map of model aliases to model entries (see [`ModelEntry`](#modelentry) below). Required when running the server. | `Record` | Yes | — | | `publicBaseUrl` | Externally reachable origin (e.g., `"https://api.example.com"`). Required for image `response_format=url`. Must start with `http://` or `https://`. The CLI flag `--public-base-url` overrides this value. | `string` | No | — | | `cors` | Browser origins trusted to make cross-origin requests. See [`CorsOptions`](#corsoptions). | `CorsOptions` | No | — | | `openai` | Options for the `openai` extension, mounted with `qvac serve --openai`. See [`OpenAIOptions`](#openaioptions). | `OpenAIOptions` | No | — | #### `CorsOptions` | Field | Description | Type | Required | Default | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- | -------- | ------- | | `origins` | Exact HTTP(S) origins allowed by CORS, such as `"https://app.example.com"`. Values cannot include credentials, a path, query, or fragment. Wildcard (`"*"`) is not allowed. CLI `--cors-origin` values are added to this list. | `string[]` | No | `[]` | Configure every browser origin explicitly: ```json { "serve": { "cors": { "origins": [ "https://app.example.com", "http://localhost:3000" ] } } } ``` Configuring one or more origins enables CORS. `--docs` also enables CORS for same-port `localhost`, `127.0.0.1`, and `[::1]`, plus the bound host when it is itself loopback. The legacy `--cors` flag is a compatibility validation switch: it does not enable CORS by itself and fails unless `--cors-origin` or `serve.cors.origins` supplies at least one explicit origin. `--cors --docs` still needs an explicit origin because the docs defaults do not satisfy that validation. #### `ModelEntry` The `serve.models` field is a map of model aliases to model entries. Keys are the **model aliases** — the names that HTTP clients use in the `model` field of their requests. Values can be either a **string** (SDK model constant name, e.g., `"QWEN3_600M_INST_Q4"`) or a `ModelEntry` object: **Tip:** you can generate or extend `serve.models` interactively with [`qvac configure`](/cli#qvac-configure) instead of writing entries by hand. | Field | Description | Type | Required | | --------- | ----------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------------------------------------------------------ | | `model` | SDK model constant name. | `string` | Yes (unless using `src` + `type`) | | `src` | Explicit model source (URL or path). | `string` | Yes (if no `model`) | | `type` | Model type: `llm` \| `embeddings` \| `whisper` \| `parakeet` \| `nmt` \| `tts` \| `ocr` \| `whispercpp-audio-translation` \| `diffusion`. | `string` | Yes (if using `src`) | | `default` | Use as the default model for its endpoint category. | `boolean` | No (`false`) | | `preload` | Load the model at server startup. When `false`, it loads lazily on the first request that names it (cold start). | `boolean` | No (`true` for constant entries, `false` for explicit) | | `config` | Model config overrides (same as [`modelConfig` in `loadModel()`](/sdk/reference/api#loadmodel)). | `object` | No | Example: ```json { "serve": { "models": { "my-llm": { "model": "QWEN3_600M_INST_Q4", "default": true, "preload": true, "config": { "ctx_size": 8192 } }, "my-embed": "GTE_LARGE_FP16" } } } ``` #### `LoadOptions` (`serve.load`) Controls how models are loaded on demand. Each field has a matching CLI flag on `qvac serve`. | Field | Description | Type | Required | Default | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | -------- | ------- | | `lazy` | When `false`, requests never trigger a load; an unloaded model returns `503 model_not_loaded`. Only preloaded models serve. CLI: `--no-lazy-load`. | `boolean` | No | `true` | | `concurrency` | Max simultaneous loads across different aliases. `1` mirrors startup preload and bounds memory under lazy request-time loads. CLI: `--load-concurrency`. | `number` | No | `1` | | `timeoutMs` | Per-load deadline in ms; on expiry the load is cancelled and the request gets `503 model_load_timeout`. `null` = unbounded. CLI: `--load-timeout`. | `number \| null` | No | `null` | | `cancelOnDisconnect` | When `true`, a client disconnecting mid-load cancels the load — but only once no other request is still waiting on that same load. CLI: `--no-cancel-load-on-disconnect`. | `boolean` | No | `true` | #### `OpenAIOptions` Optional OpenAI-adapter settings. Currently only `audio.speech` is configurable: | Field | Description | Type | Required | Default | | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | -------- | --------- | | `audio.speech.defaultVoice` | Voice id used by `/v1/audio/speech` when the request omits `voice`. Set to `null` to make `voice` strictly required (otherwise the route returns `400 missing_voice`). | `string \| null` | No | `"alloy"` | | `audio.speech.voices` | Map from OpenAI `voice` strings to `serve.models` aliases (case-insensitive keys). Lets clients keep using OpenAI voice names while the server routes them to QVAC TTS aliases. See [HTTP server — `POST /v1/audio/speech`](/cli/http-server). | `Record` | No | — | | `audio.speech.maxInputChars` | Hard cap on the `input` length (characters) accepted by `/v1/audio/speech`. Set to `null` to disable. Matches OpenAI's documented limit and bounds memory usage since the route buffers the full WAV before responding. | `number \| null` | No | `4096` | Example: ```json { "serve": { "publicBaseUrl": "https://api.example.com", "openai": { "audio": { "speech": { "defaultVoice": "alloy", "voices": { "alloy": "tts-chatter-alloy", "echo": "tts-chatter-echo" }, "maxInputChars": 4096 } } } } } ```