TokTagger

TokTagger: an open source, interactive annotation platform for Tokamak diagnostic data.

TokTagger is a web-based platform for curating labeled datasets from tokamak diagnostics. It lets users browse shots, inspect signals and images, apply consistent labels, and manage annotations in one place. The Python API and React UI support local or team workflows, making it straightforward to create datasets for downstream analysis and machine-learning models.

It currently supports the following features:

Data Browsing: Explore tokamak shots, signals, and images through an intuitive interface.
Annotation Tools: Apply consistent labels to signals and images using a customizable tagging system.
ML Models: Train and infer from ML models within the UI.
Dataset Management: Organize and manage annotations in a central repository.
Multi-User Support: Role-based access control with per-project membership, suitable for team annotation workflows.
Extensible API: A Python API for integrating with existing workflows and tools.

Installation

To run the application locally:

Install via pip

To install the package via pip (or similarly via Poetry or uv package managers):

python -m venv .venv
source .venv/bin/activate

To install the package for labelling only (without ML Model functionality):

pip install toktagger

Or to include the ML models:

pip install toktagger[models]

If you intend to add custom data loaders or models to your TokTagger instance, this is the recommended route.

Install as a uv tool

Alternatively, it can be installed as a tool using uv. To install the package for labelling only (without ML Model functionality):

uv tool install --python 3.12.6 toktagger

Or to include the ML models:

uv tool install --python 3.12.6 toktagger[models]

Quick Start

To start a local single-user instance:

toktagger

This starts the application at http://localhost:8002. On the first start, TokTagger creates a local identity provider and prints the user name and the password of the first administrator to the terminal, which will only be shown once. Open the application and click Sign in.

Warning

This is an insecure default password. Change it immediately after first login from within Canaille at http://localhost:8003/profile/admin/auth/password.

Multi-User / Team Deployment

For concurrent multi-user access, run with multiple workers. Multiple workers operate on Linux, macOS and Windows:

toktagger --workers 4 --no-browser

The default host is localhost. Only the local machine can connect to it. To let other users on the network connect, add --host 0.0.0.0.

Warning

--host 0.0.0.0 makes TokTagger available to all devices that can reach the machine on port 8002. The traffic is not encrypted. Use it only on a trusted network. For other deployments, use the docker-compose.yml stack, which puts TokTagger behind a TLS proxy.

See User Management for creating accounts, assigning roles, and managing project membership.

Deploy with Docker

To run TokTagger on a shared server, use the Docker Compose stack. The stack adds TLS, Keycloak and MongoDB. Read the Deployment guide.

Configuration

There are a series of additional options which you can configure to customise the functionality of TokTagger - find details about these here.