Configuration reference

Describe a run in a TOML config, then pass it to flash train. Every run requires project, model, and environment.id. algorithm defaults to sft. Run the submit-time checks without starting a run using flash train config.toml --dry-run; it allocates no training GPU, though an SFT config with no cached workload profile starts a billed profile run first (see flash train).

project = "00000000-0000-0000-0000-000000000000"
model = "Qwen/Qwen3.5-4B"
# model_revision = "main"
algorithm = "sft"
seed = 42

[environment]
id = "your-org/your-env"

[train]
epochs = 3
max_examples = 1000
lora_rank = 32

Top level

Key	Type	Default	Description
`project`	string	(required)	Freesolo project UUID that the run belongs to. Validated against your organization at submit time, before any GPU is allocated. Create one with `flash projects create`.
`model`	string	(required)	Base model to train a LoRA adapter on, e.g. `Qwen/Qwen3.5-4B`. See `flash models list`.
`model_revision`	string	`""`	Optional Hugging Face branch, tag, or commit for the base model. Empty uses the default revision. Authoring one makes the resulting run undeployable, so leave it empty unless you need the pin.
`algorithm`	string	`sft`	`sft` imitates completions, `grpo` learns from your reward, and `opd` distils from a managed teacher.
`seed`	int	`42`	Deterministic run seed for training order and sampling. Must be between `0` and `9223372036854775807`.
`thinking`	bool	`false`	Enable reasoning mode on a thinking-capable model. Reasoning and the answer share `max_completion_tokens`.

`[environment]`

Key	Type	Default	Description
`id`	string	(required)	Published Freesolo environment id, `your-org/your-env`.
`params`	table	`{}`	Keyword arguments passed to the env’s `load_environment(**kwargs)`. Flash also honors `split` for packaged env datasets. See Datasets: it selects the first of `dataset/<split>.jsonl`, `dataset/<split>.json`, `<split>.jsonl`, or `<split>.json` that exists, and a missing split file is an error (no silent `train.jsonl` fallback).
`pip`	list[string]	`[]`	Third-party requirements your scorer imports, installed on the worker alongside the managed runtime. See Scorer dependencies.
`secrets`	list[string]	`[]`	Environment variable names to make available to your environment at runtime. Values are read from your shell, `.env`, or `.env.local` at submit time.

[environment]
id = "your-org/your-env"
secrets = ["SERVICE_API_KEY"]

Environment code reads the secret normally:

import os

service_api_key = os.environ["SERVICE_API_KEY"]

Never put secret values in [environment.params]; those values are recorded on the run. Every name you list under [environment].secrets must resolve to a value in your shell, .env, or .env.local when you submit. Names such as FREESOLO_API_KEY, RUN_ID, and GITHUB_TOKEN are reserved by Flash.

Scorer dependencies

If your reward function imports a third-party package the managed runtime does not ship, declare it under [environment] pip and the worker installs it before your environment loads:

[environment]
id = "your-org/your-env"
pip = ["pymongo==4.10.1", "rapidfuzz>=3.9"]

Each entry is a requirement string, so the list form is required - pip = "pymongo" is rejected with the bracketed form to use. Entry syntax is validated at submit, before a GPU is allocated, because a malformed entry would otherwise fail mid-install on hardware you are already paying for:

Only requirements, never pip options. A leading - (--no-deps, --target=..., --extra-index-url=...) is rejected: those change how the mandatory worker requirement installs.
No credentials in a URL. The spec is stored and uploaded in plaintext, so a token in a direct or VCS requirement URL would be written to the run record. Any userinfo before the host is rejected, as is any query string.

Private requirements that need authentication to install are therefore not supported: [environment] secrets supplies values to your environment at runtime, after installation, so it cannot authenticate pip. Vendor the package into the folder you publish, or depend on a publicly installable one. Your requirements install alongside Flash’s own managed worker requirement rather than replacing it, so the runtime your environment loads into is never displaced. A transient package-index failure is retried before the run is given up on; a genuine resolution or build failure is terminal, because retrying it would only burn GPU time. A dependency you forgot to declare otherwise surfaces on the worker as a scorer that cannot import. flash env test runs against your local interpreter, so a package installed on your machine but missing from pip passes locally and fails only once the run starts - declare everything your scorer imports, rather than relying on a local pass.

`[train]`

[train] is one flat table shared by all three algorithms. Keys that apply everywhere are below; the rest are scoped by algorithm and a knob the run’s algorithm cannot consume is rejected at submit rather than silently ignored. See Knobs are scoped by algorithm.

