Skip to main content

Job Spec Reference

API reference content

The SkyPilot job spec is a YAML file that defines what SkyPilot needs to route, launch, and manage a job. The fields below cover the spec in CLI v0.9.

name

string required

A readable job identifier, shown in sky status output, cost reports, and log prefixes. Use letters, numbers, and hyphens only, with no spaces or underscores.

Example
name: llama3-finetune-v2

cloud

string default: "cheapest"

Provider choice. Set cloud to cheapest for SkyPilot to pick the lowest-cost provider at dispatch, or specify aws, gcp, azure, or lambda.

Example
cloud: cheapest  # or: aws | gcp | azure | lambda

resources

object required

Job hardware requirements. SkyPilot matches them with available instances across all configured providers.

resources.accelerators string

GPU model and quantity in TYPE:COUNT form. Available models: A100, H100, V100, A10G, and T4.

resources.cpus string or int

Lowest CPU count. Use 16+ for a minimum; with accelerators set, the instance family's standard is used by default.

resources.memory string

RAM minimum in GB, such as 64GB or 128GB+. Optional for accelerator-typed instances.

resources.use_spot boolean

Controls spot/preemptible use. With cloud: cheapest, true is the default; false requires on-demand capacity.

Example
resources:
  accelerators: A100:8
  memory: 320GB+
  use_spot: true

run

string (multi-line) required

Shell command or commands for the training job. They run in bash on the provisioned instance after setup, and YAML multiline blocks are supported.

Example
run: |
  python train.py \
    --model llama3-8b \
    --epochs 5 \
    --checkpoint-interval 1000

setup

string (multi-line) optional

Commands executed before run, for dependencies, Docker image pulls, or one-time instance setup. Runs once during provisioning, not after a migration restart.

Example
setup: |
  pip install torch==2.3.0 transformers==4.41.0
  pip install -r requirements.txt

file_mounts

dict optional

Connects local paths or cloud storage URIs to paths on the job instance. SkyPilot manages cross-cloud transfers. Source URIs may use s3://, gs://, or az://.

Example
file_mounts:
  /data/train: s3://my-bucket/datasets/train-v2
  /checkpoints: gs://my-gcs-bucket/checkpoints/run-001

envs

dict optional

Adds environment variables to both setup and run contexts. Pass sensitive values, such as API keys and tokens, as variables instead of placing them in run commands.

Example
envs:
  WANDB_PROJECT: llama-finetune
  NUM_NODES: "1"
  NCCL_SOCKET_IFNAME: eth0

Cost reports

Every completed job generates a cost record available in the SkyPilot dashboard. Records list the provider, instance type, zone, spot vs. on-demand, wall-clock duration, effective $/GPU-hour, and total billed amount. Records are retained 90 days on Team tier and 365 days on Scale and Enterprise.

From dashboard settings, configure budget alerts per-team or per-user. Webhook endpoints (Scale and Enterprise only) receive a JSON payload when the configured threshold is reached.