Skip to main content

komorebi-runtime

The tt-metal build that Komorebi runs on, as one platform wheel with a locator. It is the one copy of the runtime that komorebi-tt (and later kohakutt) depend on, so that both can run in one process on one card. Nothing of Komorebi's programming model is in it. It is on PyPI as komorebi-runtime (0.81.1.3, with Komorebi 0.1.0, a first release for one card model); pip install "komorebi-tt[runtime]" installs it.

File What it is
../tt-metal.pin The tt-metal release the runtime is built from (v0.81.1): packaging/tt-metal.pin, the only pin in the repository.
patches/ Our patches to that release: a successful kernel build's compiler output goes through tt-metal's logger, and eager launches of a thread that opts in publish their fetch-queue entries together (both from Kohaku-TT's packaging); and no path of the build machine in the binaries (the X280 objects and images compiled with -ffile-prefix-map, the experimental NoC estimator's table looked up relative to the working directory).
BUILD Our build number. The version is the pin plus it: 0.81.1.3. A dependent requires >=0.81.1.N,<0.81.2.
build_tt_metal.sh Clones the pin into a directory, applies the patches, configures it with the X280 runtime and without distributed (OpenMPI cannot be carried in a wheel) and with -ffile-prefix-map=DIR=. (so no path of the build machine is written into a library), and builds only what the wheel carries. It installs no system packages: tt-metal's build dependencies must be on the host.
build_wheel.py Builds the wheel from that directory.
src/komorebi_runtime/ (at the top of the repository) The locator, the one-time setup steps (prepare.py) and the commands. The komorebi-tt wheel does not carry it.

Building

packaging/runtime/build_tt_metal.sh /path/to/tt-metal    # KMR_JOBS=N limits the jobs
python3.13 packaging/runtime/build_wheel.py --tt-metal /path/to/tt-metal --out dist

build_tt_metal.sh builds the targets ttnn (with it _ttnncpp.so and the libraries), hw_toolchain, the two X280 runtime objects, the X280 idle image, and the static X280 host runtime (x280_device, x280_state) that Komorebi's native host module links, and the X280 priming program x280_prime_test (packaging/build_wheel.py --host-module builds it in this tree). A second run updates the build. KMR_CCACHE=1 compiles through ccache.

build_wheel.py rejects a tree at another tag or with a patch not applied, and a pyproject.toml whose version is not the pin plus BUILD. It needs patchelf (--patchelf PATH). The platform tag is manylinux_<glibc floor>_x86_64, where the floor is the newest GLIBC_ symbol version any carried library requires (read with readelf -V; 2.38 for a build on glibc 2.39), so the tag claims no more than the files need; --platform overrides it. It prints the floor, the wheel's size and its three largest members.

What the wheel carries

