> ## 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.
# Quickstart
> Install the CLI, log in, and train, deploy, and chat with your first model.
Go from an empty directory to a deployed model. Train a
[LoRA adapter](/how-flash-works) 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](https://freesolo.co). Commands that contact Freesolo, including
server-side `--dry-run`, authenticate with it. Local `--cost` does not submit.
## Step 1: Install the CLI
```bash uv theme={null}
uv tool install freesolo-flash
```
```bash pipx theme={null}
pipx install freesolo-flash
```
```bash pip theme={null}
pip install freesolo-flash
```
## Step 2: Log in
```bash theme={null}
flash login --api-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`.
```bash theme={null}
flash whoami # confirm who your stored key resolves to
```
## Step 3: Scaffold a project
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 5.
```bash theme={null}
flash env setup
```
This writes a ready-to-edit starter into the current directory:
```
environment.py # a Freesolo environment (task + reward)
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.
Skip the hand-editing. Point your coding agent (Claude Code, Cursor, etc.) at
the [environment guide](/guides/environments/overview) and have it find and port your
existing reward and dataset into `environment.py`. A prompt to start from:
```text theme={null}
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 4: Publish your environment
An [environment](/guides/environments/overview) is the task and reward your model trains
on. [Publish](/guides/environments/package#publish-it) the scaffolded one to the managed
Environments Hub to get an id:
```bash theme={null}
flash env push --name starter .
```
This prints an environment id of the form `your-org/starter`.
## Step 5: Configure and validate your run
Open `configs/sft.toml` and set the one thing that's yours, the environment id
from the previous step:
```toml configs/sft.toml theme={null}
model = "Qwen/Qwen3.5-4B"
algorithm = "sft"
[environment]
id = "your-org/starter"
[train]
epochs = 1
max_examples = 2
lora_rank = 32
```
Run an authenticated server-side validation first. `--dry-run` runs server-side
submit-time preflights, creates a run with `state=dry_run`, reports client/server
`[train]` schema mismatches, allocates no GPU, and incurs no charge:
```bash theme={null}
flash train configs/sft.toml --dry-run
```
See what [the run will cost](/guides/training#cost-and-billing) before
committing. `--cost` remains local: it prints the pre-flight USD cost and exits
without submitting:
```bash theme={null}
flash train configs/sft.toml --cost
```
## Step 6: Train
```bash theme={null}
flash train configs/sft.toml
```
This is the first step that can spend money. 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](/guides/training#monitor-a-run):
```bash theme={null}
flash runs # list your runs and their state/cost
flash status # status JSON, including the cost record
flash log -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 7: Deploy
Serve the trained adapter on Freesolo's
[managed serving service](/guides/deploy-and-chat). Serving is
[billed per token](/guides/deploy-and-chat#billing) for requests you send:
```bash theme={null}
flash deploy
```
Every real deploy resolves an immutable adapter revision and runs a bounded
serving smoke before the stable run-id alias is activated.
## Step 8: Chat
```bash theme={null}
flash chat -m "Hello! What can you do?"
```
That completes the loop. When you're done,
[tear the endpoint down](/guides/deploy-and-chat#manage-deployments):
```bash theme={null}
flash undeploy
```
## Essential commands
The commands you used above, plus the ones you'll reach for next. Run
`flash --help` for the full set of flags, or see the
[CLI reference](/reference/cli).
| Command | What it does | Example |
| ----------------------- | -------------------------------------------- | ---------------------------------------- |
| `flash login` | Store your Freesolo API key locally | `flash login --api-key ` |
| `flash env setup` | Scaffold a starter environment and configs | `flash env setup` |
| `flash env push` | Publish an environment and print its id | `flash env push --name starter .` |
| `flash train` | Submit a run and follow its logs | `flash train configs/sft.toml` |
| `flash train --dry-run` | Run server preflights, no GPU or charge | `flash train configs/sft.toml --dry-run` |
| `flash train --cost` | Preview the local pre-flight cost, no submit | `flash train configs/sft.toml --cost` |
| `flash runs` | List your runs with state, cost, and model | `flash runs` |
| `flash status` | Show run status and cost | `flash status ` |
| `flash log` | Print or follow worker logs | `flash log -f` |
| `flash deploy` | Serve a trained adapter | `flash deploy ` |
| `flash chat` | Send a message to a deployment | `flash chat -m "hi"` |
| `flash undeploy` | Tear a deployment down | `flash undeploy ` |
## Next steps
The loop behind a run, and the concepts each command refers to.
SFT, GRPO, and OPD, config options, monitoring, and cost.
Replace the starter task with your own data and reward.
Serving billing and the OpenAI-compatible API.