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

# Fine-tuning studio

> Configure and review SFT or native RL in Ghostty or another terminal, monitor retained runs, and hand off the same workspace to an agent.

Open the studio from the reviewed StateSet Agents environment:

```bash theme={null}
stateset-agents tui --workspace outputs/finetune
```

It uses POSIX curses without a web server or separate UI installation. Ghostty and Herdr
terminal panes are supported; Windows requires WSL. The same workspace is available to the
[JSON agent CLI](/stateset-agents/finetuning-agents).

## Navigate and review

| Control | Action |
| - | - |
| `Ctrl+P` or `:` | Search commands or open Actions |
| `w` | Guided settings/data/runtime/launch/evaluation checklist |
| `b`, `m`, `f` | Select backend, model, or dataset path |
| `u` | Inspect data in the background; examples stay hidden until explicitly revealed |
| `v`, `i` | Configuration checklist and local readiness |
| `p`, `r` | Preview, then capture the launch review |
| Enter in launch review | Submit the exact reviewed run |
| Tab | Switch Configure/Runs |
| `l`, `x` on Runs | Inspect logs or compare runs; neither selects a quality winner |
| `j`, `z`, `k` on Runs | Evaluation, checkpoint recovery, or local stop review |
| `q` or Ctrl+C | Close the UI; launched jobs continue |

Select settings, validate the configuration, and inspect the dataset before reviewing a
launch. Preview and review capture data in the background. Esc abandons an outdated read
without letting a late result reopen a launch screen. A separate Enter in the displayed
review starts work.

Runs retain IDs, plan checksums, metrics, logs, provider handles, and known failures. Reopen
the same workspace to reconnect. Select an agent-prepared run and press `r` to review and
launch that same ID. `c` reuses settings for a new run; it does not restore optimizer state.

## Training data

Studio SFT uses text-only chat JSONL: an optional initial system message, alternating
user/assistant turns, and a final assistant target. Message content must be nonempty text.

```jsonl theme={null}
{"messages":[{"role":"user","content":"What is the example return policy?"},{"role":"assistant","content":"The example policy allows returns within 30 days."}]}
```

Native GRPO/GSPO/DAPO use a JSON list of support scenarios:

```json theme={null}
[
  {
    "id": "damaged-item",
    "context": "The customer says their item arrived damaged.",
    "policy_facts": ["Damaged items may be replaced at no charge."],
    "expected_resolution": "Offer a replacement using the supplied policy.",
    "user_responses": ["Please send a replacement."],
    "must_avoid": ["Your refund has already been processed"]
  }
]
```

These are synthetic format examples. Native RL uses support reward v3, zero-dropout LoRA,
a frozen reference, and a positive KL coefficient. The step budget counts committed
optimizer updates. SFT and RL input formats are not interchangeable.

Generated [industry training files](/stateset-agents/industry-finetuning) retain declared
synthetic provenance in inspection, snapshots, and review. Declared validation/test rows
are rejected as training input even after renaming the file. The broader industry tool-data
contract has capabilities beyond the studio's text-only SFT form.

## Backends and billing

| Backend | Studio methods | Requirements and result |
| - | - | - |
| Local | SFT, GRPO, GSPO, DAPO | CUDA, training dependencies, local Buildr resources; local weights |
| RunPod | SFT | `RUNPOD_API_KEY`, reviewed GPU request and quoted pod-lifetime ceiling; downloaded weights |
| Modal | SFT | Modal extra/authentication and `cost_policy: provider_billed`; downloaded weights |
| River | SFT | Python 3.12+, River extra, `RIVER_API_KEY`, and `cost_policy: provider_billed`; hosted pointer |

RunPod's ceiling excludes ancillary costs. Modal and River have no enforced dollar ceiling
in this integration. River manages hardware and rejects GPU overrides. Local readiness
does not authenticate any provider or certify that a model fits a GPU.

Remote jobs retain the reviewed framework release identity. Modal installs the matching
published release remotely rather than uploading uncommitted local source. A reviewed RunPod
development wheel can be snapshot-bound by hash. Neither mechanism attests the entire remote
dependency/runtime environment. Confirm publication and backend support before live use.

RunPod/Modal details expose retained submission IDs, allocation intent, and cleanup
acknowledgements. Inspect them with `finetune provider-status RUN_ID`. These are local
observations, not live provider status. An interrupted allocation may have succeeded without
returning an ID; a cleanup acknowledgement does not establish that charges stopped.

## Checkpoints, stopping, and quality

Set a training seed independently of evaluation randomness. A full model commit is required
for exact recovery; an unpinned run does not acquire reproducible identity from its model name.
Local native RL can set `checkpoint_every` to a positive committed-update interval, capped
at 100 planned checkpoints. Zero keeps final-only behavior. SFT saves epoch checkpoints;
remote backends do not support this native interval setting.

`k` opens a checksum-bound cooperative local stop. Prepared runs cancel immediately; queued
workers check before loading; active SFT stops at a step boundary and native RL saves after
a committed update. A stop request does not kill a PID or confirm immediate exit. Remote
cleanup remains provider-specific.

`z` inspects exact recovery; `j` manages local paired evaluation and checkpoint validation.
These workflows require their own reviews. Read [recovery and evaluation](/stateset-agents/checkpoints-and-evaluation)
before treating a checkpoint or successful run as a quality result.

## Small terminals

Phone-sized panes work from **32 columns × 16 rows**. Below 72 × 22, compact navigation uses
`2/8` to move, `3/9` to page, `0` to go back, and `4` to switch main screens outside editors.
Digits remain literal in editors and search. An undersized resize pauses actions, including
hidden confirmation keys.

```bash theme={null}
stateset-agents tui --snapshot --columns 40 --rows 24
```

Snapshot mode writes no draft and launches no work. Source basis: the October 20, 2026
`docs/FINETUNING_TUI.md` and the live `finetune schema` from the reviewed checkout.
Start with [the preparation quickstart](/stateset-agents/quickstart).


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