---
name: tuned-tensor
description: Use when an agent needs to create, manage, run, evaluate, download, or locally serve Tuned Tensor behaviour specs and fine-tuned models through the tt CLI or REST API.
---

# Tuned Tensor

Tuned Tensor is a CLI-first service for turning behaviour specs into fine-tuned open-weight language models. Prefer the `tt` CLI for automation. Use the REST API only when the CLI cannot express the workflow.

## Quick Start

Install the CLI:

```bash
npm install -g @tuned-tensor/cli
```

Authenticate with an API key from the Tuned Tensor dashboard:

```bash
tt auth login tt_your_api_key
tt auth status
```

Create a local behaviour spec:

```bash
tt init --name "Customer Support Bot" --model Qwen/Qwen3.5-2B
```

Edit `tunedtensor.json`, then validate and sync it:

```bash
tt eval
tt push
```

Start and watch a training run:

```bash
tt runs start <spec-id>
tt runs diagnose <run-id>
tt runs watch <run-id>
```

Inspect, download, or locally serve the resulting model:

```bash
tt models list
tt models get <model-id>
tt models download <model-id> --output model.tar.gz
tt models setup-runtime
tt models serve <model-id> --spec tunedtensor.json
```

## Agent Workflow

1. Check authentication with `tt auth status`.
2. If no local spec exists, run `tt init` with the nearest matching supported base model.
3. Treat `tunedtensor.json` as the source of truth. Edit it directly, preserve its `id` when updating an existing spec, and commit meaningful spec changes.
4. Run `tt eval` before `tt push`.
5. Run `tt push` to create or update the remote behaviour spec.
6. Start a run with `tt runs start <spec-id>`, inspect live learning progress with `tt runs diagnose <run-id>`, and poll with `tt runs watch <run-id>`.
7. Inspect results with `tt runs get <run-id>` before starting another iteration.
8. Download completed models with `tt models download` only when the user needs a local artifact.
9. Use `tt models setup-runtime` once before local reference serving, then `tt models serve <model-id> --spec tunedtensor.json` to serve a model with its behaviour spec prompt applied.

## Common Commands

```bash
tt specs list
tt specs get <spec-id>
tt runs list
tt runs get <run-id>
tt runs diagnose <run-id>
tt datasets upload training.jsonl --name "Training data"
tt datasets list
tt models setup-runtime
tt models serve <model-id> --spec tunedtensor.json
tt balance
tt topup --amount 25
```

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

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

Use a custom API base URL only for local or staging environments:

```bash
tt -u https://your-api.example.com specs list
```

## Local Model Serving

Use the CLI for local reference serving when a user wants to test a completed model locally:

```bash
tt models setup-runtime
tt models serve <model-id> --spec tunedtensor.json
```

`tt models serve` accepts a model ID, a downloaded `.tar.gz` artifact, or an extracted Hugging Face model directory. It exposes an OpenAI-compatible local endpoint at `/v1/chat/completions` and a `/health` endpoint. By default it applies the compiled behaviour spec prompt from `tunedtensor.json`, so responses preserve the prompt contract used during training.

Useful options:

```bash
tt models serve <model-id> --spec tunedtensor.json --device auto
tt models serve <model-id> --spec tunedtensor.json --device mps
tt models serve <model-id> --spec tunedtensor.json --device cuda
tt models serve model.tar.gz --spec tunedtensor.json
tt models serve ./models/my-model --spec tunedtensor.json
```

Use `--no-spec-prompt` only when intentionally testing raw model behaviour.

## Supported Base Models

- `Qwen/Qwen3.5-2B`
- `Qwen/Qwen3.5-4B`
- `google/gemma-4-E2B-it`
- `google/gemma-4-E4B-it`
- `meta-llama/Llama-3.2-3B-Instruct`
- `microsoft/Phi-4-mini-instruct`
- `ibm-granite/granite-3.3-2b-instruct`
- `bigcode/starcoder2-3b`

## REST API Fallback

Base URL:

```text
https://tunedtensor.com/api/v1
```

Authenticate REST calls with:

```text
Authorization: Bearer tt_your_api_key
```

Prefer these docs before constructing raw requests:

- `/docs/quickstart`
- `/docs/cli`
- `/docs/authentication`
- `/docs/behavior-specs`
- `/docs/runs`
- `/docs/datasets`
- `/docs/models`
- `/docs/billing`

## Safety Rules

- Never commit API keys, downloaded model artifacts, `.env` files, or credentials.
- Never commit local serving runtimes, extracted model directories, or model cache artifacts.
- Do not print full API keys in logs or final answers.
- Check `tt balance` before starting expensive or repeated runs.
- If a command fails with `402 insufficient_credits`, run `tt topup` or ask the user to add credits before retrying.
- Do not delete remote specs, datasets, runs, or models unless the user explicitly asks.