System requirements

Overview

Minimum host requirements for running @qvac/sdk and @qvac/cli. You can validate your environment against this list with:

qvac doctor

Use --json for machine-readable output and --quiet to set the exit code only (0 when all required checks pass, 1 otherwise).

The qvac CLI itself runs on desktops only. The SDK additionally targets Android and iOS via Expo/BareKit; those appear here as deploy targets with host-toolchain checks (adb, xcodebuild) but never cause a non-zero exit.

Required

Requirement	Notes
Node.js `>= 18.0.0`	Node 18 is end-of-life; prefer `>= 20`. Matches `engines.node` of `@qvac/cli`.
Supported CLI host	`darwin-arm64`, `darwin-x64`, `linux-arm64`, `linux-x64`, `win32-x64`. The CLI cannot run on mobile; those are deploy targets only.
Total RAM `>= 2 GB` (recommended `>= 4 GB`)	Below 4 GB, most LLMs will fail to load.

Requirement	When it is needed
Available RAM `>= 2 GB`	Needed when loading a model. Checked via `os.availableMemory()` on Node 22+, falling back to `os.freemem()` on older Nodes.
GPU acceleration (Metal on macOS, Vulkan on Linux/Windows)	QVAC inference backends use Metal (always present on macOS) or Vulkan on Linux/Windows. Without a Vulkan ICD, LLM and Whisper inference fall back to CPU and are significantly slower.
Free disk `>= 5 GB` in the working directory	Model artifacts are typically multi-GB per model. Uses `fs.statfsSync` (Node 18.15+) with a POSIX `df` fallback.

Deploy targets

These checks are informational. They never cause qvac doctor to exit non-zero, because cross-bundling is always supported via bare-pack prebuilt binaries. What is checked here is the host toolchain needed to install/deploy to each target class.

Target	Check	Status when missing
`darwin-{arm64,x64}`, `linux-{arm64,x64}`, `win32-x64`	Listed under "Desktop"; native host flagged with `(native)`.	Always `pass` — cross-bundling is built in.
`android-arm64`	`adb --version`	`warn` — install Android platform tools to deploy to devices.
`ios-arm64` + simulators	`xcodebuild -version` (macOS only)	`warn` on macOS without Xcode, `info` on non-macOS hosts.

Optional tools

Only required if you use the corresponding feature. The checker warns when they are missing but does not fail.

Tool	Required for
`ffmpeg`	Microphone capture, transcription examples, and the built-in audio decoder. Install from ffmpeg.org.
Bare runtime	Running the SDK under Bare directly.
Bun	Building the SDK from source or running the monorepo development workflow.

Project

Check	Notes
`@qvac/sdk` resolvable from project	Resolved with `require.resolve('@qvac/sdk/package.json')` rooted at the working directory; hoisted installs (monorepos, Yarn/Bun workspaces) are correctly detected.

Exit codes

0 — all required checks passed. Warnings, skips, and informational rows may still be present.
1 — one or more required checks failed (unsupported Node version, unsupported CLI host, insufficient total RAM, ...). See the printed hints for remediation steps.

JSON schema

interface DoctorReport {
  ok: boolean;
  platform: string;       // e.g. "darwin"
  arch: string;           // e.g. "arm64"
  nodeVersion: string;    // e.g. "20.19.5"
  sections: Array<{
    id: 'runtime' | 'hardware' | 'targets' | 'tools' | 'project';
    title: string;
    checks: Array<{
      id: string;
      label: string;
      status: 'pass' | 'warn' | 'fail' | 'skip' | 'info';
      severity: 'required' | 'recommended' | 'informational';
      value?: string;
      detail?: string;
      hint?: string;
    }>;
  }>;
}

Status semantics

pass — check ran and the requirement is satisfied.
warn — recommended requirement not met, or a deploy-target toolchain is missing; does not cause a non-zero exit.
fail — required check not met; causes exit code 1.
skip — the check could not be executed on this host (missing Node API and no fallback, etc.).
info — informational row with no pass/fail judgment (e.g. iOS deploy target on a non-macOS host).