Requirements

What you need before installing, from a single GPU box to a governed cluster.

StarForge is designed to work on one GPU server and on a centrally governed multi-node cluster, without a different product for each. What changes between them is which of the pieces below you actually need.

Always

Piece	Notes
Python 3.12–3.13	For the control plane and the CLI
A container runtime	Docker or Podman. Bare-process mode exists for development and isolates nothing
Storage	A path the console and every node see identically — see storage layout
At least one GPU	For anything but the platform’s own tests, which run in simulation mode

For a team

Piece	Why
Postgres	SQLite is single-writer. Two console replicas contending for one file is not a deployment
Redis	Shared cache, distributed locks, rate limiting, immediate token revocation. Without it, background tasks stop rather than run unsafely across replicas
S3-compatible object storage	Job packages, artifacts, datasets, archives. Without it everything falls back to shared-filesystem paths
A fixed FORGE_WEB_JWT_SECRET	Otherwise every restart signs with a new key and logs everyone out
An https domain	FORGE_PUBLIC_URL. Single sign-on cannot work without it

A deployment with more than one console replica and no Redis has background roles disabled — storage accounting, diagnosis, the daily report and the watchdog simply do not run. The scheduled tasks page says so in a banner, but it is easy to miss.

Per executor

local

One machine. Docker or Podman, and NVIDIA container runtime for real GPU passthrough. Nothing else. This is the right starting point even for a team — moving to another executor later is a setting, not a migration.

agent

Several bare-metal machines, each running forgelet. Requires the storage root mounted at the same path on the console and every node, and a shared bearer token both sides hold. A missing token refuses startup rather than running unauthenticated.

kuberay

A Kubernetes cluster with the KubeRay operator, a GPU device plugin, and an RWX PVC for the storage root. An RWO claim does not fail outright — it gives each pod its own volume, so checkpoint shards split across nodes and the run cannot be resumed.

slurm

slurmrestd reachable over REST, with a JWT. The control plane never falls back to sbatch or SSH. Container images must be available as SIF or SQSH through FORGE_RUNTIME_REGISTRY_FILE, and the container runtime profile must be chosen explicitly.

Network

Direction	Needed for
Users → console	The web console and the API
Cluster → console	Ingest. Training reports logs and metrics back, so FORGE_INGEST_URL must be reachable from inside the cluster — never 127.0.0.1
Console → executor	Kubernetes API, slurmrestd, or the agent nodes
Cluster → registry	Pulling training images
Cluster → model hub	Weights, or an internal mirror — see air-gapped

The second row is the one people miss. A console that users can reach is not automatically a console that a worker node can reach.

Optional, and what you lose without each

Missing	Consequence
Object storage	No sf dataset push, no automatic post-training evaluation
An LLM endpoint	No AI diagnosis, no Ask Agent, no LLM judge, no daily report
A sandbox image	Environments that run model-generated code are refused rather than falling back to the training container
Argilla	No preference annotation loop
Hugging Face OAuth	No gated models, no pushing exports