Self-hosting is for teams who want to run on their own GPU accounts. The
managed platform at platform.freesolo.co needs
none of this:
flash login and flash train are the whole setup.What you need
Configure Modal credentials, artifact storage, and the control-plane key.flash-server validates the required settings at startup.
Flash-owned run artifacts and published environment packages use private Azure
Blob storage. Provision the account/container and grant the controller the
permissions needed to read/write artifacts and issue worker credentials. A
preissued SAS must cover the run lifetime and allow read/create/write/list for
training. Keep serving credentials read-only where possible.
Optional Spot configuration enables Spot; Modal is
still required for custom sessions and customer-owned serving.
Quickstart
On the plane host, write the operator config to a file so both the server and your shell read the same values:flash, flash-cli, or python -m flash.cli for client commands.
flash-server runs in the foreground, so leave it running and open a second
terminal for the client. Read the key back from the same file rather than
retyping it:
flash-server never terminates TLS itself. For anything but loopback, put a
TLS-terminating reverse proxy (nginx, Caddy, a cloud load balancer) in front of
it and point --api-url at the proxy’s https:// address rather than the
plane’s own port.
Use your own server URL with --api-url. If you operate a separate compatible
authentication service, set --freesolo-url to its address.
flash-server reads the process environment, not .env. If you keep
credentials in a file, load it first:
EnvironmentFile, and any orchestrator’s secret
store work as-is.
Projects on a standalone plane
Every run config still needs a top-levelproject UUID - it groups runs and is
required in standalone mode too. Any well-formed UUID works, so pick one and
reuse it:
flash projects create <name> mints a UUID locally for you; pass it to
flash env setup --project <uuid>. flash projects list has no org directory to
enumerate and says so, so keep track of the ids you use. On the plane host, run
these as flash-cli (see the warning above).
Environments
Point[environment] id at a GitHub source the standalone plane can read. Every
supported form resolves to an environment.py entrypoint.
ref may be a branch, tag, or commit SHA; pin a SHA for reproducible runs.
Public repos work without credentials, subject to GitHub’s unauthenticated rate
limit; set GITHUB_TOKEN for private repos.
Standalone training accepts GitHub sources. Managed training accepts published
namespace/project/name IDs. Local directories are not supported training
sources. flash env push is for the managed Hub, not self-hosted training.
Modal training
SetMODAL_TOKEN_ID and MODAL_TOKEN_SECRET; MODAL_ENVIRONMENT defaults to
main. Keep the credential owner and environment stable while runs are active:
attempt ownership and cleanup are bound to that scope.
Use flash gpus for validated GPU classes and estimated resource rates. Omit
[gpu] type and count for automatic sizing, or constrain the class and card
ceiling as described in GPU configuration.
Placement remains subject to Modal capacity and workspace quotas; there is no
cross-cloud fallback.
Each sandbox reserves at least four CPU cores and 32 GiB RAM per GPU, has a
24-hour lifetime limit, and supports at most 512 GiB ephemeral disk. Resource
estimates do not include burst CPU/RAM above reservations, storage, or network
charges from your Modal invoice.
Spot training
Spot requires a provider configured on the control plane. Managed users select[gpu] spot = true without local provider credentials. For self-hosted
installations, configure provider access, region, network, and a worker image
before enabling Spot.
Use a worker host image prepared to run the Flash GPU worker container, with
network access to the private artifact store and model downloads. Private Azure
artifact storage is required before worker launch. Keep project and region
stable while runs are active so recovery and cleanup stay in the same account
scope. Check region quota and one-/eight-GPU availability separately from CLI
authentication. Select Spot in a training config with [gpu] spot = true.
See Spot training for admission, checkpoint recovery,
and the distinction between provider price thresholds and customer quotes.
What FLASH_STANDALONE=1 does
Set FLASH_STANDALONE=1 for a self-hosted installation.
- Use
FREESOLO_INTERNAL_KEYto authenticate clients. - Set a valid project UUID in every training config.
flash projects creategenerates a project UUID locally.flash projects listandflash traces exportare unavailable.- Use the same supported training models as managed Flash.
The state directory
The default data directory is~/.flash. Set FLASH_DATA_DIR to use another
writable directory:
flash-server reads it from its own
environment, so a bare shell assignment leaves state under ~/.flash while you
believe it moved.
Back up this directory. In a container, mount a persistent volume at the path
you configure. Run exactly one Flash server per data directory. On networked
storage, increase FLASH_SQLITE_BUSY_TIMEOUT_SECONDS if needed (default 30).
Logs
flash-server logs at INFO. Check these logs when setup or runs fail.
Set FLASH_LOG_LEVEL=DEBUG for more detail or WARNING for less.
Set FLASH_LOG_FORMAT=json for JSON logs.
Serving
flash serve deploy provisions serving in your own Modal account,
running the published serving image against one base model and one run’s adapter.
That is the supported serving path when you are not on managed serving, and it
works the same whether your training plane is managed or standalone. See
Serve in your own account
for the full walkthrough and
the CLI reference for every flag.
FLASH_SERVING_KEY you generated. Provider credentials are read for one call and
never stored. flash serve status and flash serve undeploy inspect and remove
that exact deployment.
Use flash serve to manage customer-owned endpoints. flash models deploy,
undeploy, and chat require a separate compatible service configured with
FREESOLO_SERVING_URL.
Use flash models export to copy a trained checkpoint to a Hugging Face
repository you own.
Optional pieces
The security model
A standalone plane is single-tenant. It cannot distinguish organizations, so anyone holdingFREESOLO_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, never commit it, and rotate it if it leaks.
After rotating the key, existing runs remain accessible with the new key.
The old key stops working.
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 - run without FLASH_STANDALONE and set FREESOLO_BASE_URL to an
identity backend serving the auth-verify contract.
Verifying your setup
flash-server preflights at startup: it fails on anything required to run a job,
and only warns when a setting degrades an optional capability.
Startup checks the control-plane key, configured GPU providers, and private
artifact storage. Optional upstream credentials are separate from artifact
storage. Confirm the reported provider before submitting:
Troubleshooting
401 on every request
401 on every request
In standalone mode
FREESOLO_INTERNAL_KEY is the only accepted credential.
Confirm the client is sending that exact value (flash login --api-key ...,
or flash-cli login on the plane host) and that the plane was started with it
set.Startup says no GPU provider is configured, but you set a key
Startup says no GPU provider is configured, but you set a key
Both
MODAL_TOKEN_ID and MODAL_TOKEN_SECRET must be non-empty in the
server process environment.Runs fail to allocate on a class you expected
Runs fail to allocate on a class you expected
Check
flash gpus, the model’s memory requirements, and your Modal workspace
quotas.Next steps
Configuration reference
Every field in a training config.
Supported models
The curated catalog a plane can train.