# Installation (/installation)



import { TrackCopy } from '@/components/track-copy'

## Supported environments

QVAC SDK is distributed as the npm package `@qvac/sdk` for JavaScript/TypeScript projects.

### JS environments

* Node.js $\geq$ v22.17
* [Bare](https://bare.pears.com) $\geq$ v1.24
* [Expo](https://expo.dev) $\geq$ v54

### Compatibility matrix

| Platform | Min Version | Architecture | GPU API/Backend              | Notes                                                                       |
| -------- | ----------- | ------------ | ---------------------------- | --------------------------------------------------------------------------- |
| macOS    | 14.0+       | arm64        | Metal                        | Arch x64 supports CPU inference only; Intel iGPU acceleration not supported |
| iOS      | 17.0+       | arm64        | Metal                        | Requires Expo                                                               |
| Linux    | Ubuntu 22+  | arm64, x64   | Vulkan                       | Vulkan runtime required                                                     |
| Android  | 12+         | arm64        | Vulkan, OpenCL (Adreno 700+) | Requires Expo                                                               |
| Windows  | 10+         | x64          | Vulkan                       | Vulkan-capable GPU + vendor drivers required                                |

## Installation

<TrackCopy name="npm_install">
  ```bash
  npm i @qvac/sdk
  ```
</TrackCopy>

### Linux

Requirements:

* Ubuntu 22 requires [g++](https://github.com/gcc-mirror/gcc) $\geq$ 13.
* Vulkan runtime: 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.

<Callout type="info">
  On PCs, the Vulkan runtime is usually installed along with the GPU drivers. In other words, *if you've installed the correct driver for your GPU (with Vulkan support), you typically don't need to install anything else.*
</Callout>

To verify it, install Vulkan tools and run `vulkaninfo`:

<Tabs>
  <Tab value="debian" label="Debian/Ubuntu" default>
    ```bash
    sudo apt update
    sudo apt install -y vulkan-tools
    vulkaninfo --summary
    ```
  </Tab>

  <Tab value="fedora" label="Fedora/RHEL">
    ```bash
    sudo dnf install -y vulkan-tools vulkan-devel
    vulkaninfo --summary
    ```
  </Tab>
</Tabs>

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:

<Tabs>
  <Tab value="debian" label="Debian/Ubuntu (Intel/AMD via Mesa)" default>
    ```bash
    sudo apt update
    sudo apt install -y libvulkan1 mesa-vulkan-drivers
    vulkaninfo --summary
    ```
  </Tab>

  <Tab value="fedora" label="Fedora">
    ```bash
    sudo dnf install -y vulkan-loader mesa-vulkan-drivers
    vulkaninfo --summary
    ```
  </Tab>
</Tabs>

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

```bash
sudo usermod -aG render,video $USER
```

### Expo

<Steps>
  <Step>
    Install peer dependencies:

    ```bash
    npm i 'react-native-bare-kit@^0.11.5'
    npm i -D 'bare-pack@^1.5.1'
    npx expo install expo-file-system expo-build-properties expo-device
    ```

    <Callout type="success">
      **Tip:** use `npx expo install` for all `expo-*` packages to ensure compatibility with your project's Expo SDK version.
    </Callout>
  </Step>

  <Step>
    Configure `expo-build-properties` and add `@qvac/sdk/expo-plugin` to the `plugins` array in your `app.json`:

    ```json title="app.json"
    {
      "expo": {
        "plugins": [
          ["expo-build-properties", { // [!code ++]
            "android": { "minSdkVersion": 29 } // [!code ++]
          }], // [!code ++]
          "@qvac/sdk/expo-plugin" // [!code ++]
        ]
      }
    }
    ```
  </Step>

  <Step>
    Prebuild your project to generate the native files:

    ```bash
    npx expo prebuild
    ```
  </Step>

  <Step>
    Build and run it on a **physical device**:

    ```bash
    npx expo run:ios --device
    # or
    npx expo run:android --device
    ```
  </Step>
</Steps>

<Callout type="info">
  Due to limitations with `llamacpp`, QVAC currently does not run on emulators.
  You **must** use a physical device.
</Callout>

### Windows

Requirement:

* Vulkan runtime: 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](https://vulkan.lunarg.com) and run:

```powershell
vulkaninfo --summary
```