burst

Burst (one coupled multi-node GPU job)

Burst is the escape hatch for a single distributed task: gang-schedule N nodes, run one command under torchrun, get logs, exit. It is deliberately not a workflow surface — there is no plan, no stage graph, no decision artifact, and nothing for a toolRef to describe.

If you need a second stage, you need a workflow. Author an npa.workflow/v0.0.1 spec under workflows/ instead (skills/workflows/author-npa-workflow/SKILL.md). submit-yaml rejects multi-task documents, and a guardrail pins the example set so a pipeline cannot quietly grow here.

Submit a distributed run directly

npa burst submit \
  --image <registry>/<image>:<tag> \
  --nodes 2 \
  --gpu-per-node H100:8 \
  --entrypoint "python train.py --config configs/run.yaml" \
  --name <job-name> \
  --json

All four of --image, --nodes, --gpu-per-node, --entrypoint are required. A plain image reference is rendered as docker:<image>. --json prints only the serialized job handle, which is what you want when scripting.

The entrypoint runs under torchrun, not directly. Burst derives the rendezvous from SkyPilot's node environment and exports MASTER_ADDR, MASTER_PORT, WORLD_SIZE, and RANK, then execs torchrun with --nnodes, --node-rank, and --master-addr already set. Two consequences:

• torchrun must exist in the image. Burst checks and fails with an explicit message if it is missing.
• Do not set the distributed variables yourself and do not wrap your command in another torchrun. Pass the training command as if it were a single-process entrypoint.

--gpu-per-node is a SkyPilot accelerator spec such as L40S:1 or H100:8, and it is per node: all GPUs of one task land on one node. Confirm the name the cluster actually advertises with npa workbench workflow gpus --cluster <name> — Kubernetes names accelerators after node labels, so the spec string is discovered rather than guessed.

Submit a single-task YAML