Key	Type	Default	Description
`lora_rank`	int	`32`	LoRA rank; higher means a larger adapter with more capacity and cost. Flash enforces the per-model max rank. Omit with `init_from_adapter`; the source rank is authoritative. See context window and LoRA rank.
`lora_alpha`	int	`2 * lora_rank`	LoRA scaling factor. Omit it for the tuned `2 * lora_rank` default; set it to depart from that ratio. Rejected alongside `init_from_adapter`, where the source adapter’s alpha is authoritative. Requires Flash 1.1.35.
`learning_rate`	float	recipe default	Optimizer learning rate.
`batch_size`	int	recipe default	SFT only. The optimizer batch, resolved against the measured workload profile. GRPO and OPD reject it - see The optimizer batch has a different name per algorithm.
`prompts_per_step`	int	`64` / `8`	GRPO and OPD only. Prompts drawn per optimizer update. Defaults to `64` for GRPO and `8` for OPD. SFT rejects it. Requires Flash 1.1.43.
`max_context_tokens`	int	recipe default	Total training context cap. SFT applies it to the rendered sequence; GRPO and OPD apply it to prompt plus completion, and must leave room for a prompt once the completion budget is reserved. It cannot exceed the model’s training context cap. See context window.
`epochs`	int	recipe default	Passes over the retained rows or prompt pool when `max_steps` is not positive.
`max_examples`	int	see below	Rows or prompts retained from the dataset. Omitted or `0` means no cap. SFT keeps the first N in file order before the seeded shuffle; GRPO and OPD truncate the prompt pool, and need this or `max_steps` to be quotable - see GRPO and OPD need a stated horizon.
`max_steps`	int	derived	A positive value is the exact update horizon for SFT, GRPO, and OPD. Absent or non-positive uses the derived count, except on GRPO and OPD with no `max_examples` - see GRPO and OPD need a stated horizon.
`save_at_steps`	list[int]	`[]`	Strictly increasing positive steps to save a deployable checkpoint at. Requires positive `max_steps`, cannot exceed it, and suppresses `save_every`.
`save_every`	int	recipe default	Checkpoint cadence when `save_at_steps` is empty.
`init_from_adapter`	string	-	Continue a GRPO or OPD adapter from `RUN_ID` or the exact `RUN_ID/step-N` shown by `flash runs checkpoint`. Longer refs are rejected. Omit `lora_rank` and `lora_alpha`. If set, `model_revision` must match the source exactly.

--dry-run resolves warm-start rank and alpha for you. Local --cost may warn and estimate with defaults instead.

Knobs are scoped by algorithm

There are no [sft], [grpo], or [opd] tables: every knob lives under [train], and the error names the key you set. --dry-run surfaces these without allocating a GPU.

Knob	SFT	GRPO	OPD
`group_size`, `temperature`, `max_completion_tokens`, `kl_penalty_coef`, `stop_sequences`, `structured_outputs`	rejected	yes	yes
`entropy_quantile`, `thinking_length_penalty_coef`, `credit_assignment`	rejected	yes	rejected
`teacher_model`	rejected	rejected	yes
`batch_size`	yes	rejected	rejected
`prompts_per_step`	rejected	yes	yes

GRPO and OPD need a stated horizon

SFT measures its dataset, so an uncapped SFT config prices fine. GRPO and OPD quote offline from the catalog with nothing measuring the pool, so a config that sets neither max_examples nor a positive max_steps is refused rather than quoted:

cannot price grpo without a prompt-pool size: set [train] max_examples to the
row count the run will train on, or [train] max_steps to state the horizon
directly

Set either one. [environment.params] max_examples does not count: it reaches your environment as an opaque load_environment() kwarg that the starter templates ignore, so only [train] max_examples is applied by the worker.

The optimizer batch has a different name per algorithm

SFT authors batch_size; GRPO and OPD author prompts_per_step. They are not interchangeable, so each is rejected under the other algorithm, naming the key you meant:

[train] batch_size does not apply to grpo: use prompts_per_step instead.
batch_size is sft-only, and the two are different quantities -- prompts_per_step
is the optimizer batch itself, so copying an sft batch_size here would change how
many prompts each update trains on.

Under SFT, a measured workload profile turns batch_size into examples-per-update against your real tokenized dataset. Under GRPO and OPD there is no profile: prompts_per_step is the optimizer batch, and each step samples prompts_per_step x group_size completions. Do not carry a value across when porting a config: a typical SFT batch_size is far smaller than the 64 GRPO and 8 OPD defaults.

SFT-specific

Its only algorithm-only key is batch_size - every rollout knob is rejected, because SFT trains on your dataset’s completions and never generates.

