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 and Python SDK — Configuration.

Providing a configuration is optional; when omitted, the SDK uses the default settings.

Example

Values marked with <placeholders> should be replaced with your actual values.

Configuration schema

{
  "plugins": ["<builtin_plugin_1>", "<custom_plugin_2>"],
  "loggerConsoleOutput": true,
  "loggerLevel": "info",
  "swarmRelays": ["<hyperbee_key_1>", "<hyperbee_key_2>"],
  "cacheDirectory": "</absolute/path/to/.qvac/models>",
  "httpDownloadConcurrency": 3,
  "httpConnectionTimeoutMs": 10000,
  "registryDownloadMaxRetries": 3,
  "registryStreamTimeoutMs": 60000,
  "deviceDefaults": [
    {
      "name": "Samsung Galaxy force CPU",
      "match": { "platform": "android", "deviceBrand": "samsung" },
      "defaults": { "llm": { "device": "cpu" } }
    }
  ],
  "bareRuntimeVersion": "<x.y.z>",
  "serve": {
    "models": {
      "<model_alias>": {
        "model": "<SDK_MODEL_CONSTANT>",
        "default": true,
        "preload": true,
        "config": {}
      }
    }
  }
}

Options

The following table lists all supported configuration options for qvac.config.*:

Option	Description	Type	Required	Default
`plugins`	Plugin specifiers to bundle (built-in and/or custom).	`string[]`	No	All built-in plugins
`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`
`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`
`deviceDefaults`	Override loaded model config for specific devices. First matching pattern wins. Use it to optimize for different hardware.	`DevicePattern[]`	No	—
`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.	`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`	Yes
`defaults`	Model config overrides to apply when matched.	`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):

{
  "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.

`ServeConfig`

Field	Description	Type	Required	Default
`models`	Map of model aliases to model entries (see `ModelEntry` below). Required when running the server.	`Record<string, string \| ModelEntry>`	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	—
`openai`	OpenAI-adapter–specific options. See `OpenAIOptions`.	`OpenAIOptions`	No	—

`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:

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 model into memory on server startup.	`boolean`	No (`true` for constant entries, `false` for explicit)
`config`	Model config overrides (same as `modelConfig` in `loadModel()`).	`object`	No

Example:

{
  "serve": {
    "models": {
      "my-llm": {
        "model": "QWEN3_600M_INST_Q4",
        "default": true,
        "preload": true,
        "config": { "ctx_size": 8192 }
      },
      "my-embed": "GTE_LARGE_FP16"
    }
  }
}

`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`.	`Record<string, string>`	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:

{
  "serve": {
    "publicBaseUrl": "https://api.example.com",
    "openai": {
      "audio": {
        "speech": {
          "defaultVoice": "alloy",
          "voices": {
            "alloy": "tts-chatter-alloy",
            "echo": "tts-chatter-echo"
          },
          "maxInputChars": 4096
        }
      }
    }
  }
}

Configuration

On this page