launch.yaml¶

launch.yaml configures one job. launch validate checks a file and prints every refusal with its path. It exits 64 if there is any. The JSON Schema is published beside this page.

An unknown key at any level is refused, and so is a key in another case. version must be 1, and the file needs a train section, a serve section or both. launch train refuses a file without train, and launch serve one without serve.

train¶

Key	Default	Meaning
`command`	required	Run verbatim on every rank.
`procsPerNode`	the scheduler's	Ranks per node. Absent, it comes from `PET_NPROC_PER_NODE` or `SLURM_NTASKS_PER_NODE`, and the launcher refuses to start if neither is set.
`rendezvous.port`	`0`	Slurm only. `0` picks a free port for the job.
`rendezvous.resumePort`	`0`	Kubeflow only. `0` means `PET_MASTER_PORT` + 1.
`rendezvous.joinTimeout`	`10m`	How long nodes wait for the resume point.
`env`	none	Added to every rank's environment. Names under `LAUNCH_` and `DISPATCH_` are refused.

checkpoint¶

Optional. Without it there is no resume and no publication.

Key	Default	Meaning
`root`	required	An absolute path or an `s3://` URL.
`framework`	required	`hf` or `dcp`: how `publish watch` decides a save is complete.
`resumeFlag`	none	Appended to `train.command` with the path when a resume point exists.
`publish`	`publish`, or `/opt/dispatch/publish` on Kubeflow	The helper's path.
`creds`	none	`s3://` roots only. `${DUNSCAITH_S3_CREDS}` is the only interpolation in the file, and it must be the whole value.

signal¶

Key	Default	Meaning
`grace`	the kill window	The most the payload is given after a signal, in whole seconds. `0s` says no save is wanted.

heartbeat¶

Optional. Without it there is no hang detection beyond NCCL's own.

Key	Default	Meaning
`timeout`	`5m`	The longest gap between beats in phase `train`. It must be below NCCL's timeout, which is 10 minutes unless `ncclTimeout` says otherwise.
`startup`	`45m`	The longest wait for the first beat.
`ncclTimeout`	none	The process-group timeout, for a payload that sets its own.
`phases`	none	A timeout per named phase. `train` is refused, because `timeout` already times it.

gpu¶

Key	Default	Meaning
`health`	`optional`	`required` refuses with 64 when NVML can't start or shows no GPUs, and needs the `launch-nvml` build. Under Slurm the coordinator's node makes that check too, so its step must be able to see a GPU. `optional` reads NVML where it can and reports `absent` otherwise. `off` reads nothing and doesn't load the library.

serve¶

Key	Default	Meaning
`command`	required	How to start vLLM, such as `[vllm, serve]`.
`model.name`, `model.path`	required	The base model and the name it is served under. A comma is refused in the name.
`adapters`	none	Startup LoRA adapters, name to path. A comma or `=` is refused in a name, and so is the base model's name.
`lora.runtime`	`false`	Allow `POST /v1/load_lora_adapter`.
`lora.maxLoras`	vLLM's	LoRAs per batch.
`lora.maxLoraRank`	vLLM's	One of 1, 8, 16, 32, 64, 128, 256, 320 or 512.
`lora.maxCpuLoras`	vLLM's	CPU slots, no fewer than `maxLoras`.
`env`	none	Added to vLLM's environment. Refused: names that aren't shell identifiers, `LAUNCH_` and `DISPATCH_` names, and `VLLM_ALLOW_RUNTIME_LORA_UPDATING`, which `lora.runtime` owns.
`port`	`8000`	The loopback port.
`ready.timeout`	`20m`	How long to wait for vLLM to become ready.
`ready.interval`	`5s`	How often to check.
`stopGrace`	`30s`	How long vLLM gets after SIGTERM before SIGKILL.

Flags the launcher owns¶

A URL with userinfo, a query string or a fragment, or with an @ anywhere later in the value, even after a space, is refused in serve.command, serve.model and serve.adapters, names as well as paths, including inside an argument such as --model=URL, because each reaches the manifest's exact argv. A URL that needs no credential but has a query string is refused too, since the launcher can't tell them apart. The @ rule deliberately over-refuses: a legitimate @ in a path or query must be percent-encoded, as %40.

That can't catch a credential passed as a bare flag, such as --api-key secret, which looks like any other flag and is recorded as written. Give vLLM its API key in the environment instead, as VLLM_API_KEY, with serve.env or inherited: the manifest records that variable as ***. Of the rest of the environment only VLLM_* variables reach the manifest, and a value there is masked only where go/redact recognises a credential by its shape, so don't put any other secret in a VLLM_* variable.

These are refused in serve.command: --host, --port, --served-model-name, --enable-lora, --lora-modules, --max-loras, --max-lora-rank and --max-cpu-loras. They are matched the way vLLM's parser reads them, so --max_loras and the abbreviation --served-model are refused too.

--config is refused outright. Its contents would be flags the launcher never sees, so put them in serve.command, where they are checked and recorded.