gnome-jarvis/docs/qvac-runtime.md

QVAC runtime and GPU authority

The single-master rule

Only daemon/qvac-master.js may import and operate the QVAC SDK for Jarvis runtime work. Skills receive a master facade; they do not call loadModel() or create their own workers. The harness is connected through daemon/harness-bridge.js and uses the same owner.

flowchart LR
  V[Voice] --> M[Master scheduler]
  H[Harness] --> M
  CU[Computer vision] --> M
  J[Jobs: media / RAG] --> M
  M --> L{GPU admission}
  L -->|fit| SDK["QVAC SDK 0.19.1"]
  L -->|no fit| E[truthful unavailable error]
  SDK --> W[one QVAC worker]

The optional qvac serve --openai command is diagnostic/API infrastructure. It is not started alongside jarvisd in production and must remain bound to 127.0.0.1 when used.

Lifecycle

1. Read QVAC_CONFIG_PATH and the selected profile.
2. Query GPU visibility and model fit before loading the local chat model. Opt-in Groq agent inference skips this local chat load; ASR and TTS still use auxiliary QVAC models on the same worker.
3. Admit work through interactive, computer-vision, background, or
4. Admit work through interactive, computer-vision, background, or maintenance lanes.
5. Load one model configuration at a time and serialize worker access.
6. Stream completion or media progress to the daemon.
7. Cancel by request ID/model ID when the user says stop or a grant is revoked.
8. Suspend or unload according to idle policy; close once during shutdown.

stateDiagram-v2
  [*] --> Uninitialized
  Uninitialized --> Preflight: start
  Preflight --> Ready: GPU visible + fit accepted
  Preflight --> Unavailable: GPU missing / fit rejected
  Ready --> Loading: admitted request
  Loading --> Loaded: loadModel
  Loaded --> Busy: completion / media / vision
  Busy --> Loaded: stream complete
  Busy --> Loaded: cancellation
  Loaded --> Suspended: idle policy
  Suspended --> Loading: new request
  Loaded --> Closing: shutdown
  Suspended --> Closing: shutdown
  Closing --> [*]

Configuration

The repository config is qvac.config.json. Installed user sessions use ~/.config/jarvis/qvac.config.json, generated from packaging/qvac.config.template.json. The server is localhost-only and the default alias is jarvis-master. Model cache files belong under the user's cache directory, never under a system-wide writable location.

GPU policy

JARVIS_GPU_REQUIRED=1 is set by the service. The master requests GPU device and maximum GPU layer offload. An explicit GPU request (or JARVIS_GPU_REQUIRED=1) fails directly on a GPU load error rather than loading a CPU copy that the master would reject. Optional device: 'auto' callers outside that policy can still fall back, and runtime status labels that backend as CPU. Run npm run gpu-doctor and consult hardware compatibility before changing a model profile.