Quickstart

Install the CLI, submit a GRPO job, and see the first point land on the loss curve.

Fifteen minutes from nothing to a training run you can watch. The path below is deterministic: copy it and it runs.

Before you start

An account · required

An administrator creates it, or your deployment uses single sign-on. You also need the console URL.

Quota and a hardware profile · required

sf status prints both after you log in. Every profile name on this site — h200:8 and friends — is an example; use the ones your own sf status prints.

Model weights reachable from the cluster · required

The scaffold trains Qwen/Qwen2.5-1.5B and pulls it from Hugging Face when the job starts. On an air-gapped network an administrator points the deployment at an internal mirror; see air-gapped deployments. Without it the job starts, stalls at downloading weights, and eventually times out.

Object storage · optional

Only needed for sf dataset push and for automatic evaluation after training. This path works without it.

1. Install the CLI and create a project

   uv tool install starforge-core     # or: pip install starforge-core
   sf init my-lab --yes
   cd my-lab
   

   Do not clone the platform repository — sf init is what creates your project. See sf init for what it puts on disk. Later, upgrade with sf update rather than reinstalling by hand.

2. Log in

   sf login --server https://starforge.your-company.com
   

   Opens a browser. On an SSH session add --device-flow; in CI pass --token. Credentials land in ~/.forge/.

   sf status
   

   Prints your account, your quota, and the profile names this deployment actually has. Note them — the next step needs one.

   

   Console sign-in. Username and password, or single sign-on where the deployment has it.

3. Create an experiment

   sf new my-grpo --method nemo-rl/grpo
   

   Writes experiments/my-grpo/ with config.yaml, README.md and recipe.lock.json.

   sf methods                 # every method this deployment offers
   sf methods nemo-rl/grpo    # what you can tune, with ranges and defaults
   
4. Tune and validate

   Edit experiments/my-grpo/config.yaml. The keys people change most often — learning rate, batch size, sequence length — are at the top of the scaffold.

   sf validate my-grpo
   

   Checks types, ranges and batch-size divisibility against the method declaration. A typo fails here, in seconds, instead of after a queue wait.

5. Submit

   git add -A && git commit -m "first grpo run"
   sf submit my-grpo --profile h200:8
   

   Prints a job id. --profile is the only resource flag: h200 takes the registry default shape, h200:4 asks for four GPUs, h200:16 for two full nodes.

   A dirty working tree is refused unless you pass --allow-dirty, so a result stays traceable to an exact commit.

   sf job logs        # omit the id to follow the latest job
   

   Status moves QUEUED → SUBMITTED → PENDING → RUNNING. Queued means admitted but not yet on the cluster — see job states.

6. Watch it in the console

   Open the console, go to Jobs, and click into yours.

   Tab	What it shows
   Charts	Loss, reward, KL, gradient norm, step by step
   Logs	The full stream, searchable and downloadable
   Validation	Sample conversations and reward histograms
   System	GPU utilisation, memory, network
   Diagnostics	On a failure or an odd curve, a report and the knobs worth trying

   

   Job charts during a GRPO run: reward, accuracy, and training scalars.

Confirm it worked

Check these in order. If one does not match, stop there — every later step assumes the previous one actually happened.

When	What you should see	If it does not match
After sf status	Your username, your quota, at least one profile name	Login did not complete, or no quota has been granted
After sf submit	A job id, state QUEUED or SUBMITTED	A refusal names the gate that refused it — see errors
1–3 min	State turns RUNNING	Stuck in QUEUED: the job page names the gate holding it
3–8 min	Logs show the weight download, then Ray starting	Stuck downloading: the mirror, see air-gapped
8–15 min	The first point on the Charts tab	Logs moving but charts empty: ingest, see below

Once that first point appears, the path worked.

If the logs show training and the charts are still empty, the reporting call is not happening. For a catalog method that is an ingest configuration problem; for your own trainer it usually means starforge.report was never called. See reporting.

Next

Submitting in depth

Every flag on the submit path: resources, overrides, data, images, follow-on actions.

Your own trainer

When the method you need is not in the catalog.

Sweeps

One command, many variants, grouped in the console.

Benchmarks

Score the run against GSM8K, MMLU, C-Eval and the rest.