Using the tt‐metalium container

Why containers?

A container is the easiest way to install tt-metalium because it has a complex set of dependencies which are not available on some distributions and systems. To help mitigate some of the UX challenges containers raise, we create a "wrapper script" which is located at ~/.local/bin/tt-metalium. The script uses Podman to launch the container with some useful options preset for you. Here's the Podman command we use:

podman run --rm -it \
  --volume=/dev/hugepages-1G:/dev/hugepages-1G \
  --volume=${HOME}:/home/user \
  --device=/dev/tenstorrent:/dev/tenstorrent \
  --workdir=/home/user \
  --env=DISPLAY=${DISPLAY} \
  --env=HOME=/home/user \
  --env=TERM=${TERM:-xterm-256color} \
  --network=host \
  --security-opt label=disable \
  "ghcr.io/tenstorrent/tt-metal/tt-metalium-ubuntu-22.04/release-amd64:latest-rc" "$@"

This ensures that:

• The container has access to hugepages
• The container has access to your tenstorrent devices
• You can read and write your home directory as yourself
• Networking is as simple as possible
• Any commands you pass to the script are executed when the container starts

Modifying your container setup

By modifying the wrapper script at ~/.local/bin/tt-metalium, you can edit the configuration options passed to the container at runtime. You can also edit the image itself or launch the container manually like you would any other.

Why Podman?

Docker is the industry standard for containerized workloads, but it's poorly suited for this use case. Podman is easier to install (it's packaged by all major distributions), it can run without administrator privileges, and it automatically maps UIDs and GIDs between the container and the host system. This means that when you create or edit a file in your home directory from within the container, the host system attributes the changes to your user, not the administrator, which prevents file permissions issues.