Set up the Voyager SDK & your card

Every hardware tutorial assumes three things: a Linux machine, an Axelera card, and a working Voyager SDK install. This page gets you all three verified — and explains the notice Wingman shows when the SDK is missing.

You need Ubuntu 22.04 or newer and an Axelera M.2 or PCIe card seated in the machine. Agent Dev itself works fine without the SDK — general coding, planning, and reviews all run — but hardware pipeline tasks (deploy, inference, benchmarks) need the Voyager SDK installed locally.

When the SDK is not detected

Install the SDK and driver

1. Clone the SDK

   Clone the SDK and run its dependency installer. This pulls the system packages the toolchain needs.

   bash

   git clone --branch latest https://github.com/axelera-ai-hub/voyager-sdk.git
   cd voyager-sdk
   ./install-dependencies.sh

2. Install the SDK into a virtual environment

   Pip is the recommended install path for current Voyager releases. Create a virtual environment, install the runtime and devkit without copying a version pin from an older guide, then build the operators. The latest branch and package index resolve the current matching release. Keep one virtual environment per SDK version — do not upgrade packages inside an old venv in place.

   bash

   python3 -m venv axelera-env
   source axelera-env/bin/activate
   pip install --extra-index-url \
     https://software.axelera.ai/artifactory/api/pypi/axelera-pypi/simple \
     axelera-rt "axelera-devkit[all]"
   make operators

3. Install the PCIe driver

   Install the PCIe driver that matches the SDK. With no version argument, axdevice selects the release’s recommended driver from the current compatibility data. If the driver build fails, install kernel headers first with sudo apt-get install -y linux-headers-$(uname -r), then verify the module loaded. The module and device names below are the ones a Metis card uses; for another generation, take the names from your SDK release’s driver guide.

   bash

   axdevice driver --install
   lsmod | grep metis   # driver should be listed; load with
                        # sudo modprobe metis or reboot

4. Verify the card answers

   Run axdevice with no arguments. A healthy card prints a device line with its firmware and board-controller versions. If nothing is listed right after boot, check the selected release notes and axdevice reference before using axdevice --refresh; do not carry an older release’s retry workaround into a newer install without matching evidence.

   bash

   source axelera-env/bin/activate && axdevice
   # Device 0: metis-0-1-0 1GiB metis-m2 flver=1.8.0 bcver=7.4

Verify your Metis card

Check version compatibility

Before debugging anything else, check that your versions actually match. Always use the compatibility matrix and release notes shipped with the SDK release you selected; copied commands from another release can install the wrong driver or leave stale model artifacts behind. The table below is the selected v1.8.0 snapshot only, taken on a Metis card, not a compatibility statement for later releases or for another hardware generation.

Refresh models after an SDK upgrade

Where Wingman looks for the SDK

Move to the first tutorial

That is the whole prerequisite path. When axdevice lists your card and Wingman Home shows the SDK as installed, move to Tutorial: your first detection pipeline. If any step above fails — card not listed, driver errors, version mismatch — Troubleshoot devices & SDK has the symptom-by-symptom fixes.