Configuration reference

Describe a run in a TOML config, then pass it to flash train. Every run requires model and environment.id; SFT also requires a positive train.max_examples. algorithm defaults to sft. Run authenticated submit-time preflights with flash train config.toml --dry-run; it creates state=dry_run, allocates no GPU, and charges nothing.

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
`model`	string	(required)	Base model to train a LoRA adapter on, e.g. `Qwen/Qwen3.5-4B`. See `flash models`.
`model_revision`	string	`""`	Optional Hugging Face branch, tag, or commit. Empty uses the default revision; a value pins all student-model loads.
`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 `dataset/<split>.jsonl`, and a missing split file is an error (no silent `train.jsonl` fallback).
`pip`	list[string]	`[]`	Extra third-party pip requirements the worker installs before importing your environment (an escape hatch for deps your `environment.py` imports).
`secrets`	list[string]	`[]`	Environment variable names to forward to the worker as runtime secrets. Values are read from your shell, `.env`, or `.env.local` at submit time.

[environment]
id = "your-org/your-env"
pip = ["openai>=1.0.0"]
secrets = ["SERVICE_API_KEY"]

Environment code reads the secret normally:

import os

service_api_key = os.environ["SERVICE_API_KEY"]

[environment].pip is the worker install path for reward and environment dependencies. Do not rely on pyproject.toml, requirements.txt, or lockfiles inside the published environment artifact for managed training installs. Those files may describe your local development environment; runtime packages belong in this config list. Never put secret values in [environment.params]; it becomes part of the run spec. Every name you list under [environment].secrets must resolve to a value in your shell, .env, or .env.local when you submit. Reserved platform secret names such as FREESOLO_API_KEY, HF_TOKEN, GITHUB_TOKEN, RUN_ID, and HF_REPO are owned by Flash.

`[train]`

Key	Type	Default	Description
`lora_rank`	int	`32`	LoRA rank; higher means a larger adapter with more capacity and cost. Flash enforces the base model serving cap. Omit with `init_from_adapter`; the source rank is authoritative. See context window and LoRA rank.
`lora_alpha`	int	`64`	LoRA alpha. Omit with `init_from_adapter`; the source alpha is authoritative.
`learning_rate`	float	recipe default	Optimizer learning rate.
`batch_size`	int	recipe default	Training batch size.
`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. It cannot exceed the base model serving context. See context window.
`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.
`save_at_steps`	list[int]	`[]`	Strictly increasing positive required saves. Requires positive `max_steps`, cannot exceed it, and suppresses `save_every`. Each step must durably publish the deployable adapter and full resume checkpoint.
`save_every`	int	recipe default	Periodic cadence when `save_at_steps` is empty. Upload attempts are synchronous but remain best-effort after bounded retries.
`init_from_adapter`	string	-	Continue a GRPO or OPD adapter from `RUN_ID` or the exact `RUN_ID/step-N` shown by `flash checkpoints`. Longer storage refs are rejected. Omit rank and alpha. If set, `model_revision` must match the source exactly.

Server-side --dry-run resolves warm-start rank and alpha. Local --cost may warn and estimate with defaults.

SFT-specific

Key	Type	Description
`epochs`	int	Passes over retained rows when `max_steps` is not positive.
`max_examples`	int	Required positive row count. Retains the first N rows in file order before seeded shuffle; use the full row count for an uncapped run.

GRPO-specific

Key	Type	Description
`epochs`	int	Passes over the retained prompt pool when `max_steps` is not positive.
`max_examples`	int	Truncate the prompt pool to N examples (`0` = no cap).
`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.
`advantage_clip`	float	Recorded for recipe parity but currently a no-op; the runtime clips the importance ratio instead.
`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.

OPD-specific

OPD derives updates from epochs, retained prompts, and batch size unless positive max_steps sets an exact horizon. An SFT warm-start is recommended.

Key	Type	Default	Description
`teacher_model`	string	`glm-5.2`	Managed teacher: `glm-5.2`, `deepseek-v4-pro`, or `kimi-k2.6`. Unsupported ids are rejected. Teacher tokens are not billed to you.
`epochs`	int	recipe default	Passes over retained prompts when `max_steps` is not positive.
`max_examples`	int	`0`	Truncate the prompt pool to N examples (`0` = no cap).
`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. advantage_clip and thinking_length_penalty_coef do not apply to OPD.

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
`provider`	string	`""`	Omit or leave empty for automatic selection; `runpod`, `lambda`, or `vast` pins the provider.
`exact_type`	string	`""`	Pin an active validated GPU exactly as shown by `flash gpus`. Preflight rejects unavailable, unsupported, or undersized choices.
`max_retries`	int	`5`	Nonnegative retry count. `0` means exactly one provider submission.
`max_wall_seconds`	int	`86400`	Maximum run wall time in seconds; minimum `60`.

Provider and exact-GPU constraints persist across retries and cost estimates. Use exact_type when hardware identity matters.

`[worker_env]` (advanced)

[worker_env] passes non-secret string values into the worker environment and is serialized into the run spec and artifacts. Use it only for harmless labels or feature flags. Secret-looking keys and values are rejected; runtime secrets belong in [environment].secrets. SEED, RUN_ID, HF_REPO, and FLASH_ARM are control-plane-owned and cannot be overridden here.

[worker_env]
FEATURE_FLAG = "enabled"

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

Get started

Flash

Reference

Top level

`[environment]`

`[train]`

SFT-specific

GRPO-specific

OPD-specific

Structured outputs

`[gpu]`

`[worker_env]` (advanced)

`[wandb]`

Overrides & composition

Next steps

Training

Troubleshooting

​Top level

​[environment]

​[train]

​SFT-specific

​GRPO-specific

​OPD-specific

​Structured outputs

​[gpu]

​[worker_env] (advanced)

​[wandb]

​Overrides & composition

​Next steps

Training

Troubleshooting

Top level

`[environment]`

`[train]`

SFT-specific

GRPO-specific

OPD-specific

Structured outputs

`[gpu]`

`[worker_env]` (advanced)

`[wandb]`

Overrides & composition

Next steps