Running from source

NOTE: If you’re just looking to run the app, try installing from pypi or using the hosted version is highly recommended.

Front end

The current supported Node version is listed in the .nvmrc file. We recommend using a node version manager such as NVM for ease of use.

We use pnpm as our package manager. Please see their guidelines for installing pnpm on your machine.

nvm use
pnpm install
pnpm run dev

Back end

We use uv to manage Python versions and dependencies. The version is pinned in .python-version and locked via uv.lock.

Install uv (see uv installation), then sync dependencies:

uv sync

uv sync installs the Python version from .python-version if needed, creates .venv, and installs the project in editable mode with dev dependencies (black, isort, mypy, pytest, etc.). Use uv run … for backend commands — no manual activation, pyenv, or PYTHONPATH needed.

Starting the server

pnpm run flask:start

Starting with hot reload:

pnpm run flask:start-debug

When both the frontend and backend are running you can access the app on http://localhost:5173, but an alternative local URI may be provided in the terminal when running pnpm run dev.

CLI arguments

  • --profiler-path - specify the local path to the folder containing profiler data

  • --performance-path - specify the local path to the folder containing performance data

  • --tt-metal-home - specify the path to the TT Metal repo when running directly on the machine where reports are being generated

  • --host - set the host to bind the backend server to

  • --port - set the port to bind the backend server to

  • --server - enable server mode and bind to all network interfaces (0.0.0.0)

  • -d, --daemon - run the backend server as a daemon process

Environment variables

The application should run out of the box, but should you need to you can adjust certain values in the front end or back end code using a .env file. See .env.sample for some of the key variables available.

ALLOWED_ORIGINS

Comma-separated list of browser origins allowed to call the API and open a socket, for example ALLOWED_ORIGINS=https://visualizer.example.com,https://ops.example.com.

By default the app trusts only its own origin, plus the Vite dev server (http://localhost:5173) outside production. This matters because there is no authentication: local-only endpoints hand out SSH hosts, usernames, and report paths, so anything you add here is another page that can read them.

The app still accepts its own origin without configuration where it can recognise it: localhost, any IP address (so --server and containers reached by address work as they always have), and whatever you passed to --host.

Set it when the app is reached under some other hostname, including:

  • a hosted deployment behind a reverse proxy or TLS termination;

  • a separately hosted front end calling this API.

A hostname the app wasn’t launched with is not trusted just because it resolves here, even via X-Forwarded-Host: a page on an attacker-controlled domain can point its own name at your loopback interface, and the socket handshake would otherwise accept it as same-origin. Addresses aren’t affected, since no name is resolved. Setting ALLOWED_ORIGINS to an empty string trusts nothing beyond those self-recognised origins.