Everything is under komorebi_runtime/:

  • lib/: _ttnncpp.so (Kohaku-TT's native library links it) and the libraries it loads from the build, under the names they are loaded as, each with the rpath $ORIGIN: libtt_metal.so, libtt-umd.so.0, libtracy.so.0.14.1, libtt_stl.so;
  • tree/: the kernel runtime tree the JIT compiles against, laid out as in a tt-metal tree (runtime/hw, tt_metal/hw, tt-llk, the kernel-side headers and sources, tt_metal/sfpi-version, the list tt-metal's own wheel ships), and the X280 pieces at their tree paths: tt_metal/fabric/experimental/x280/ld/ and include/, build/x280/obj/entry_active.o and x280_active_start.o, and the idle image the X280 tiles are booted to, build/x280/firmware-lim-idle.bin;
  • bin/x280_prime_test: the pinned tree's program that primes a card's X280 memory, as the tree builds it, with the rpath $ORIGIN/../lib. It loads only the libraries above; gtest and the X280 host runtime are linked into it statically;
  • manifest.json: the pin, the tt-metal commit, the patches and their sha256, the build number, the version, the libraries and every file of the package.

Not inside: tt-metal's Python packages (ttnn and its module _ttnn.so): Komorebi's host goes through tt-metal's C++ API in its native module. Nor the RISC-V compiler (sfpi). python -m komorebi_runtime sfpi fetches the release tree/tt_metal/sfpi-version names, checks its sha256, and unpacks it into the cache directory.

The locator

Nothing runs at import.

Call Answer
installed() whether the package holds a built runtime (an install of packaging/runtime/ alone does not)
manifest(), pin(), version() the build's manifest; "v0.81.1"; "0.81.1.3"
lib_dir(), tree() the libraries; the kernel runtime tree inside the package
x280() the X280 runtime objects in link order, the linker script, the include directory, the idle image
prime_program() the X280 priming program (absent before 0.81.1.3)
sfpi_dir(), sfpi_bin() where the compiler is fetched to; its bin directory, or None before the fetch
cache_directory() KMR_CACHE, else $XDG_CACHE_HOME/komorebi, else ~/.cache/komorebi
root() the runtime root: <cache>/runtime-<version>/, a directory of links to the tree's entries plus runtime/sfpi once the compiler is fetched. It has a tt-metal tree's layout, so it serves as TT_METAL_RUNTIME_ROOT and as the tree Komorebi builds X280 images against
activate() sets TT_METAL_RUNTIME_ROOT to root() unless it is set
python -m komorebi_runtime sfpi     # fetch the compiler into the cache
python -m komorebi_runtime prime    # prime a card's X280 memory (--card N)
python -m komorebi_runtime doctor   # files present, libraries load, compiler found
python -m komorebi_runtime root     # print the runtime root

sfpi and prime are the lower-level form of Komorebi's kmr sfpi and kmr prime; kmr setup runs both, in that order.

Priming a card

A card's X280 memory is prepared once: the ECC of the X280 tiles' local memory (LIM) is primed, and the card is then reset once (tt-smi -r N); the priming survives resets. prime runs the carried program on card N (--card N, else the first of TT_VISIBLE_DEVICES, else 0) with the runtime root, slow dispatch and the program's opt-in (X280_ALLOW_LIM_ECC_PRIME=1), and reads its result:

  • the card was unprimed: the program opened the X280 runtime, which primed every L2CPU tile (WayEnable committed, the top way walked, the marker written); the card needs its reset;
  • the card was primed before: the open found it ready and wrote nothing to the X280 tiles (the same open every Komorebi session makes); nothing to do;
  • anything else (no /dev/tenstorrent/N, the compiler not fetched, the program's failure): exit status 1 and the reason.

Priming opens the card and refuses while an X280 tile is out of reset, so nothing else may use the card while it runs. The program is the pinned tree's own rather than a new one: the X280 runtime's entry point lives in a static library that no carried shared library exports, and the program needs no library the wheel does not already carry.

A program that uses komorebi.Session, the examples among them, needs nothing set: Komorebi activates the runtime before it opens the card. A host of one's own sets TT_METAL_RUNTIME_ROOT to what root prints.

doctor exits with status 1 when a file is missing, a library does not load or the compiler is not fetched. It names the priming command and does not open the card, so it does not say whether a card is primed.

How Komorebi finds it

With TT_METAL_HOME set, Komorebi uses that tree, as before. Otherwise, when komorebi_runtime is importable and holds a runtime, Komorebi uses root() as its tree: the X280 objects, linker script, include directory, idle image and compiler come from the package through it, and a komorebi-tt wheel built with --host-module loads its prebuilt _km_host, whose rpath $ORIGIN/../komorebi_runtime/lib finds this package's libraries when both are installed in one environment. kmr doctor says which was used (from TT_METAL_HOME or from komorebi-runtime 0.81.1.3). komorebi-tt's extra runtime names this package; it is not yet required.

Metadata

Release files for komorebi-runtime 0.81.1.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distribution (wheel)

Table of built distributions (wheels) for komorebi-runtime 0.81.1.3
File Interpreter ABI Platform Actions
komorebi_runtime-0.81.1.3-py3-none-manylinux_2_38_x86_64.whl Python 3 none Linux glibc 2.38+ x86-64 Details for komorebi_runtime-0.81.1.3-py3-none-manylinux_2_38_x86_64.whl

Release files / komorebi_runtime-0.81.1.3-py3-none-manylinux_2_38_x86_64.whl

Download URL komorebi_runtime-0.81.1.3-py3-none-manylinux_2_38_x86_64.whl
Size 47.0 MB
Tags Linux glibc 2.38+ x86-64 Python 3
SHA-256 checksum
How to use checksums
1af7859465c343d733e36d45ee33c64279bc11567d8812a76e4777a8d208e18f
BLAKE2b-256 checksum
How to use checksums
2921cc322867b99b54e65c0b803eb4cf85739d9dc7a8756fdafb0d396ff2dd0f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

Security for komorebi-runtime 0.81.1.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

1 file in this release has been uploaded with provenance metadata.

Attestation for komorebi_runtime-0.81.1.3-py3-none-manylinux_2_38_x86_64.whl

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.81.1.3 This release

1 release file Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page