> ## Documentation Index
> Fetch the complete documentation index at: https://starforge.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# 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.14 (control plane), 3.12+ (CLI) | The console image ships 3.14. The `sf` CLI and the node daemon still run on 3.12 and later, so upgrading the server does not force an interpreter upgrade on researchers' laptops or on GPU nodes. |
| 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](/en/ops/storage) |
| 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 |
**Which psycopg the console uses.** The shipped image compiles `psycopg[c]` against the base
image's libpq, so TLS to a managed Postgres validates against the certificates the image trusts
and a libpq security fix arrives with the next image rebuild. `psycopg[binary]` — the same C code
with its own libpq and its own OpenSSL bundled inside the wheel — is what a development checkout
gets, because it needs no compiler. Installing the wheel yourself, pick one:
`starforge-console[c]` (needs `libpq-dev` and a compiler) or `starforge-console[binary]`. With
neither, psycopg falls back to a pure-Python binding: slower, never broken.
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](/en/console/admin-tasks) says so in a banner, but it is easy to miss.
## Per executor
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.
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.
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.
`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](/en/ops/airgapped) |
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 |