TT-Studio

Web interface for running AI models on Tenstorrent hardware. It wraps TT Inference Server's packaging, containerization, and deployment automation around TT-Metal model execution. Full deployment needs a Tenstorrent accelerator (/dev/tenstorrent), but the frontend can also run against remote/cloud inference endpoints with no local hardware.

Use python run.py for everything — startup.sh is deprecated. There are no git submodules; run.py fetches the tt-inference-server artifact.

Architecture & ports

Containers share the tt_studio_network bridge; the backend reaches Docker Control at http://docker-control:8002 and the inference API via host.docker.internal. Health checks: backend GET /up/ and GET /models/health/, inference server GET /health, frontend GET /.

Repo layout

• app/backend/ — Django project. Apps: api (settings, ASGI/WSGI, URL routing), docker_control (image pulls, container deploy, model execution), model_control (model registry, inference, TTS), board_control (hardware detection / telemetry), vector_db_control (Chroma RAG), logs_control, wakeword_control (voice activation, WebSocket consumers), shared_config (model/device config, model sync). Routes in app/backend/api/urls.py.
• app/frontend/ — React/TS/Vite app. Source under src/: components/, pages/, providers/, contexts/, hooks/, routes/, api/, lib/, types/. Backend proxy config in vite.config.ts.
• app/agent/ — agent service. inference-api/ — FastAPI inference server.
• docker-control-service/ — standalone Docker control service.
• models/ — model definitions/config. dev-tools/ — license/header tooling.
• dev-docs/ — developer docs. .cursor/rules/ — editor rules. .claude/skills/ — assistant skills.

Common commands

python run.py                 # full setup + start (venv, .env, artifact, Docker)
python run.py run <model>     # setup + start + deploy <model> in one step, from the terminal (stage progress + endpoint shown; --browser to deploy via the web UI instead; omit <model> to pick interactively; --device-id 0 or --device-id 0,1 to pin chips)
python run.py --dev           # dev mode: hot-reload frontend & backend, mount source
python run.py --stop          # stop containers, keep the persistent volume
python run.py --stop-model    # stop one deployed model + reset its chip(s); bare flag opens a picker, or pass a name
python run.py --purge-all     # wipe containers, volumes, HF-cached models and .env
python run.py --purge-model   # uninstall specific model(s); bare flag opens a picker
python run.py --logs          # stream all container logs (docker compose logs -f, env-file wired)
python run.py --info          # re-show the "TT Studio is ready" summary (URLs, mode, hardware)
python run.py --no-clear      # start without clearing the terminal; stream full startup detail
python run.py --report-bug    # bundle logs (logs/tt-studio-logs-ttbr-*.zip) + a ready-to-send support email (.eml) with it attached
python run.py --install-shortcut # add a `tt-studio` shell shortcut (~/.zshrc/~/.bashrc)
python run.py --switch REF    # fetch + check out a tt-studio branch/tag (e.g. an RC), then re-run
python run.py --uninstall     # --purge-all teardown + remove the `tt-studio` shell shortcut
python run.py --check-headers # report files missing SPDX headers
python run.py --build-images  # build images locally instead of pulling prebuilt ones from GHCR
python run.py --make-rc-branch   # maintainers: cut rc-vX.Y.Z from main + open the RC PR
python run.py --update-rc-branch # maintainers: cherry-pick new dev commits into the RC
python run.py --merge-rc-branch  # maintainers: merge the approved RC, tag, publish the release

Frontend (in app/frontend/): npm run dev, npm run build, npm run lint / lint:fix, npm run type-check. Backend (in app/backend/): ./manage.py runserver 0.0.0.0:8000, and tests via pytest (e.g. pytest model_control/test_model_api.py -v).

Conventions

• SPDX headers are mandatory on every new code file (.py/.ts/.tsx/.js):

  # SPDX-License-Identifier: Apache-2.0
  # SPDX-FileCopyrightText: © 2026 Tenstorrent AI ULC

  Use python run.py --add-headers or npm run header:fix to apply.
• Pre-commit: ruff lint + format (config in dev-tools/). Frontend also enforces ESLint + header checks.
• pip package: pipx install tt-studio ships the launcher plus the app tree (hatch_build.py, tt_setup/install_mode.py, guide). If the launcher starts reading a new path under TT_STUDIO_ROOT, add it to BUNDLE_PATHS in hatch_build.py or pip installs won't have it.
• Git workflow: branch off dev as <username>/<feature>; PRs target dev (squash-merge); main is tagged production only. Follow the feature-branch-pr skill for the full flow.

Environment

.env lives at the repo root, auto-created from .env.default. Key vars: HF_TOKEN (gated model downloads), JWT_SECRET, DJANGO_SECRET_KEY, TAVILY_API_KEY (agent search), TT_MODEL_SUPPORT_URL (tt-cli model support spec the catalog syncs from; its release is the default inference-server build), TT_INFERENCE_ARTIFACT_VERSION/_BRANCH (override that build), and the CLOUD_* endpoint/token vars used for deployed/remote-endpoint mode (VITE_ENABLE_DEPLOYED=true).

Docs & assistant config

• Developer guides: Setup, run.py guide, FAQ, Troubleshooting, Model interface, vLLM models, Launcher terminal design (read before changing tt_setup/ terminal output). Also README, Contributing, Agent.
• .cursor/rules/ — Cursor rules: general, backend, frontend, docker-deployment, ai-models, project-overview.
• .claude/skills/ — skills: tt-studio-overview (project map), feature-branch-pr (branch/PR workflow), tt-studio-debug-bundle (log triage), tt-studio-add-model (add an inference-server model that TT-Studio can't deploy yet: catalog entry, hardware deploy, cross-repo triage, patched image, upstream PRs).