When sequence packing is off

Flash packs multiple examples into one sequence when it can prove the packing is boundary-safe, which every catalog model on the managed worker image qualifies for. Multimodal rows are never packed. --cost, --dry-run, and train all warn when your run cannot pack. An unpacked run trains exactly one example per optimizer update, so batch_size no longer groups examples. It is not inert, though - it still keys the workload profile and sizes the GPU for an auto-sized run, so changing it can bill another profile run and move the card you land on. The default learning rate is tuned for a batched update, so expect noisier steps and lower learning_rate if you are comparing against a packed run.

GRPO-specific

Key	Type	Description
`prompts_per_step`	int	Prompts per optimizer update (default `64`). Each step samples `prompts_per_step x group_size` completions. SFT’s `batch_size` is rejected here.
`group_size`	int	Completions sampled per prompt. Must be at least `2`.
`temperature`	float	Sampling temperature for rollouts.
`max_completion_tokens`	int	Maximum generated tokens per completion or assistant turn.
`kl_penalty_coef`	float	Strength of the penalty that limits drift from the base model.
`entropy_quantile`	float	Restrict the GRPO policy update to the highest-entropy fraction of completion tokens. Between `0` and `1`; the default (unset) trains on all tokens, while a smaller value (for example `0.2`) trains on only the top-entropy tokens.
`thinking_length_penalty_coef`	float	Penalty on reasoning length.
`stop_sequences`	list[string]	Stop sequences for generation.
`structured_outputs`	string/table	Constrain each rollout to a JSON schema, regex, choice set, or any JSON. See Structured outputs.
`credit_assignment`	string	`per_episode` (default) scores one reward for the whole rollout; `per_turn` gives each assistant turn its own group-relative advantage in pure multi-turn GRPO. Tool-calling multi-turn environments require `per_episode`, and single-turn runs are equivalent either way. See per-turn credit.

OPD-specific

OPD derives updates from epochs, retained prompts, and prompts_per_step unless positive max_steps sets an exact horizon; one of those or max_examples is required. An SFT warm-start is recommended.

Key	Type	Default	Description
`teacher_model`	string	`glm-5.2`	Managed teacher alias from Managed teachers. Image prompts need an image-capable teacher. Teacher tokens are not billed to you.
`prompts_per_step`	int	`8`	Prompts per optimizer update. Rollout concurrency is `prompts_per_step x group_size`. SFT’s `batch_size` is rejected here.
`group_size`	int	`1`	Completions sampled per prompt.
`temperature`	float	`1.0`	Student sampling temperature.
`max_completion_tokens`	int	`512` (`1536` with `thinking`)	Maximum generated tokens per completion or assistant turn.
`kl_penalty_coef`	float	`1.0`	Reverse-KL strength. Must be greater than `0`.
`stop_sequences`	list[string]	-	Stop sequences for student completions.
`structured_outputs`	string/table	-	Guided decoding for each student rollout.

There is no auxiliary EOS loss. For termination problems, use an SFT warm-start, verify teacher quality, set a hard prompt budget, add suitable stop_sequences, and inspect truncated_rollouts. The local --cost estimate may itemize teacher usage for diagnosis, but only GPU time is charged.

Managed teachers

The teacher is platform-managed: teacher_model takes one of these friendly aliases, and a provider or repository identifier is never accepted. An unsupported value is rejected before a GPU is provisioned.

Alias	Teacher	Sees images
`glm-5.2`	GLM 5.2 (default)	no
`kimi-k3`	Kimi K3	no
`deepseek-v4-pro`	DeepSeek V4 Pro	no
`qwen3.5-397b-a17b`	Qwen3.5 397B A17B	yes
`qwen3-vl-235b`	Qwen3-VL 235B A22B	yes

Image-bearing OPD

Distilling a prompt that contains an image requires a teacher that can see it. Select one of the image-capable aliases above; any other teacher is rejected, with the aliases you can use named in the error. When the images are in your dataset file, Flash sees them at submit and rejects a text-only teacher before a GPU is allocated. When your environment code attaches the image instead - building it inside build_prompt_messages, say - nothing can see it until that code runs, so the same rejection happens on the worker after allocation. Both fail the run rather than distilling blind. The restriction is not bureaucratic. A text-only teacher answers a request carrying an image with a normal 200 and no indication that it ignored the pixels, so without the check a run would train, bill, and quietly distil from a teacher that never saw the image. Flash verifies the image survived into the teacher’s own tokenization and fails the run if it did not.

Multi-turn image-bearing OPD is not supported and is rejected up front. Single-turn image prompts are the supported shape. Requires Flash 1.1.42.

