Package & publish

Structure the package

A published environment is a small folder. Flash packages it, imports its environment.py entrypoint at run time, and calls load_environment(**params), which must return a Freesolo SDK environment. The folder can be named anything as long as it contains environment.py at its root.

math/
  environment.py          # defines load_environment()
  helpers.py              # optional Python helpers
  dataset/
    train.jsonl           # input/output records
    eval.jsonl

The directory is dataset/, singular. Flash probes dataset/<split>.jsonl and dataset/<split>.json and never reads a top-level datasets/. A package that uses the plural name fails at load time naming the layout, rather than training on a silently empty dataset. Rename the directory, or point [environment.params] dataset_path at the exact file.

A single .py upload still works for tiny smoke tests, but push real environments as folders. Import from sibling files in the folder you publish, from the freesolo SDK, from the Python standard library, or from any third-party package you declare under [environment] pip (see Dependencies are managed).

Dependencies are managed

The GPU worker installs one managed requirement set - the freesolo SDK and the training stack - for every environment. Anything your scorer needs on top of that is declared with [environment] pip, which is appended to the managed set rather than replacing it; see Scorer dependencies. Without that key, your environment.py and its sibling modules can import only from:

the freesolo SDK,
the Python standard library,
other files in the folder you publish.

A pyproject.toml, requirements.txt, or lockfile beside environment.py can describe your local development setup, but Flash does not read those files to install packages for a managed run. If your reward logic needs an external service - a judge model, a database - declare its client under [environment] pip, or call the service over HTTP with the standard library if you would rather not add a dependency. Either way, declare the credential it reads under [environment] secrets (see Use API keys):

environment.py

import json
import os
import urllib.request

JUDGE_API_KEY = os.environ["JUDGE_API_KEY"]


def judge(prompt: str) -> float:
    body = json.dumps({"model": "some-judge", "messages": [{"role": "user", "content": prompt}]})
    request = urllib.request.Request(
        "https://openrouter.ai/api/v1/chat/completions",
        data=body.encode(),
        headers={
            "Authorization": f"Bearer {JUDGE_API_KEY}",
            "Content-Type": "application/json",
        },
    )
    with urllib.request.urlopen(request, timeout=30) as response:
        payload = json.load(response)
    return float(payload["choices"][0]["message"]["content"].strip())

Give every outbound call an explicit timeout. A reward that blocks holds up the whole training step, and slow grading shows up as wall-clock cost. Do not declare unused secrets. If the active reward only calls the judge model and no longer queries a database, leave the database credential out.

Publish it

Training runs on managed infrastructure, so the environment must be reachable by id. Push the folder to the managed Environments Hub. Every environment belongs to a project, the same grouping the dashboard organizes runs and traces by, and you name it on every push. Get a project UUID from flash projects list, or create one:

PROJECT=$(flash projects create my-project)
flash env push --project "$PROJECT" --name math math

The --name value is normalized to a lowercase hyphen slug, and the command prints the published id (your-org/your-project/math) to put in [environment] id. A malformed UUID is rejected before anything uploads, and a project outside your organization fails the push. See flash env push.

Environment names are unique per project, not per organization. The owning project is part of the id, so two projects in your organization can each publish their own math and they stay separate environments. Renaming a project does not change any id it already published.

Use an existing environment

If you already have a published env id (yours or one shared with you), reference it directly. On Freesolo’s managed service, [environment] id accepts only a managed namespace/project/name slug; github: refs and GitHub URLs are rejected. Publish yours with flash env push, use the returned id, and note that flash env pull also accepts managed slugs only. Standalone planes use reachable GitHub sources instead; see Self-hosted environments.

[environment]
id = "your-org/your-project/your-env"

To edit or inspect the source locally, pull the whole environment into a directory:

flash env pull your-org/your-project/your-env

Pull one file by adding its path inside the environment. Use -o to choose the destination and -f to overwrite an existing output:

flash env pull your-org/your-project/your-env dataset/train.jsonl -o train.jsonl

List what you have

flash env list

Shows local environment sources you can publish, such as ./environment.py or folders under environments/, and your organization’s already-published environments with the ids you paste into [environment] id.

Delete a Hub environment

Delete only targets managed Hub ids of the form namespace/project/name; GitHub refs and local paths are not Hub records and cannot be deleted this way.

flash env delete your-org/your-project/your-env --project <project-uuid>
flash env delete your-org/your-project/your-env --project <project-uuid> -y   # skip the confirmation prompt

--project is required and must be the UUID of the project the environment was published to. flash projects list shows the projects you can reach, and the environment’s dashboard page shows the one it belongs to.

Use API keys

If your environment needs an external service, read the key from os.environ in environment.py:

environment.py

import os

SERVICE_API_KEY = os.environ["SERVICE_API_KEY"]

Then declare the environment variable names in your training config:

[environment]
id = "your-org/your-project/your-env"
secrets = ["SERVICE_API_KEY"]

Set the value in your shell before submitting:

export SERVICE_API_KEY="..."
flash train configs/sft.toml

You can also put local development values in .env or .env.local:

SERVICE_API_KEY=...

Declared secret values are sent separately from everything else, and are never stored in the TOML config, status JSON, logs, or the published environment. Do not put API keys in [environment.params]. If a declared secret is missing when you submit, flash train fails before the run starts.

Get started

Flash

Reference

Structure the package

Dependencies are managed

Publish it

Use an existing environment

List what you have

Delete a Hub environment

Use API keys

Next steps

Single-turn environments

Training

​Structure the package

​Dependencies are managed

​Publish it

​Use an existing environment

​List what you have

​Delete a Hub environment

​Use API keys

​Next steps

Single-turn environments

Training

Structure the package

Dependencies are managed

Publish it

Use an existing environment

List what you have

Delete a Hub environment

Use API keys

Next steps