Quickstart

Go from an empty directory to a deployed model. Train a LoRA adapter on managed infrastructure, serve it, and chat with it from the CLI.

Prerequisites

Python 3.11 or 3.12, with uv, pipx, or pip to install the CLI.
A Freesolo API key, created in your dashboard at freesolo.co. Commands that contact Freesolo, including --dry-run and an SFT --cost, authenticate with it. A GRPO or OPD --cost quotes offline from the catalog. Neither submits a training run.

Step 1: Install the CLI

uv tool install freesolo-flash

pipx install freesolo-flash

pip install freesolo-flash

Step 2: Log in

flash login --api-key <your-freesolo-key>

Flash verifies the key against Freesolo and stores it locally, so you only do this once. You can also set FREESOLO_API_KEY instead of passing --api-key.

flash whoami    # confirm who your stored key resolves to

Step 3: Create a project

Every run and environment belongs to a project. Create one and keep its UUID; the next steps need it.

flash projects create my-project

This prints the project UUID. flash projects list shows them all later.

Step 4: Scaffold an environment

Already have a published environment id, yours or one shared with you? Set it as [environment] id in your config and skip ahead to step 6.

flash env setup --project <project-uuid>

This writes a ready-to-edit starter into the current directory:

environment.py            # a Freesolo environment (task + reward)
evaluations.py            # held-out eval suites for flash env eval
dataset/
  train.jsonl             # a tiny starter dataset (input/output rows)
configs/
  sft.toml                # an SFT training config to start from
  rl.toml                 # a GRPO (RL) training config to start from
  opd.toml                # an OPD (distillation) training config to start from
TRAINING.md               # agent playbook with common run issues and mitigations

Rerunning is safe: flash env setup leaves any file that already exists untouched.

Already have a training loop?

Skip the hand-editing. Point your coding agent (Claude Code, Cursor, etc.) at the environment guide and have it find and port your existing reward and dataset into environment.py. A prompt to start from:

I already have a training loop with a reward function and a dataset, and I
want to run it on Freesolo Flash. Find my reward function and dataset in this
project, then read https://docs.freesolo.co/guides/environments/overview and
create an environment.py whose load_environment() returns an
EnvironmentSingleTurn (use EnvironmentMultiTurn for multi-step tasks). Port my
reward into score_response and wire my dataset in as the input/output records
load_environment() returns. Then fill in the matching training config in
configs/ (sft.toml for SFT, rl.toml for GRPO, opd.toml for OPD) with the base
model and [train] settings.

Step 5: Publish your environment

An environment is the task and reward your model trains on. Publish the scaffolded one to the managed Environments Hub to get an id:

flash env push --project <project-uuid> --name starter .

This prints an environment id of the form your-org/starter.

Step 6: Configure and validate your run

flash env setup already wrote project into each generated config. Open configs/sft.toml and set the one thing that’s yours, the environment id from the previous step:

configs/sft.toml

model = "Qwen/Qwen3.5-4B"
project = "<project-uuid>"
algorithm = "sft"

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

[train]
epochs = 1
max_examples = 2
lora_rank = 32

Validate it first. --dry-run applies the real submit-time checks, including unrecognized [train] keys, without allocating a training GPU. On an SFT config with no cached workload profile it starts a short billed profile run first; see flash train:

flash train configs/sft.toml --dry-run

That first --dry-run starts the workload profile and prints its run id. Wait for it before going on, or the next two commands only join the profile instead of quoting and training:

flash runs status <profile-run-id> -f

Once it reports done, see what the run will cost before committing. --cost prints the pre-flight USD cost and never submits a training run:

flash train configs/sft.toml --cost

Step 7: Train

flash train configs/sft.toml

This is the first step that spends money on training, though on an SFT config the profile run behind --dry-run and --cost above was already billed on its own. At submit time Flash checks your org balance against the pre-flight estimate, then bills successful runs at the quoted Flash cost. Setup and cold start time are reported separately for observability and are not billed.

