getting started

Requirements

You'll need an x86-64 Linux machine with a Blackhole p150a, root access, a network connection, and uv.

Check the Tenstorrent installation guide for the OS, BIOS, driver and firmware your card needs. Our p150a dev box runs Ubuntu 24.04.

Install the system software

On Ubuntu, install the prerequisites and run Tenstorrent's installer:

sudo apt update && sudo apt install -y curl jq
/bin/bash -c "$(curl -fsSL https://tenstorrent.ai/install.sh)"

The installer sets up the kernel driver, firmware, hugepages and management tools. Reboot when it tells you to. None of this is part of the libtt Python wheel.

If you let the installer create its default Python environment, activate it and look at the card:

source ~/.tenstorrent-venv/bin/activate
tt-smi

tt-smi should list every card you installed. (If you picked a different environment, activate that one instead.) Quit tt-smi before you continue.

Install the JAX plugin

Create a separate environment for your experiments:

uv venv --python 3.12 .venv
source .venv/bin/activate
uv pip install "jax==0.11.1" "jaxlib==0.11.1" "jax-tt-plugin==0.1.5"

These versions match libtt's reference inference recipe and the published plugin wheel. The wheel bundles the compiler and runtime, so you don't need to install tt-metal separately.

Verify JAX execution

Run this inside the environment:

JAX_PLATFORMS=tt JAX_USE_SHARDY_PARTITIONER=true python - <<'PY'
import jax
import jax.numpy as jnp
import numpy as np

device = jax.devices("tt")[0]
print("device:", device)
x = jax.device_put(np.arange(32, dtype=np.float32), device)
y = jax.jit(lambda a: a + jnp.float32(1))(x)
y.block_until_ready()
np.testing.assert_array_equal(np.asarray(y), np.arange(1, 33, dtype=np.float32))
print("PASS: addition on", y.device)
PY

JAX_PLATFORMS=tt makes JAX fail loudly if the TT backend can't start, instead of quietly falling back to the CPU. JAX_USE_SHARDY_PARTITIONER=true matches libtt's reference configuration. If you see PASS, the plugin can open the device, compile a program and return correct results. That's a smoke test; it doesn't mean larger models will work.

If a check fails

Next, try the matrix multiply experiment or serve a Qwen model.