Configuration
Use qvac.config.* to configure QVAC's overall behavior.
Overview
QVAC configuration is loaded once during initialization from qvac.config.* file — qvac.config.json, qvac.config.js, or qvac.config.ts — and remains immutable for the lifetime of the SDK instance. To provide configuration, either set the QVAC_CONFIG_PATH environment variable or place a qvac.config.* file at the root of your project.
When using only the SDK, providing a configuration is not required. If you do not provide one, the SDK uses the default settings. When using the HTTP server, however, providing a configuration is required.
Examples
Below are examples of qvac.config.* files. Values marked with <placeholders> should be replaced with your actual values.
{
"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,
"deviceDefaults": [
{
"name": "Samsung Galaxy force CPU",
"match": { "platform": "android", "deviceBrand": "samsung" },
"defaults": { "llm": { "device": "cpu" } }
}
],
"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 |
deviceDefaults | Override loaded model config for specific devices. First matching pattern wins. Use it to optimize for different hardware. | DevicePattern[] | No | — |
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 | nmt | tts | ocr
Important: for the exact config fields supported by each model type (key), see modelConfig — loadModel() at @qvac/sdk API reference.
ServeConfig
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. | 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"
}
}
}