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. flash train config.toml --dry-run runs submit-time checks without starting paid training or allocating a training GPU. See Cost and billing for estimate behavior.

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

[environment]
id = "your-org/your-project/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`.
`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)	Environment source accepted by the control plane. Managed Freesolo requires a published `namespace/project/name` slug. A standalone plane requires a `github:` reference or supported GitHub repository, tree, or blob URL that resolves to `environment.py`, and rejects managed slugs. Local paths are not valid training sources.
`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-project/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-project/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. Examples per optimizer update. 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 any finished 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`; the source adapter’s values are authoritative. See Warm-start from any algorithm.

--dry-run resolves warm-start rank, alpha, and the source base-model identity for you. Local --cost may warn and estimate with defaults instead.

Warm-start from any algorithm

init_from_adapter works for every source/target pair. SFT, GRPO, and OPD each read a source adapter produced by any of the three, including same-algorithm continuation - sft → sft to keep training on more data, or grpo → grpo to extend a run. SFT was previously rejected as a warm-start target; it is now accepted like the other two.

algorithm = "sft"   # or "grpo", or "opd" - any of the three

[train]
# the source run id, from any algorithm. add /step-N to continue a specific
# checkpoint listed by `flash runs checkpoint <run-id>`.
init_from_adapter = "<source-run-id>"

Across the lineage keep the same base model. The source adapter’s rank and alpha are authoritative, so setting lora_rank or lora_alpha alongside init_from_adapter is rejected at submit, and a source rank above the model’s serving cap is rejected too. A warm-started SFT run also inherits its source’s base-model pin rather than resolving its own, so the continued adapter stays deployable when the base model’s upstream tip moves.

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 estimates its packaged dataset, so an uncapped SFT config prices fine. GRPO and OPD quote offline from the catalog with nothing reading the prompt 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, batch_size is examples per optimizer update. Under GRPO and OPD, prompts_per_step is prompts per optimizer update, 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 examples when it can do so safely; multimodal rows are never packed. --cost, --dry-run, and train warn when packing is off. An unpacked run trains exactly one example per optimizer update, regardless of a larger authored batch_size. That value can still affect the quote and GPU choice. The default learning rate assumes a batched update, so expect noisier steps and consider a lower learning_rate than for 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. See the rollout shape.
`group_size`	int	Completions sampled per prompt. Exactly `2`, `4`, or `8`; defaults to `8`. See the rollout shape.
`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.

The GRPO rollout shape is a fixed set

GRPO group_size accepts exactly 2, 4, or 8, and defaults to 8. Any other value - including 1, 3, 6, or anything above 8 - is rejected at submit, before a GPU is looked up or allocated. Flash never rewrites the value you authored, so an unsupported group_size fails fast instead of quietly training a different shape than you asked for. A step also has a completion ceiling:

train.prompts_per_step * train.group_size must be <= 512 for GRPO
(got 128 * 8 = 1024)

The default 64 x 8 is exactly 512. Admission checks the authored values, or their defaults when omitted, so an oversized shape is refused up front - a smaller retained dataset cannot rescue it later. To raise one factor, lower the other. At execution the effective prompt count may clamp down to the number of valid prompts left after max_examples and prompt-budget filtering; group_size is never changed. Rollout generation, reward work, and cost all scale with the effective prompts_per_step x group_size product. These limits are GRPO’s. OPD keeps its own group_size default of 1 and is not restricted to the same set.

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.

Multi-turn image-bearing OPD is not supported. Flash rejects statically visible image-bearing multi-turn inputs before allocation, while images attached later by environment execution are rejected by the worker guard. 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 or list[string]	omitted	A string hard-pins one active validated class from `flash gpus`. A non-empty list names acceptable classes; list order is not priority because quoting and allocation cost-rank the whole set. Every entry must be supported, provider-compatible, and large enough. Omit it for managed cheapest-fit allocation.
`count`	int	auto-size	Omit this and `type` to let Flash pick the smallest shape that fits. Authoring either form of `type` without `count` is a single-card constraint. Set `count` to pin a ceiling of `1`-`8` cards. See Multi-GPU runs.
`provider`	string	omitted	Hard-pin one GPU provider: `runpod`, `lambda`, or `vast`. The provider must be able to provision every acceptable `type`. Cannot be combined with `providers`.
`providers`	list[string]	omitted	Ordered soft provider preference. When authored, the list must be non-empty. Named configured providers are preferred in order, but configured providers omitted from the list remain eligible. Use `provider` instead when other providers must be excluded. Cannot be combined with `provider`.

The authored class constraint and provider routing are honored in estimates, submissions, and retries. Use a scalar type or provider when hardware or provider identity is mandatory; use lists when several outcomes are acceptable.

[gpu]
type = ["A100 PCIe", "A100 SXM"]
providers = ["lambda", "runpod"]

This allows either GPU class, prefers Lambda and then RunPod, and still permits another configured provider if neither preference can place the run. Replace providers with provider = "lambda" to make Lambda a hard requirement.

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.

Authoring type without a count, whether as a scalar pin or an acceptable list, stays a single-card constraint. Auto-sizing across multiple cards applies only when you omit both keys.

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. A run’s VRAM requirement is a whole-run figure, and a multi-card shape pools its cards to meet it. The quote spells out both numbers so a shape that fits does not read as a rejection:

GPU : 2x B200 (300 GB usable across 2x 180 GB; run needs >= 199 GB) @ $5.89/hr per card

The per-card size stays visible because that is what you check against a provider listing. If an authored single-card pin cannot hold the run, the error now names the card count that would - for example it fits on 2 cards -- raise the card ceiling with --gpus 2 - so a run needing more than the largest single card is not a dead end.

`[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]`

Warm-start from any algorithm

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

The GRPO rollout shape is a fixed set

OPD-specific

Managed teachers

Image-bearing OPD

Structured outputs

`[gpu]`

Multi-GPU runs

`[wandb]`

Overrides & composition

​Top level

​[environment]

​Scorer dependencies

​[train]

​Warm-start from any algorithm

​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

​The GRPO rollout shape is a fixed set

​OPD-specific

​Managed teachers

​Image-bearing OPD

​Structured outputs

​[gpu]

​Multi-GPU runs

​[wandb]

​Overrides & composition

Top level

`[environment]`

Scorer dependencies

`[train]`

Warm-start from any algorithm

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

The GRPO rollout shape is a fixed set

OPD-specific

Managed teachers

Image-bearing OPD

Structured outputs

`[gpu]`

Multi-GPU runs

`[wandb]`

Overrides & composition