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

{
  "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,
  "requireHttpChecksum": false,
  "requireSecureTransport": false,
  "registryDownloadMaxRetries": 3,
  "registryStreamTimeoutMs": 60000,
  "rpcInitTimeoutMs": 30000,
  "deviceDefaults": [
    {
      "name": "Samsung Galaxy force CPU",
      "match": { "platform": "android", "deviceBrand": "samsung" },
      "defaults": { "llm": { "device": "cpu" } }
    }
  ],
  "bareRuntimeVersion": "<x.y.z>",
  "serve": {
    "cors": {
      "origins": ["https://app.example.com"]
    },
    "models": {
      "<model_alias>": {
        "model": "<SDK_MODEL_CONSTANT>",
        "default": true,
        "preload": true,
        "config": {}
      }
    }
  }
}

Options

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

DevicePattern

DeviceMatch

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

ServeConfig

CorsOptions

Configure every browser origin explicitly:

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

Example:

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

OpenAIOptions

Optional OpenAI-adapter settings. Currently only audio.speech is configurable:

Example:

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