> ## Documentation Index > Fetch the complete documentation index at: https://docs.freesolo.co/llms.txt > Use this file to discover all available pages before exploring further. # Configuration reference > Every field in a Flash training config (TOML). 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. ```toml theme={null} 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`](/reference/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](/guides/environments/package#publish-it) 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](/guides/datasets#load-sidecars): it selects `dataset/.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. | ```toml theme={null} [environment] id = "your-org/your-env" pip = ["openai>=1.0.0"] secrets = ["SERVICE_API_KEY"] ``` Environment code reads the secret normally: ```python theme={null} 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](/reference/models#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](/reference/models#context-window-and-lora-rank). | | `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](/guides/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 ``. See [Structured outputs](/guides/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. ```toml theme={null} [worker_env] FEATURE_FLAG = "enabled" ``` ## `[wandb]` Optional [Weights & Biases](https://wandb.ai) 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): ```bash theme={null} flash train config.toml --set train.epochs=3 --set train.lora_rank=16 flash train base.toml --config overlay.toml # deep-merge extra TOML ``` ## Next steps See these fields in the run lifecycle. Fix common config and run errors.