freesolo-flash-dev 1.0.72__tar.gz → 1.0.73__tar.gz

freesolo_flash_dev-1.0.73/.env.example

@@ -0,0 +1,97 @@
+# Flash control plane (operator-side). Copy to .env and fill in.
+# Provider credentials live ONLY here — clients never see them and authenticate
+# with their API key.
+#
+# Everything under "required" is checked by `flash/providers/preflight.py` at
+# startup; `flash-server` refuses to serve if any of them is missing. Settings
+# that only DEGRADE the plane (a single-account RunPod pool, no GITHUB_TOKEN)
+# warn at startup instead of blocking it.
+#
+# Self-hosting? Read SELF_HOSTING.md first - the short version is the two lines
+# below, and it is a much smaller list than this file suggests:
+#
+#   FLASH_STANDALONE=1
+#   FREESOLO_INTERNAL_KEY=$(openssl rand -hex 32)
+#
+# IMPORTANT: `flash-server` does NOT read this file. It reads the process
+# environment, so copying it to .env is not by itself enough — load it:
+#
+#   set -a && . ./.env && set +a && flash-server     # shell
+#   docker run --env-file .env ...                   # docker
+
+# --- required: GPU substrate (AT LEAST ONE of the three) ---
+# Flash allocates across RunPod, Lambda, and Vast. Configure the ones you have an
+# account with; a provider whose key is unset is simply never considered, and the
+# allocator ranks candidates only on the substrates you configured. One is enough
+# to run. The preflight fails only when ALL THREE are missing.
+#
+# RunPod: one key, or several comma-separated for multi-account failover. A
+# single-account pool works but cannot fail over or reap across accounts, so the
+# preflight warns.
+RUNPOD_API_KEY=
+# Lambda Cloud API key.
+LAMBDA_API_KEY=
+# Vast.ai API key.
+VAST_API_KEY=
+
+# --- required: artifacts ---
+# HuggingFace token with write access to the dataset repos flash creates for artifacts
+# (code upload + streamed checkpoints/adapters). The repo is assigned by the control
+# plane and scoped to the ENVIRONMENT, so runs sharing an environment share a repo and
+# each run lands under its own prefix. It is not a user-authored field: the TOML parser
+# rejects a [train] hf_repo set by hand.
+HF_TOKEN=
+# The HuggingFace user or org those artifact repos are created under. Defaults to
+# Freesolo's namespace, which a self-hoster's token cannot write to - so on a
+# self-hosted plane SET THIS to a namespace your HF_TOKEN owns, or every run fails at
+# the code upload before training starts.
+# FLASH_HF_NAMESPACE=your-hf-username
+
+# --- required: control-plane auth ---
+# The plane's own auth key. On a self-hosted (FLASH_STANDALONE=1) deployment this is
+# the ONLY credential the plane accepts and is therefore the entire trust boundary -
+# generate a high-entropy value and treat it like a root password:
+#
+#   export FREESOLO_INTERNAL_KEY=$(openssl rand -hex 32)
+#
+# On a managed deployment it is the shared internal key that maps to a single service
+# identity without a network call, alongside per-user keys verified against
+# {FREESOLO_BASE_URL}/api/auth/verify.
+FREESOLO_INTERNAL_KEY=
+
+# --- optional: self-hosting ---
+# Run without a Freesolo backend. Off by default. With it set, the plane stops calling
+# out for project/environment/billing validation and trusts FREESOLO_INTERNAL_KEY as a
+# single-tenant operator credential; external bearer tokens are REJECTED rather than
+# accepted unverified. Single tenant - see SELF_HOSTING.md before enabling.
+# FLASH_STANDALONE=1
+
+# --- optional ---
+# Server token for the environment repository. Without it, environments hosted in a
+# private GitHub repo cannot be fetched; environments in public GitHub repos still work,
+# so this warns at startup rather than blocking it. (A local directory is never a valid
+# environment source - the GPU worker fetches the environment itself.)
+GITHUB_TOKEN=
+# The OPD teacher credential (injected into the worker for opd jobs only). NOT covered
+# by the startup preflight: an opd run submitted without it still allocates and BILLS a
+# GPU, then fails inside the worker before the first teacher request. Set it before
+# running opd; sft and grpo do not use it.
+FIREWORKS_API_KEY=
+# Where to verify user keys. Defaults to https://api.freesolo.co when unset. Ignored
+# under FLASH_STANDALONE=1, which verifies nothing over the network.
+# FREESOLO_BASE_URL=
+# Adapter serving is delegated to a multi-LoRA serving app (a Modal app that serves
+# every adapter on one GPU per base model, scaling to zero when idle).
+# `flash deploy`/`undeploy`/`chat` register/deregister/chat against it. Defaults to the
+# hosted URL when unset; point it at your own deployment to self-host serving.
+#
+# Under FLASH_STANDALONE=1 there is NO default: those three commands error out until this
+# is set. Every serving request carries FREESOLO_INTERNAL_KEY, which on a self-hosted
+# plane is the credential controlling that plane, so falling back to the hosted URL would
+# send it to a service the operator does not run. Training never uses this.
+#
+# LEFT COMMENTED DELIBERATELY. The standalone guard rejects an UNSET value, so a template
+# that assigned the hosted URL would satisfy it and hand the plane's root credential to
+# serve.freesolo.co on the first deploy -- the exact leak the guard exists to stop. Set it
+# to YOUR serving deployment; the managed plane gets the hosted URL from the code default.
+# FREESOLO_SERVING_URL=https://serve.freesolo.co

