System requirements

Overview

Minimum host requirements for running the SDK and CLI. These are worker-level — all SDK clients (JS/TS and Python) drive the same worker, so the requirements below apply regardless of which client you use.

You can validate your environment against the machine-checkable subset 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).

Supported environments

Environment setup

Host-level toolchain and driver setup that the QVAC worker relies on. Client install commands (npm i @qvac/sdk, pip install tetherto-qvac-sdk, Expo plugin wiring, …) live on each client page — see JS/TS SDK and Python SDK.

Linux

Requirements:

• Ubuntu 22 requires g++ >= 13.
• Vulkan runtime >= 1.4: Vulkan loader + a GPU driver with Vulkan support.

On desktop Linux distributions (e.g., Ubuntu Desktop), these requirements are typically satisfied out of the box.

To verify it, install Vulkan tools and run vulkaninfo:

sudo apt update
sudo apt install -y vulkan-tools
vulkaninfo --summary

In minimalist/headless installations (e.g., Ubuntu Server), you may need to manually install the Vulkan loader, and ensure a Vulkan-capable GPU driver (ICD) is installed. The exact packages vary by distro and GPU vendor. For example:

sudo apt update
sudo apt install -y libvulkan1 mesa-vulkan-drivers
vulkaninfo --summary

Ensure QVAC can detect the GPU Vulkan driver by adding your user to the render and video groups:

sudo usermod -aG render,video $USER

Windows

Requirement:

• Vulkan runtime >= 1.4: Vulkan loader + a GPU driver with Vulkan support.

This requirement is typically satisfied out of the box after installing the correct GPU vendor drivers. To verify it, install Vulkan SDK and run:

vulkaninfo --summary

Mobile (iOS / Android)

Mobile is supported by the JS/TS SDK via Expo. See JS/TS SDK — Expo setup for the full flow.

Scope

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

Recommended

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.

Optional tools

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

Project

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