Skip to content

Part 1. One core · lesson 2 of 42

2. Setup and the first run

This lesson gets your machine ready and runs the program of lesson 1, What Komorebi is. At the end you have run one program on the card yourself.

What you need

  • A computer with a Blackhole P150A card in it, running Linux on x86-64, with Python 3.13.
  • The card set up once for Komorebi: tt-metal (Tenstorrent's own software for the card) built with the extra support Komorebi needs, and the card prepared. This is done once per machine, and it has its own guide. If you work on a shared machine somebody has done it already.
  • Nobody else using the card at the same moment. One program at a time can open it.

Get the code

The steps are the same everywhere. Replace the path of TT_METAL_HOME by where tt-metal is on your machine.

git clone <this repository> komorebi
cd komorebi
python3.13 -m venv .venv
source .venv/bin/activate
pip install -e .
export TT_METAL_HOME=~/tt-metal

pip install -e . installs the Python package komorebi from the folder you cloned, so that import komorebi works. The -e means the package is read from the folder itself. The last line tells Komorebi where tt-metal is.

Or, from 0.1.0: the two wheels

From the 0.1.0 release there is a second way, with no tt-metal folder of your own: two packages from PyPI, komorebi-tt (the framework) and komorebi-runtime (tt-metal, already built). The packages do not hold the tutorial's programs, so you clone the repository at the release's tag for them:

git clone --depth 1 --branch v0.1.0 <this repository> komorebi
cd komorebi
python3.13 -m venv .venv
source .venv/bin/activate
pip install "komorebi-tt[runtime]"
kmr setup

The last line is done once: it fetches the compiler for the card's cores, then prepares the card's X280 memory. On a card prepared before, it says so and changes nothing; on a new card it asks you to reset the card once, with the command it prints (the install guide says more). Do not set TT_METAL_HOME in this way of working: when it is set, Komorebi uses that folder instead of the package. Everything else in this tutorial is the same.

Check the machine

kmr doctor looks at what you have set up and prints one line for each thing. It does not open the card.

kmr doctor

komorebi      0.1.0
python        3.13.18 (~/komorebi/.venv/bin/python)
package       ~/komorebi/src/komorebi
include       ~/komorebi/src/komorebi_native/include
tt-metal      ~/tt-metal
from          TT_METAL_HOME
build         ~/tt-metal/build
x280 runtime  yes
x280 compiler ~/tt-metal/runtime/sfpi/compiler/bin/riscv-tt-elf-gcc

The paths here are shortened; yours show where things really are. Read the lines in pairs of name and answer:

  • komorebi and python: the version of the package, and the Python it runs in. The path should be inside your .venv.
  • package and include: where the package is, and where the C++ headers are that your own C++ files will include.
  • tt-metal and build: the tt-metal folder it found and whether it comes from TT_METAL_HOME. With the two wheels the folder is inside your cache and the line under it says from komorebi-runtime.
  • The two x280 lines name a part of the card that lesson 3, The card explains. The first must say yes and the second must show a path. Without them nothing in this tutorial runs.
  • card setup names the command that prepares a card once, kmr setup. The doctor does not open the card, so it cannot tell whether that was done.

If tt-metal says not found, TT_METAL_HOME is not set in this shell, or it names a folder that does not exist.

Run the first program

The program of the first lesson is in the folder tutorial/01_first_look of the repository. Run it from there:

cd tutorial/01_first_look
python add.py

40 + 2 = 42
7 + 35 = 42
1000 + 2345 = 3345

If you see the same three lines, your machine can run everything in this tutorial.

Two things you will notice the first time:

  • It takes a few seconds before the first line. Komorebi compiles the C++ files for the card, and keeps the result, so the next run starts faster.
  • Besides these three lines your terminal fills with about 25 lines of log from tt-metal (lines that start with a date, and warnings from the compiler on the first run). They are not part of the program's output. The lessons show only what the program printed. To hide the log, run python add.py 2>/dev/null.

Every program in this tutorial lives in its own folder under tutorial/, named with the number of its lesson, and every lesson shows the output that program printed when it ran on a P150A card.

Common mistakes

  • kmr: command not found. The virtual environment is not active in this shell. Run source .venv/bin/activate again; it is needed in every new shell.
  • tt-metal not found in kmr doctor. TT_METAL_HOME is not exported in this shell.
  • The program stops with CardBusy and the number of another process. Something else is using the card. Wait until it ends; a second program that opens the card would otherwise wait for it without end, so Komorebi refuses at once and tells you who holds it.

Next: lesson 3, The card looks at the card itself, so that the next lessons have a picture to work with.