{freesolo_flash_dev-1.0.72 → freesolo_flash_dev-1.0.73}/CONTRIBUTING.md

@@ -81,6 +81,13 @@ this repository have one, and it is the main reason the history is readable.
 Do not add tool-generated trailers (co-author lines for AI assistants, session links, or
 "generated with" footers) to commits.
 
+That rule governs new commits only. Commits already in this history carry such trailers,
+plus a build box that committed under an internal hostname. `scripts/scrub_history.sh`
+rewrites both out of every ref and refuses to print publication instructions unless the
+residual counts reach zero. It has to run on a fresh mirror clone **before** the
+repository is made public: rewriting afterwards accomplishes nothing, because the old
+shas stay reachable through forks, caches, and the GitHub API.
+
 ## Code style
 
 - Ruff is the formatter and linter; its configuration lives in `pyproject.toml`. Run

{freesolo_flash_dev-1.0.72 → freesolo_flash_dev-1.0.73}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: freesolo-flash-dev
-Version: 1.0.72
+Version: 1.0.73
 Summary: Flash — managed LoRA post-training (SFT/GRPO/OPD) for Freesolo environments, driven by the `flash` CLI
 Project-URL: Homepage, https://github.com/freesolo-co/flash
 Project-URL: Repository, https://github.com/freesolo-co/flash
@@ -87,19 +87,21 @@ This repository contains:
 - the GPU provider substrate (`flash/providers/`) — pricing, allocation, submit/poll,
 - the environment loading machinery (`flash/envs/`).
 
-It does **not** contain everything needed to stand up an equivalent service from scratch.
-The following are Freesolo-operated and not part of this repository:
+The training path is self-hostable end to end: with `FLASH_STANDALONE=1`, one GPU provider
+key, and a HuggingFace token, you can run SFT, GRPO, and on-policy distillation on your own
+hardware budget with no Freesolo backend involved. See
+**[SELF_HOSTING.md](SELF_HOSTING.md)**.
 
-| Component               | Where it lives                                        |
-| ----------------------- | ----------------------------------------------------- |
-| Identity and API keys   | `api.freesolo.co` — verifies keys, owns projects/orgs |
-| Multi-LoRA serving      | `serve.freesolo.co` — `flash/serve/` is a thin client |
-| Managed environment hub | a private repository of published environments        |
+Two components stay Freesolo-operated and are not in this repository:
 