Structured outputs

structured_outputs constrains GRPO and OPD rollouts; SFT rejects it. Set exactly one JSON schema, regex, choice, or json_object constraint. Optional whitespace controls are documented in the guide. Combining constraints or using unsupported grammar forms is rejected. With thinking = true, reasoning remains free-form and the grammar begins after </think>. See Structured outputs.

`[gpu]`

Key	Type	Default	Description
`type`	string	`""`	Omit or leave empty for managed cheapest-fit allocation; set an active validated class from `flash gpus` to pin it exactly. Preflight rejects unavailable, unsupported, or undersized choices.
`count`	int	auto-size	Omit this and `type` to let Flash pick the smallest shape that fits; omitting only `count` while pinning `type` is a single-card pin. Set it to pin a ceiling of `1`-`8` cards. See Multi-GPU runs.
`provider`	string	`""`	Pin the GPU provider (`runpod`, `lambda`, or `vast`). Omit to let the allocator rank every configured provider. A provider that cannot supply the pinned `type` is rejected.

A pinned GPU class is honored on retries and in cost estimates. Use type when hardware identity matters; everything else about allocation is managed.

Multi-GPU runs

Omit both type and count and Flash sizes the run for you. It picks the smallest geometry-safe card count your configuration actually fits on, then ranks the fitting shapes by cost per step. A run that needs more memory than one card holds is placed on two, four, or eight instead of being rejected. Only rentable shapes are ever provisioned: 1, 2, 4, and 8. Setting count turns it into a hard ceiling that never escalates:

[gpu]
count = 4     # at most 4 cards; the allocator may still choose 1 or 2

A ceiling of 3 therefore never buys 4 cards - it permits 1 or 2. An explicit count = 1 on a run that does not fit one card is an error rather than a silent escalation, and it names the smallest count that would work:

grpo needs >= 229 GB VRAM; gpu.count=1 provides at most 180 GB (B200). Raise the
card ceiling with `--gpus 2` (2x H200 = 234.1 GB), or lower
[train].max_context_tokens / [train].max_completion_tokens / [train].lora_rank
to fit.

If nothing fits even at eight cards, the error names the knobs that actually shrink that algorithm - they differ per algorithm. See Pre-flight says the run is too large.

Pinning type without a count stays a single-card pin, so naming a specific card never quietly bills you for four of them. Auto-sizing applies only when you omit both.

flash train --gpus N sets the same ceiling from the command line without editing the config. Cost is quoted for the shape the run actually occupies, so a multi-card run is priced on every card it held.

`[wandb]`

Optional Weights & Biases logging labels. These values are non-secret; set WANDB_API_KEY in your local environment when submitting a run to enable logging to your own W&B account.

Key	Type	Description
`project`	string	W&B project name.
`run_name`	string	W&B run name.

Overrides & composition

Set any value at submit time without editing the file. The override flag is --set (repeatable, dotted keys):

flash train config.toml --set train.epochs=3 --set train.lora_rank=16
flash train base.toml --config overlay.toml      # deep-merge extra TOML
flash train config.toml --gpus 4                 # sugar for --set gpu.count=4

The config file is the base, --config overlays merge onto it, and --set/--gpus win over both, applied left to right. An absent --gpus is indistinguishable from no flag, so a [gpu] count authored in the file is never silently downgraded.

Get started

Flash

Reference

Top level

`[environment]`

Scorer dependencies

`[train]`

Knobs are scoped by algorithm

GRPO and OPD need a stated horizon

The optimizer batch has a different name per algorithm

SFT-specific

When sequence packing is off

GRPO-specific

OPD-specific

Managed teachers

Image-bearing OPD

Structured outputs

`[gpu]`

Multi-GPU runs

`[wandb]`

Overrides & composition

​Top level

​[environment]

​Scorer dependencies

​[train]

​Knobs are scoped by algorithm

​GRPO and OPD need a stated horizon

​The optimizer batch has a different name per algorithm

​SFT-specific

​When sequence packing is off

​GRPO-specific

​OPD-specific

​Managed teachers

​Image-bearing OPD

​Structured outputs

​[gpu]

​Multi-GPU runs

​[wandb]

​Overrides & composition

Top level

`[environment]`

Scorer dependencies

`[train]`

Knobs are scoped by algorithm

GRPO and OPD need a stated horizon

The optimizer batch has a different name per algorithm

SFT-specific

When sequence packing is off

GRPO-specific

OPD-specific

Managed teachers

Image-bearing OPD

Structured outputs

`[gpu]`

Multi-GPU runs

`[wandb]`

Overrides & composition