# Installation

> Install a prebuilt release, or build Cascadia from source.

There are two ways to install Cascadia:

| Option | Use it to | You need |
| --- | --- | --- |
| [Prebuilt release](#install-a-prebuilt-release) (recommended) | Run models on Intel hardware | An Intel graphics driver; on Linux, the GPU runtime stack |
| [Build from source](#build-from-source) | Develop Cascadia, test it in CI, or build against a specific OpenVINO version | Rust; for real inference, also a C++ toolchain and the OpenVINO GenAI SDK |

Whichever you choose, finish by running `cascadia doctor`. It checks your setup and tells you whether OpenVINO can actually see your GPU, which otherwise fails silently.

## Install a prebuilt release

Each [GitHub release](https://github.com/labscommunity/cascadia/releases/latest) ships self-contained archives for Linux and Windows. The OpenVINO runtime is included, so there is no SDK to install and no `INTEL_OPENVINO_DIR` to set.

### 1. Download and unpack

**Linux**

Download `cascadia-<version>-linux-x86_64.tar.gz`, then unpack it:

```bash
tar -xzf cascadia-*-linux-x86_64.tar.gz
cd cascadia-*-linux-x86_64
```

Bundled libraries load from `lib/` beside the binary. The bundle needs glibc 2.35 or newer (Ubuntu 22.04 or newer).

**Windows**

Download `cascadia-<version>-windows-x86_64.zip` and extract it. Run Cascadia from PowerShell in the folder that contains `cascadia.exe`.

The binary is not added to your PATH. Run it from the unpacked folder (`./cascadia` or `.\cascadia.exe`), or add that folder to your PATH.

### 2. Install the GPU runtime

**Linux**

This is the step most people miss. OpenVINO GPU inference needs the Intel Compute Runtime, the OpenCL ICD, and the Level Zero loader, and your user must be in the `render` group. **Without these, OpenVINO silently sees only the CPU**, even with a working driver and a healthy `clinfo`.

Install them from Intel's graphics repository (Ubuntu 22.04 and 24.04):

```bash
sudo apt-get install -y ca-certificates gnupg wget
wget -qO- https://repositories.intel.com/gpu/intel-graphics.key \
  | sudo gpg --yes --dearmor -o /usr/share/keyrings/intel-graphics.gpg
. /etc/os-release   # noble on 24.04, jammy on 22.04
echo "deb [arch=amd64 signed-by=/usr/share/keyrings/intel-graphics.gpg] \
https://repositories.intel.com/gpu/ubuntu $UBUNTU_CODENAME unified" \
  | sudo tee /etc/apt/sources.list.d/intel-gpu.list
sudo apt-get update
sudo apt-get install -y ocl-icd-libopencl1 intel-opencl-icd libze-intel-gpu1 libze1
sudo usermod -a -G render "$USER"   # then log out and back in
```

Use Intel's repository, not the distro packages. Ubuntu 24.04 ships Compute Runtime 23.43, which predates Lunar Lake and Arc B-series; on that hardware OpenVINO may see no GPU at all. Intel publishes the repository for Ubuntu only. On other distributions, install the equivalent packages by hand.

`ocl-icd-libopencl1` is required even for CPU-only use: the bundled OpenVINO library imports `libOpenCL.so.1`, so without it the binary does not start.

**Windows**

The OpenCL runtime ships inside the Intel graphics driver. Install the latest driver and reboot.

### 3. Verify

**Linux**

```bash
./cascadia doctor
```

**Windows**

```powershell
.\cascadia.exe doctor
```

Doctor should list a GPU device, not just the CPU. It also prints the bundled OpenVINO GenAI version.

Next: [serve your first model](/getting-started/quickstart/).

## Build from source

Choose the build that matches what you need:

| Build | What works | Platforms | You need |
| --- | --- | --- | --- |
| **Stub** | The `mock` engine: the full API, transport, and multi-stage plumbing, without real inference | Linux, Windows, macOS | Rust |
| **OpenVINO** | Real inference on Intel hardware | Linux, Windows | Rust, a C++ toolchain, the OpenVINO GenAI SDK, and on Linux the GPU runtime |

### 1. Install Rust and clone the repository

Install Rust 1.89 or newer with [rustup](https://rustup.rs), then:

```bash
rustup default stable
git clone https://github.com/labscommunity/cascadia.git
cd cascadia
```

### 2. Build

**Stub**

```bash
cargo build --release -p cascadia
./target/release/cascadia doctor
```

The OpenVINO-backed engines return a clean runtime error in this build. Use `--engine mock`; see [Try the API without hardware](/getting-started/try-without-hardware/).

**OpenVINO**

An OpenVINO build needs three things in place before `cargo build`. `cascadia doctor` verifies all three.

**C++ toolchain.** The FFI shim (`cascadia-ov-genai-shim`) compiles C++ against the OpenVINO GenAI headers.

- Linux: `g++` 12 or newer and the OpenCL loader (`sudo apt install g++ ocl-icd-libopencl1`). The final link fails without OpenCL.
- Windows: Visual Studio 2022 Build Tools. Build from a *Developer Command Prompt for VS 2022*.

**OpenVINO GenAI SDK** (2026.2 or newer). Let the repository's resolver download and verify it, and point `INTEL_OPENVINO_DIR` at the result:

```bash
export INTEL_OPENVINO_DIR="$(python3 scripts/ov_sdk.py fetch 2026.4.1.0 --dest "$HOME/openvino/2026.4.1.0")"
```

`--os` and `--dist` default to this host; pass `--dist ubuntu22|ubuntu24|ubuntu26` on other Linux flavours. On Windows: `python scripts\ov_sdk.py fetch 2026.4.1.0 --dest C:\openvino\2026.4.1.0`. To download the archive yourself instead, get it from [Intel's package archive](https://storage.openvinotoolkit.org/repositories/openvino_genai/packages/) and set `INTEL_OPENVINO_DIR` to the extracted root, the folder that contains `runtime/` and `setupvars.sh`.

**GPU runtime (Linux).** Run `./scripts/setup-openvino.sh`, which installs the [same packages as a prebuilt release](#2-install-the-gpu-runtime). On Windows, `scripts/setup-openvino.ps1` checks your driver, MSVC, and SDK environment.

Then build and verify:

```bash
cargo build --release -p cascadia --features openvino
./target/release/cascadia doctor   # should list a GPU device, not just CPU
```

If the link fails on `tbb::detail::…`, add TBB to the linker's search path:

```bash
export LIBRARY_PATH="$INTEL_OPENVINO_DIR/runtime/3rdparty/tbb/lib:$INTEL_OPENVINO_DIR/runtime/lib/intel64"
```

### Run your build on another machine

The binary is statically linked apart from the OpenVINO libraries. Copy it together with:

- Linux: `$INTEL_OPENVINO_DIR/runtime/lib/intel64/` and `runtime/3rdparty/tbb/lib/`
- Windows: `runtime/bin/intel64/Release/` and `runtime/3rdparty/tbb/bin/`

TBB ships beside the runtime, not inside it, and OpenVINO imports it.

### Include the web dashboard

The browser dashboard served at `/` by `--api` workers is compiled in with the `dashboard-embed` feature. Build the dashboard first (Node 20 or newer):

```bash
cd crates/cascadia-dashboard/web && npm ci && npm run build && cd -
cargo build --release -p cascadia --features dashboard-embed            # stub
cargo build --release -p cascadia --features openvino,dashboard-embed   # OpenVINO
```

Without the feature, `/` serves a pointer page and only the JSON API is live. Release archives newer than v0.1.8 include the dashboard.

## Optional components

### Python, for exporting models

`cascadia shard` runs a bundled Python exporter to turn a Hugging Face model into per-stage OpenVINO IR. Python is needed only for export, not for inference, and not on workers.

- From a source checkout: `pip install -r tools/requirements.txt`
- From a prebuilt release: run `cascadia doctor`, which prints the exact pinned `pip install` command for that binary.

`nncf` is optional and enables INT4 quantization; without it, sharding falls back to FP16. Exporting a whole-model IR for `--engine ov-genai` uses Intel's exporter instead: `pip install "optimum-intel[openvino]"`.

### Docker

The repository's `Dockerfile` bundles the OpenVINO and Level Zero stack, so you can skip the host install. GPU inference needs the host GPU passed in (`--device /dev/dri`) and a matching host driver. See the comments at the top of the [Dockerfile](https://github.com/labscommunity/cascadia/blob/main/Dockerfile).

## Use a different OpenVINO version

Every release archive carries one OpenVINO GenAI version: the newest stable release validated on the Cascadia fleet. `cascadia doctor` prints it. OpenVINO's C++ ABI is not stable across releases, so you can't swap the runtime underneath a binary. To use another version:

- **Variant archives.** A release may include extra archives named `cascadia-<version>-<os>-x86_64-ov<openvino-version>.*`, built against a newer or pre-release OpenVINO.
- **Build from source.** `scripts/ov_sdk.py fetch <version>` accepts any published SDK: stable (`2026.4.1.0`), beta (`2026.5.0.0beta1`), or nightly (`2026.5.0.0.dev20260925`).