Lab and console
| Term | Meaning |
|---|---|
| Lab / repository | Directory created by sf init. Marker file is starforge.yaml. sf walks up from the current directory to find it, same idea as git. |
| Project | The name field in starforge.yaml. The console groups every job from this lab under @<user>/<name>. Names are unique per user, not globally. |
| Experiment | A directory under experiments/<name>/. Holds config.yaml, recipe.lock.json, and for custom jobs train.sh. Creating an experiment does not start GPUs. |
| Job / run | One admitted submission. It has a run id, a ledger status, and (once launched) a backend handle. One experiment can produce many jobs. |
| Profile | A named GPU shape in the server hardware registry (h200, h100, …). --profile h200:8 means that series and 8 GPUs total. |
Methods and packaging
| Term | Meaning |
|---|---|
| Recipe | Versioned declaration of a method: entrypoint, params, metrics, artifacts, runtime matrix. Files live in starforge-core under recipes/catalog/. |
| Catalog | The set of recipes the connected server has published. Client and server must agree on digest and version. |
| Method id | <framework>/<method>, for example trl/kto. |
| recipe.lock.json | Written by sf new. Pins recipe digest and framework version. Submit refuses a stale lock. |
| JobSpec | forge/v2 JSON the CLI builds and the server admits. You do not hand-write it. See JobSpec. |
| Job Capsule | capsule.json + bootstrap.sh + runner.pex injected by the server after admit. Training images do not preinstall the platform package. |
| runtime_id | Key for the deployment artifact (OCI image, SIF, SQSH). Resolved from catalog, FORGE_IMAGE_*, the runtime registry file, or --image. |
Execution
| Term | Meaning |
|---|---|
| Executor | How the control plane starts a container: local (Docker on the console host), agent (forgelet on a node), kuberay (RayJob), slurm (slurmrestd only). |
| Pool | One homogeneous GPU group in the JobSpec. Heterogeneous jobs use two pools (train + rollout) and only work on kuberay / slurm. |
| FORGE_OUT_DIR | The one directory whose contents survive the job. Checkpoints written elsewhere disappear with the scratch tree. |
| Ingest | HTTP path from the training container back to the console (logs, metrics, samples). FORGE_INGEST_URL must be reachable from the GPU node, not 127.0.0.1 on the laptop. |
Custom jobs
| Term | Meaning |
|---|---|
| custom/custom | Catalog recipe that runs experiments/<name>/train.sh and nothing else. No framework detection. No fallback from a failed adapter. |
Observability platform | Recipe option: runner injects PYTHONPATH so import starforge works without installing the wheel in the image. |
Observability external | Current catalog default for custom/custom. Submit requires --observability-url. Console charts still need starforge.report if you also want them. |