Flash then follows the logs live. Press Ctrl-C to detach. The run keeps going on the server, and you can follow it again any time:

flash runs list                # list your runs and their state/cost
flash runs status <run-id>     # status JSON, including the cost record
flash runs log <run-id> -f     # stream logs until the run finishes

The run reaches done when training finishes. Start small: finish one short run end to end before you scale up. When you do, raise train.epochs or train.max_examples and change little else.

Step 8: Deploy

Serve the trained adapter on Freesolo’s managed serving service. Serving is billed per token for requests you send:

flash models deploy <run-id> --wait

Every real deploy resolves an immutable adapter revision and runs a bounded serving smoke before the stable run-id alias is activated. Without --wait the command returns while the revision is still queued, so the next step would call a model that is not servable yet. You can also deploy and tear down from the dashboard.

Step 9: Chat

flash models chat <run-id> -m "Hello! What can you do?"

That completes the loop. When you’re done, tear the endpoint down:

flash models undeploy <run-id>

Essential commands

The commands you used above, plus the ones you’ll reach for next. Run flash <command> --help for the full set of flags, or see the CLI reference.

Command	What it does	Example
`flash login`	Store your Freesolo API key locally	`flash login --api-key <key>`
`flash projects create`	Create a project and print its UUID	`flash projects create my-project`
`flash projects list`	List your projects and their UUIDs	`flash projects list`
`flash env setup`	Scaffold a starter environment and configs	`flash env setup --project <uuid>`
`flash env push`	Publish an environment and print its id	`flash env push --project <uuid> --name starter .`
`flash env eval`	Score held-out suites against a deployment	`flash env eval <run-id>`
`flash train`	Submit a run and follow its logs	`flash train configs/sft.toml`
`flash train --dry-run`	Run server preflights, no training GPU	`flash train configs/sft.toml --dry-run`
`flash train --cost`	Preview the pre-flight cost, no training run	`flash train configs/sft.toml --cost`
`flash runs list`	List your runs with state, cost, and model	`flash runs list`
`flash runs status`	Show run status and cost	`flash runs status <run-id>`
`flash runs log`	Print or follow a run’s logs	`flash runs log <run-id> -f`
`flash models deploy`	Serve a trained adapter	`flash models deploy <run-id>`
`flash models chat`	Send a message to a deployment	`flash models chat <run-id> -m "hi"`
`flash models undeploy`	Tear a deployment down	`flash models undeploy <run-id>`

Next steps

How Flash works

The loop behind a run, and the concepts each command refers to.

Training in depth

SFT, GRPO, and OPD, config options, monitoring, and cost.

Build an environment

Replace the starter task with your own data and reward.

Deploy & chat

Serving billing and the OpenAI-compatible API.

Get started

Flash

Reference

Prerequisites

Step 1: Install the CLI

Step 2: Log in

Step 3: Create a project

Step 4: Scaffold an environment

Step 5: Publish your environment

Step 6: Configure and validate your run

Step 7: Train

Step 8: Deploy

Step 9: Chat

Essential commands

Next steps

How Flash works

Training in depth

Build an environment

Deploy & chat

​Prerequisites

​Step 1: Install the CLI

​Step 2: Log in

​Step 3: Create a project

​Step 4: Scaffold an environment

​Step 5: Publish your environment

​Step 6: Configure and validate your run

​Step 7: Train

​Step 8: Deploy

​Step 9: Chat

​Essential commands

​Next steps

How Flash works

Training in depth

Build an environment

Deploy & chat

Prerequisites

Step 1: Install the CLI

Step 2: Log in

Step 3: Create a project

Step 4: Scaffold an environment

Step 5: Publish your environment

Step 6: Configure and validate your run

Step 7: Train

Step 8: Deploy

Step 9: Chat

Essential commands

Next steps