---
name: tuned-tensor
description: Use when an agent needs to create, validate, train, evaluate, or serve Tuned Tensor behaviour specs and models with the local tt CLI. Also use when the user asks to examine this machine's hardware, GPU, VRAM, CUDA, or what model or pipeline can train or infer here.
---

# Tuned Tensor

Use Tuned Tensor to prepare behaviour specs, train models, and compare results
with the baseline. Install `tt` with
`curl -fsSL https://tunedtensor.com/install.sh | sh` or
`npm install -g --ignore-scripts @tuned-tensor/cli`. Local adapter training needs Linux,
a compatible NVIDIA GPU, and `uv`. Direct local commands need no account or
token. Add a TT token to use the managed agent model and cloud commands.
The dashboard displays cloud progress and reports; use TT to operate workflows.

## Quick start

```bash
curl -fsSL https://tunedtensor.com/install.sh | sh
tt hardware
tt init --name "Customer Support Bot" --model Qwen/Qwen3.5-2B --profile spark
# Edit tunedtensor.json, replacing both placeholder examples, then:
tt doctor tunedtensor.json --config local-runner.json
tt validate tunedtensor.json
tt models prefetch tunedtensor.json
tt pipeline run --spec tunedtensor.json --config local-runner.json
tt runs report <run-id> --config local-runner.json
```

See `/docs/local-training` for configuration, evaluation, and artifact details.

## Supported base models

- `Qwen/Qwen3.5-2B`
- `nvidia/NVIDIA-Nemotron-3.5-Lightning-30B-A3B-BF16`
- `meta-models/Muse-Glimmer-30B`

## Examine this host

When the user asks to inspect or examine this machine, GPU, VRAM, CUDA, or
what can train, fine-tune, or infer here, run:

```bash
tt hardware
tt --json hardware
```

Use the verdicts (`ready`, `tight`, `not_possible`) to choose among the supported
adapter models and foundation model sizes. Base recommendations on these
results. The `tt` shell agent calls `examine_hardware` for the same inventory.

## Local agent

Use one Tuned Tensor token for the managed agent and cloud commands. Create
the token in dashboard settings, then save it at the hidden prompt:

```bash
tt auth login
tt
# With an existing BYO selection, switch back inside tt:
# /model tunedtensor/managed
```

The `tt` shell runs tools, handles approvals, and stores conversations locally.
If no provider is selected, TT login selects the managed model automatically.
Tuned Tensor chooses that model and sends requests through OpenRouter, so there
is no separate model key to configure. Prompts and tool results are sent to
Tuned Tensor and OpenRouter for inference.

For your own provider, use `/login openrouter` and
`/model openrouter/<model-id>`. This path connects directly to OpenRouter with
your key and chosen model. Scripts can use `tt agent configure` after a key is
saved. Either provider works with local or cloud workflows. Cloud operations
require a TT token.

The TT agent prepares local spec folders and pipeline dry runs for `/approve`.
Cloud spec changes also need approval, using the same TT token and API origin
used to prepare the proposal. After changing either, restore the original
token and API origin or prepare a new proposal. Start or cancel actual training
with direct CLI commands, such as `tt pipeline run` or `tt cloud runs start`.

## Cloud operations and usage

```bash
tt auth login
tt cloud push --file tunedtensor.json
tt cloud runs estimate <spec-id>
tt cloud runs start <spec-id>
tt cloud runs list
tt cloud runs report <run-id>
tt usage
tt balance
tt publish <local-run-id>
```

Check estimated credit costs before submitting cloud work. Use `tt cloud --help`
for spec, dataset, labeling, model, and run commands. Local commands remain
available without authentication. Upload local reports with `tt publish` when
the user requests it.

## Common commands

```bash
tt status
tt hardware
tt doctor tunedtensor.json
tt validate tunedtensor.json
tt pipeline run --spec tunedtensor.json
tt runs list
tt --json runs list
tt runs report <run-id>
tt models verify local-<run-id>
tt models serve local-<run-id> --config local-runner.json
tt serve active --config local-runner.json
tt pipeline validate --file pipeline.json
```

Use `tt --json` when another program needs to parse command output.

`tt serve active` requires an active adapter. To activate an adapter, its run
must pass the `generalRegression` suite. You can serve a verified adapter by its
ID with `tt models serve local-<run-id>` without activating it.

```bash
tt --json runs report <run-id>
```

## Local model serving

Local serving uses vLLM and requires Linux and an NVIDIA CUDA GPU.

```bash
tt models verify local-<run-id>
tt models serve local-<run-id> --spec tunedtensor.json
```

`tt models serve` exposes an OpenAI-compatible local endpoint at
`/v1/chat/completions` and a `/health` endpoint. Adapter serving uses the saved
training spec instructions by default. Use `--spec tunedtensor.json` to supply
that spec explicitly; its instructions must match those used during training.
For `tt serve base`, pass `--spec` to apply the spec instructions to the base model.

Useful options:

```bash
tt models serve local-<run-id> --spec tunedtensor.json --device cuda
tt serve base --spec tunedtensor.json
```

## Handling artifacts and credentials

- Keep downloaded artifacts, local runtimes, model caches, `.env` files, and credentials out of commits.
- Do not print provider API keys in logs or final answers.
- Do not delete run artifacts or activated models unless the user explicitly asks.
- Spec writes from the TT agent must wait for `/approve`. `/reject` discards a proposal without applying it.