-If you are evaluating Flash, the honest summary is: **use it against the hosted service**,
-or **read and modify the training/provider code**, which is self-contained and the most
-reusable part of the repository. Running your own end-to-end copy of the service is
-possible but requires replacing the components above — see [Self-hosting](#self-hosting).
+| Component             | Where it lives                                        | Self-hosted equivalent                                                          |
+| --------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------- |
+| Multi-tenant identity | `api.freesolo.co` - verifies keys, owns projects/orgs | `FLASH_STANDALONE=1` runs single-tenant on your own operator key                |
+| Multi-LoRA serving    | `serve.freesolo.co` - `flash/serve/` is a thin client | adapters land in your HuggingFace repos; serve them with any LoRA-capable stack |
+
+So there are three honest ways to use Flash: **against the hosted service**, **self-hosted
+against your own GPU accounts**, or as **training and provider code to read and modify**,
+which is self-contained and the most reusable part of the repository.
 
 ## Using the hosted service
 
@@ -242,44 +244,41 @@ model — in short, **pull requests go into `dev`**.
 
 ## Self-hosting
 
-You can run your own control plane, but read this first — it is an operator deployment,
-not a one-command install.
-
-The control plane needs the `server` extra — the base install above is client-only and
-`flash-server` will refuse to start without it:
+You can run your own control plane against your own GPU accounts, with no Freesolo backend
+involved. **[SELF_HOSTING.md](SELF_HOSTING.md) is the full guide**; the short version:
 
 ```bash
-pip install 'freesolo-flash[server]'
+pip install 'freesolo-flash[server]'   # the base install is client-only
+
+export FLASH_STANDALONE=1
+export FREESOLO_INTERNAL_KEY=$(openssl rand -hex 32)
+export HF_TOKEN=hf_...
+export FLASH_HF_NAMESPACE=your-hf-username   # a namespace your HF_TOKEN can write to
+export RUNPOD_API_KEY=...              # or LAMBDA_API_KEY, or VAST_API_KEY
+
+flash-server --host 0.0.0.0 --port 8080
 ```
 
-`flash-server` then fails fast at startup unless all of the following are present (see
-`flash/providers/preflight.py` and `.env.example`). Note it reads the PROCESS
-environment, so load your `.env` (`set -a && . ./.env && set +a`) rather than relying on
-the file being present:
-
-- `RUNPOD_API_KEY` — **two or more distinct** RunPod account keys, comma-separated. A
-  single-account pool cannot reap or fail over across accounts, so the preflight rejects
-  it.
-- `LAMBDA_API_KEY` — Lambda Cloud API key.
-- `HF_TOKEN` — write access to the dataset repos flash creates for artifacts. The repo is
-  assigned by the control plane and scoped to the environment, so runs sharing an
-  environment share a repo, each under its own prefix.
-- `FREESOLO_INTERNAL_KEY` — control-plane authentication. Requests presenting this key
-  authenticate as a single service identity with no network call, which is the path to use
-  if you are not integrating with Freesolo identity.
-- `GITHUB_TOKEN` — access to the managed environment repository.
-
-Beyond credentials, three seams point at Freesolo services and would need replacing for a
-fully independent deployment:
-
-1. **User authentication.** Unknown bearer tokens are verified against
-   `{FREESOLO_BASE_URL}/api/auth/verify` (`flash/server/auth.py`). Only the internal-key
-   path works without the Freesolo backend.
-2. **Environments.** Publishing and managed-slug loading target a private environment
-   repository (`flash/server/envs.py`, `flash/envs/loader.py`).
-3. **Serving.** `flash/serve/` is a client for the Freesolo multi-LoRA serving app; point
-   it elsewhere with `FREESOLO_SERVING_URL`, but this repository does not include a
-   serving backend.
+You need **one** of RunPod, Lambda, or Vast - not all three. Providers whose key is unset
+are never considered, and the allocator only proposes GPU classes it can actually
+provision. Startup fails only when all three are missing.
+
+`FLASH_STANDALONE=1` is what makes this work: it stops the plane calling out for project,
+environment, and billing validation, and trusts `FREESOLO_INTERNAL_KEY` as a single-tenant
+operator credential. External bearer tokens are rejected rather than accepted unverified.
+A standalone plane is **single-tenant** - whoever holds that key can spend your GPU budget,
+so keep it off untrusted networks. See
+[the security model](SELF_HOSTING.md#the-security-model).
+
+Two seams remain Freesolo-operated and are not part of this repository:
+
+1. **Multi-tenant identity.** Real per-user keys and org ownership need a backend serving
+   the `/api/auth/verify` contract in `flash/server/auth.py`, pointed at by
+   `FREESOLO_BASE_URL`. Standalone mode is single-tenant instead.
+2. **Serving.** `flash/serve/` is a client for a multi-LoRA serving app; point it elsewhere
+   with `FREESOLO_SERVING_URL`. Training, checkpoint streaming, and adapter export are
+   fully self-hostable - adapters land in your own HuggingFace repos and can be served by
+   any stack that loads LoRA adapters.
 
 The GPU worker image is public and can be pulled directly. It is published under an
 explicit CUDA tag, not `latest`:

{freesolo_flash_dev-1.0.72 → freesolo_flash_dev-1.0.73}/README.md

@@ -28,19 +28,21 @@ This repository contains:
 - the GPU provider substrate (`flash/providers/`) — pricing, allocation, submit/poll,
 - the environment loading machinery (`flash/envs/`).
 
-It does **not** contain everything needed to stand up an equivalent service from scratch.
-The following are Freesolo-operated and not part of this repository:
+The training path is self-hostable end to end: with `FLASH_STANDALONE=1`, one GPU provider
+key, and a HuggingFace token, you can run SFT, GRPO, and on-policy distillation on your own
+hardware budget with no Freesolo backend involved. See
+**[SELF_HOSTING.md](SELF_HOSTING.md)**.
 
-| Component               | Where it lives                                        |
-| ----------------------- | ----------------------------------------------------- |
-| Identity and API keys   | `api.freesolo.co` — verifies keys, owns projects/orgs |
-| Multi-LoRA serving      | `serve.freesolo.co` — `flash/serve/` is a thin client |
-| Managed environment hub | a private repository of published environments        |
+Two components stay Freesolo-operated and are not in this repository:
 
-If you are evaluating Flash, the honest summary is: **use it against the hosted service**,
-or **read and modify the training/provider code**, which is self-contained and the most
-reusable part of the repository. Running your own end-to-end copy of the service is
-possible but requires replacing the components above — see [Self-hosting](#self-hosting).
+| Component             | Where it lives                                        | Self-hosted equivalent                                                          |
+| --------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------- |
+| Multi-tenant identity | `api.freesolo.co` - verifies keys, owns projects/orgs | `FLASH_STANDALONE=1` runs single-tenant on your own operator key                |
+| Multi-LoRA serving    | `serve.freesolo.co` - `flash/serve/` is a thin client | adapters land in your HuggingFace repos; serve them with any LoRA-capable stack |
+
+So there are three honest ways to use Flash: **against the hosted service**, **self-hosted
+against your own GPU accounts**, or as **training and provider code to read and modify**,
+which is self-contained and the most reusable part of the repository.
 
 ## Using the hosted service
 
@@ -183,44 +185,41 @@ model — in short, **pull requests go into `dev`**.
 
 ## Self-hosting
 
-You can run your own control plane, but read this first — it is an operator deployment,
-not a one-command install.
-
-The control plane needs the `server` extra — the base install above is client-only and
-`flash-server` will refuse to start without it:
+You can run your own control plane against your own GPU accounts, with no Freesolo backend
+involved. **[SELF_HOSTING.md](SELF_HOSTING.md) is the full guide**; the short version:
 
 ```bash
-pip install 'freesolo-flash[server]'
+pip install 'freesolo-flash[server]'   # the base install is client-only
+
+export FLASH_STANDALONE=1
+export FREESOLO_INTERNAL_KEY=$(openssl rand -hex 32)
+export HF_TOKEN=hf_...
+export FLASH_HF_NAMESPACE=your-hf-username   # a namespace your HF_TOKEN can write to
+export RUNPOD_API_KEY=...              # or LAMBDA_API_KEY, or VAST_API_KEY
+
+flash-server --host 0.0.0.0 --port 8080
 ```
 
-`flash-server` then fails fast at startup unless all of the following are present (see
-`flash/providers/preflight.py` and `.env.example`). Note it reads the PROCESS
-environment, so load your `.env` (`set -a && . ./.env && set +a`) rather than relying on
-the file being present:
-
-- `RUNPOD_API_KEY` — **two or more distinct** RunPod account keys, comma-separated. A
-  single-account pool cannot reap or fail over across accounts, so the preflight rejects
-  it.
-- `LAMBDA_API_KEY` — Lambda Cloud API key.
-- `HF_TOKEN` — write access to the dataset repos flash creates for artifacts. The repo is
-  assigned by the control plane and scoped to the environment, so runs sharing an
-  environment share a repo, each under its own prefix.
-- `FREESOLO_INTERNAL_KEY` — control-plane authentication. Requests presenting this key
-  authenticate as a single service identity with no network call, which is the path to use
-  if you are not integrating with Freesolo identity.
-- `GITHUB_TOKEN` — access to the managed environment repository.
-
-Beyond credentials, three seams point at Freesolo services and would need replacing for a
-fully independent deployment:
-
-1. **User authentication.** Unknown bearer tokens are verified against
-   `{FREESOLO_BASE_URL}/api/auth/verify` (`flash/server/auth.py`). Only the internal-key
-   path works without the Freesolo backend.
-2. **Environments.** Publishing and managed-slug loading target a private environment
-   repository (`flash/server/envs.py`, `flash/envs/loader.py`).
-3. **Serving.** `flash/serve/` is a client for the Freesolo multi-LoRA serving app; point
-   it elsewhere with `FREESOLO_SERVING_URL`, but this repository does not include a
-   serving backend.
+You need **one** of RunPod, Lambda, or Vast - not all three. Providers whose key is unset
+are never considered, and the allocator only proposes GPU classes it can actually
+provision. Startup fails only when all three are missing.
+
+`FLASH_STANDALONE=1` is what makes this work: it stops the plane calling out for project,
+environment, and billing validation, and trusts `FREESOLO_INTERNAL_KEY` as a single-tenant
+operator credential. External bearer tokens are rejected rather than accepted unverified.
+A standalone plane is **single-tenant** - whoever holds that key can spend your GPU budget,
+so keep it off untrusted networks. See
+[the security model](SELF_HOSTING.md#the-security-model).
+
+Two seams remain Freesolo-operated and are not part of this repository:
+
+1. **Multi-tenant identity.** Real per-user keys and org ownership need a backend serving
+   the `/api/auth/verify` contract in `flash/server/auth.py`, pointed at by
+   `FREESOLO_BASE_URL`. Standalone mode is single-tenant instead.
+2. **Serving.** `flash/serve/` is a client for a multi-LoRA serving app; point it elsewhere
+   with `FREESOLO_SERVING_URL`. Training, checkpoint streaming, and adapter export are
+   fully self-hostable - adapters land in your own HuggingFace repos and can be served by
+   any stack that loads LoRA adapters.
 
 The GPU worker image is public and can be pulled directly. It is published under an
 explicit CUDA tag, not `latest`:

freesolo_flash_dev-1.0.73/SELF_HOSTING.md

@@ -0,0 +1,245 @@
+# Self-hosting Flash
+
+Run your own Flash control plane against your own GPU accounts, with no Freesolo backend
+involved.
+
+This is an operator deployment, not a one-command install: you supply the GPU credentials,
+you hold the auth key, and you decide which of the three providers to use. What it gets
+you is the whole training path - SFT, GRPO, and on-policy distillation on verl with
+colocated vLLM rollouts, the allocator, the stall watchdog, checkpoint streaming, and
+endpoint GC - pointed at hardware you pay for directly.
+
+## What you need
+
+Two credentials and at least one GPU account:
+
+|                         |                                                                                                                                                                               |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **One GPU provider**    | a RunPod, Lambda, **or** Vast account. One is enough.                                                                                                                         |
+| `HF_TOKEN`              | a HuggingFace token with **write** access. Flash streams code, checkpoints, and adapters through HuggingFace dataset repos, so every run needs it whichever provider you use. |
+| `FLASH_HF_NAMESPACE`    | the HuggingFace user or org those repos are created under - **set this to one your `HF_TOKEN` can write to.** It defaults to Freesolo's namespace, which you cannot write to. |
+| `FREESOLO_INTERNAL_KEY` | the key your clients present to your plane. Generate it yourself.                                                                                                             |
+
+Everything else is optional.
+
+## Quickstart
+
+```bash
+pip install 'freesolo-flash[server]'   # the base install is client-only
+
+export FLASH_STANDALONE=1
+export FREESOLO_INTERNAL_KEY=$(openssl rand -hex 32)
+export HF_TOKEN=hf_...
+export FLASH_HF_NAMESPACE=your-hf-username   # where run artifacts are created
+export RUNPOD_API_KEY=...              # or LAMBDA_API_KEY, or VAST_API_KEY
+
+flash-server --host 0.0.0.0 --port 8080
+```
+
+Then point a client at it:
+
+```bash
+flash login --api-url http://your-plane:8080 --api-key "$FREESOLO_INTERNAL_KEY"
+flash train run.toml
+```
+
+Every run config needs a top-level `project` uuid - it groups runs and is required in
+standalone mode too (see [project ids](#what-flashstandalone1-does)). Any uuid works
+on a standalone plane, so you can pick one once and reuse it:
+
+```toml
+project = "11111111-1111-4111-8111-111111111111"
+model = "Qwen/Qwen3.5-4B"
+algorithm = "sft"
+
+[environment]
+id = "github:your-org/your-repo@main:path/to/env"
+
+[train]
+epochs = 1
+max_examples = 1000
+```
+
+`flash-server` reads the **process** environment, not `.env`. If you keep credentials in a
+file, load it: `set -a && . ./.env && set +a && flash-server`, or
+`docker run --env-file .env ...`. Copy `.env.example` to start from a documented template.
+
+## Environments
+
+An environment is the Python package defining your task - dataset, rollout, reward. Point
+`[environment] id` at any GitHub repository you control:
+
+| Form                                          | Resolves to                                                  |
+| --------------------------------------------- | ------------------------------------------------------------ |
+| `github:owner/repo@ref:path/to/env`           | that repo at that ref. **Use this when self-hosting.**       |
+| `https://github.com/owner/repo/tree/ref/path` | the same thing, in browser-URL form.                         |
+| `namespace/name`                              | Freesolo's managed hub (`freesolo-co/environment-hub`) only. |
+
+A bare `namespace/name` slug is **not** a generic shorthand - it always resolves against
+Freesolo's hub, so a self-hosted plane should use the explicit `github:` form. `ref` may be
+a branch, tag, or commit sha; pin a sha if you want runs to be reproducible.
+
+Public repos work without credentials, subject to GitHub's unauthenticated rate limit. Set
+`GITHUB_TOKEN` for private repos. `flash env push` publishes to the managed hub and is not
+part of a self-hosted deployment.
+
+**A local directory is not a supported environment source.** The GPU worker fetches the
+environment itself, so it needs a source it can reach; an `[environment] path` is rejected
+at submit. Push your environment to a GitHub repository (public or private with
+`GITHUB_TOKEN`) and reference it with the `github:` form above.
+
+## Choosing providers
+
+Flash allocates across RunPod, Lambda, and Vast. **Configure the ones you have; the rest
+are simply never considered.** There is no requirement to hold all three, and no
+placeholder value to set for the ones you skip.
+
+| Provider | Variable         | Notes                                                           |
+| -------- | ---------------- | --------------------------------------------------------------- |
+| RunPod   | `RUNPOD_API_KEY` | One key, or several comma-separated for multi-account failover. |
+| Lambda   | `LAMBDA_API_KEY` |                                                                 |
+| Vast     | `VAST_API_KEY`   |                                                                 |
+
+The allocator ranks candidate GPU classes only on the substrates you configured, so a
+plane with just `VAST_API_KEY` set allocates on Vast and never proposes a class it cannot
+provision. Startup fails only when **all three** are missing.
+
+A single RunPod key works. It logs a warning at startup because a one-account pool cannot
+ride out that account's quota or credit exhaustion by moving to another - an availability
+property, not a correctness one. Runs still allocate, and idle endpoints are still reaped
+within the account you configured.
+
+## What `FLASH_STANDALONE=1` does
+
+Flash's managed deployment keeps organizations, projects, and billing in a Freesolo SaaS
+backend, and the plane validates against it on every run. A self-hoster has no such
+backend - without this flag the plane resolves `api.freesolo.co`, the validation call
+fails, and **every run is rejected 503**. The flag is what makes self-hosting a supported
+configuration rather than an unreachable one.
+
+With it set:
+
+- **`FREESOLO_INTERNAL_KEY` is the only credential the plane accepts.** External bearer
+  tokens are rejected, not accepted unverified - there is no backend to verify them
+  against, and treating "cannot verify" as "accept" would turn a self-hosted plane into an
+  open one.
+- **Project ids are taken as given.** They are still required and still validated for
+  shape, so runs stay grouped; what is skipped is the ownership check against an org
+  directory that does not exist here.
+- **Environment mirror validation is skipped.** The environment package itself is still
+  resolved and authorized normally.
+- **Backend reporting is off** - billing precheck and charge, realized-cost
+  reconciliation, checkpoint registration, the shared RunPod slot store, and the hosted
+  artifact GC sweep. Otherwise these would send your operator key to `api.freesolo.co`
+  (and, for the GC, `serve.freesolo.co`) and log a warning per run or per startup.
+
+> **RunPod endpoint concurrency is not capped by Flash**, on a self-hosted plane or a
+> managed one. The slot store and the in-process semaphore behind it are both claimed from
+> a code path the live deploy no longer uses, so neither enforces the intended 58-endpoint
+> ceiling; `flash/providers/runpod/train/endpoints.py` documents this at the constant. If
+> you expect many concurrent runs, cap them upstream of Flash or raise the worker quota on
+> your RunPod account - otherwise a large enough burst hits RunPod's account limit and the
+> excess deploys fail there.
+
+### The security model
+
+**A standalone plane is single-tenant.** It cannot distinguish organizations, so anyone
+holding `FREESOLO_INTERNAL_KEY` can submit runs, read any run's status and logs, and spend
+your GPU budget. Treat that key like a root password: generate it with
+`openssl rand -hex 32` (or equivalent), never commit it, and rotate it if it leaks.
+
+Rotating is safe: a standalone plane records run ownership against a fixed single-tenant
+owner, not against the key's value, so runs started under the old key stay listed,
+inspectable, and cancellable under the new one. The old key stops working immediately.
+
+The same applies when you turn `FLASH_STANDALONE` on for a state directory that already
+has runs in it: the single-tenant owner adopts them, so they stay listed and cancellable
+rather than becoming invisible. This is safe only because standalone is single-tenant -
+there is one principal, so every run in that store is already yours. Do not point a
+standalone plane at the state directory of a **multi-tenant** deployment: it has no way to
+tell whose runs those were, and it will treat all of them as the operator's.
+
+Do not expose a standalone plane to untrusted callers. Put it on a private network, behind
+a VPN, or behind an authenticating reverse proxy. If you need real multi-tenancy - separate
+organizations, per-user keys, project ownership enforcement - you need an identity backend
+serving the `/api/auth/verify` contract in `flash/server/auth.py`, and you should run
+without `FLASH_STANDALONE` and set `FREESOLO_BASE_URL` to point at it.
+
+## Optional pieces
+
+| Variable               | Effect if unset                                                                                                                                                                                   |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `GITHUB_TOKEN`         | Environments in **private** GitHub repos cannot be fetched and `flash env push` is unavailable. Environments in **public** GitHub repos still work. Warns at startup.                             |
+| `FIREWORKS_API_KEY`    | On-policy distillation (`opd`) runs fail inside the worker, after allocating and billing a GPU. Not covered by the startup preflight - set it before running opd. `sft` and `grpo` do not use it. |
+| `FREESOLO_SERVING_URL` | In standalone mode `flash deploy`/`undeploy`/`chat` **refuse to run** rather than send your plane's key to Freesolo's serving app. Training is unaffected. See below.                             |
+
+## Serving
+
+`flash/serve/` is a **client** for a multi-LoRA serving app (a Modal app that serves every
+adapter on one GPU per base model, scaling to zero when idle). This repository does not
+include that serving backend.
+
+Training, checkpoint streaming, and adapter export are fully self-hostable and do not
+depend on it. Your trained adapters land in your own HuggingFace repos and can be served
+by any stack that loads LoRA adapters - vLLM, TGI, or your own. Point `FREESOLO_SERVING_URL`
+at a compatible deployment if you want `flash deploy` and `flash chat` to work end to end.
+
+On a standalone plane those three commands **error out** until you set it, rather than
+falling back to the hosted default. Every serving request carries `FREESOLO_INTERNAL_KEY`,
+and on your plane that key is what grants full control of it - so the fallback would hand
+your plane's credential to a service you do not operate. Export the adapter and serve it
+yourself if you do not run a compatible backend.
+
+The catalog reports a `serving.serve_model_id` per model - the pre-quantized FP8 checkpoint
+Freesolo's serving app loads, and most of those repos are private. They are **informational
+only**: nothing in the training path reads them, so they cannot block a run. If you stand up
+your own serving backend, quantize the base model yourself (or serve it unquantized) rather
+than expecting to pull those repo names.
+
+## The worker image
+
+The GPU worker image is public and pulls directly. It is published under an explicit CUDA
+tag, not `latest`:
+
+```bash
+docker pull ghcr.io/freesolo-co/flash-worker:cu128
+```
+
+## Verifying your setup
+
+`flash-server` runs a preflight at startup and refuses to serve if it cannot run a job.
+The rule is "enough to run a job", not "everything Freesolo runs in production":
+configuration that only degrades an optional capability warns instead of blocking boot.
+
+It fails on:
+
+- no GPU provider configured (all three keys missing) - the error names every acceptable
+  way out
+- `HF_TOKEN` missing
+- `FREESOLO_INTERNAL_KEY` missing
+
+It warns on a single-account RunPod pool and a missing `GITHUB_TOKEN`, then logs the
+providers it resolved:
+
+```
+GPU provider(s) configured: vast
+```
+
+That line is the quickest confirmation your credentials were picked up. Then submit a
+small run and watch it allocate.
+
+## Troubleshooting
+
+**Every run is rejected 503 with "project validation is unavailable".** `FLASH_STANDALONE`
+is not set, so the plane is trying to reach a Freesolo backend. Set it to `1`.
+
+**`401` on every request.** In standalone mode only `FREESOLO_INTERNAL_KEY` is accepted.
+Confirm the client is sending that exact value (`flash login --api-key ...`), with no
+trailing newline.
+
+**Startup says no GPU provider is configured** but you set a key. The value must be
+non-empty and non-whitespace. For RunPod specifically, a value of `","` parses to zero
+usable accounts.
+
+**Runs fail to allocate on a class you expected.** The allocator only proposes classes on
+configured providers. Check the `GPU provider(s) configured:` startup line.

{freesolo_flash_dev-1.0.72 → freesolo_flash_dev-1.0.73}/flash/envs/loader.py

@@ -230,7 +230,14 @@ def _is_safe_github_path_parts(parts: list[str] | tuple[str, ...]) -> bool:
 
 
 def _github_token() -> str | None:
-    return os.environ.get("GITHUB_TOKEN")
+    """The GitHub token, or ``None`` when unset OR blank.
+
+    Blank must collapse to ``None``, not fall through as a truthy string: a whitespace-only
+    GITHUB_TOKEN would otherwise build ``Authorization: Bearer <whitespace>``, and GitHub REJECTS a
+    malformed credential rather than treating the request as anonymous - so a public repo that
+    loads fine with no token at all would fail with one that is merely blank.
+    """
+    return (os.environ.get("GITHUB_TOKEN") or "").strip() or None
 
 
 def _is_commit_sha(value: str) -> bool:

freesolo_flash_dev-1.0.73/flash/providers/_auth.py

@@ -0,0 +1,18 @@
+"""Shared operator-credential helpers for the GPU providers."""
+
+from __future__ import annotations
+
+import os
+
+
+def load_provider_key(env_var: str) -> str | None:
+    """Provider API key from ``env_var`` (operator configuration), or None when unset OR blank.
+
+    Whitespace-stripped, and a whitespace-only value reads as unset. This is the single point
+    every instance provider loads its key through, so ``is_configured()``, the startup preflight
+    and the outbound API calls all agree about what "configured" means. Without the strip, a key
+    that is only whitespace (a stray newline in an env file) makes the provider advertise itself,
+    the preflight pass on it as the plane's only substrate, and every allocation then fail on an
+    unusable credential. Matches how the RunPod key pool and ``internal_key()`` normalize.
+    """
+    return (os.environ.get(env_var) or "").strip() or None