> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tuneplane.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Install the CLI, submit a GRPO job, and see the first point land on the loss curve.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
uv tool install tuneplane
tp init my-lab --yes && cd my-lab
tp login --server https://tuneplane.your-company.com
tp new my-grpo --method nemo-rl/grpo
git add -A && git commit -m "first grpo run"
tp submit my-grpo --profile h200:8
```

That queues a GRPO run on 8 GPUs and prints a job id. The rest of this page is the same
sequence with the detail you need when a step does not go through.

## Before you start

* An account on a TunePlane deployment, and its URL. An administrator creates it, or the
  deployment uses single sign-on.
* Quota, and at least one hardware profile you are allowed to use. `tp status` prints both
  after you log in. Every profile name on this site is an example — use the ones `tp status`
  gives you.
* The cluster must be able to reach `Qwen/Qwen2.5-1.5B`, which is what the scaffold trains. On
  an air-gapped network an administrator points the deployment at an internal mirror. Without
  one the job starts, stalls downloading weights, and times out. See
  [air-gapped deployments](https://docs.tuneplane.ai/en/ops/airgapped.md).

Object storage is not needed for this path. It is needed for `tp dataset push` and for
automatic evaluation after training.

**1. Install the CLI and create a project**

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
uv tool install tuneplane     # or: pip install tuneplane
tp init my-lab --yes
cd my-lab
```

`tp init` writes `experiments/`, `configs/` and `common/`, plus a `tuneplane.yaml` marker
that tells `tp` where your project root is. It also makes a git repository and one commit.

Do not clone the platform repository. `tp init` is what creates your project. Upgrade later
with [`tp update`](https://docs.tuneplane.ai/en/cli/update), not by reinstalling by hand.

**2. Log in**

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
tp login --server https://tuneplane.your-company.com
```

Opens a browser. On an SSH session add `--device-flow`. In CI pass `--token`. Credentials
land in `~/.tuneplane/`.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
tp status
```

Prints your account, your quota, and the profile names this deployment has. Note one — the
submit step needs it.

![TunePlane console login page](https://mintcdn.com/starforge/GatXR2rI5-_Vm4_H/images/console/login.png?fit=max\&auto=format\&n=GatXR2rI5-_Vm4_H\&q=85\&s=2306521111801b18e089d0ddd58a6667)

Console sign-in. Username and password, or single sign-on where the deployment has it.

**3. Create an experiment**

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
tp new my-grpo --method nemo-rl/grpo
```

Writes `experiments/my-grpo/` holding `config.yaml`, `README.md` and `recipe.lock.json`.
The lock file pins the method version, so the run is reproducible even after the catalogue
moves on.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
tp methods                 # every method this deployment offers
tp methods nemo-rl/grpo    # what you can tune, with ranges and defaults
```

**4. Tune and validate**

Edit `experiments/my-grpo/config.yaml`. Learning rate, prompts per step and generations per
prompt are at the top.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
tp validate my-grpo
```

Checks types, ranges and batch-size divisibility against the method declaration. A typo
fails here in seconds instead of after a queue wait.

**5. Submit**

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
git add -A && git commit -m "first grpo run"
tp submit my-grpo --profile h200:8
```

Prints a job id. `--profile` is the only resource flag: `h200` takes the registry's default
shape, `h200:4` asks for four GPUs, `h200:16` for two full nodes.

A dirty working tree is refused. Pass `--allow-dirty` to submit anyway.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
tp job logs        # omit the id to follow the latest job
```

Status moves `QUEUED` → `SUBMITTED` → `PENDING` → `RUNNING`. `QUEUED` means admitted but
not yet on the cluster. See [job states](https://docs.tuneplane.ai/en/concepts/job-lifecycle.md).

**6. Watch it in the console**

Open the console, go to **Jobs**, and click your run.

| Tab | What it shows |
| - | - |
| Charts | Loss, reward, KL, gradient norm, step by step |
| Logs | The full stream, searchable and downloadable |
| Validation | Sample conversations and reward histograms |
| System | GPU utilisation, memory, network |
| Diagnosis | On a failure or an odd curve, a report and the knobs worth trying |

![TunePlane job charts tab](https://mintcdn.com/starforge/GatXR2rI5-_Vm4_H/images/console/job-charts.png?fit=max\&auto=format\&n=GatXR2rI5-_Vm4_H\&q=85\&s=f0cbc511c02bb6a4b59b74c5575899ce)

Job charts during a GRPO run: reward, accuracy, and training scalars.

## Check it worked

Read this in order. If one row does not match, stop there — every row below assumes the one
above happened.

| When | What you should see | If it does not match |
| - | - | - |
| After `tp status` | Your username, your quota, at least one profile name | Login did not finish, or you have no quota yet |
| After `tp submit` | A job id, state `QUEUED` or `SUBMITTED` | A refusal names the gate that refused it. See [errors](https://docs.tuneplane.ai/en/api-reference/errors.md) |
| 1–3 min | State turns `RUNNING` | Still `QUEUED`: the job page names the gate holding it |
| 3–8 min | Logs show the weight download, then Ray starting | Stuck downloading: the mirror. See [air-gapped](https://docs.tuneplane.ai/en/ops/airgapped.md) |
| 8–15 min | The first point on the Charts tab | Logs moving, charts empty: see below |

Once that first point appears, the path worked.

If logs move but charts stay empty, first identify the reporting path. SDK reporting needs
a reachable ingest endpoint and [`tuneplane.report`](https://docs.tuneplane.ai/en/api-reference/python-sdk) calls.
Native TensorBoard/JSONL outputs need declared sources, the collector and a reachable
[telemetry gateway](https://docs.tuneplane.ai/en/ops/telemetry.md); stdout alone does not create points.

## Next

Change what `tp submit` does in [submitting a job](https://docs.tuneplane.ai/en/guides/submit.md). Run many variants at
once with [sweeps](https://docs.tuneplane.ai/en/guides/sweep.md). Score the result against GSM8K or C-Eval in
[benchmarks](https://docs.tuneplane.ai/en/guides/benchmarks.md). If the method you need is not in the catalogue, bring your
own trainer with [custom training](https://docs.tuneplane.ai/en/guides/custom-training.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.