px.yaml

Reference for the px.yaml cluster spec.

INFO

px.yaml is a curated subset of the SkyPilot task YAML spec. This page mirrors the annotated template emitted by px cluster generate-config. For the version you have installed, that command is always the source of truth.

Generating a Starter Spec

Run px cluster generate-config in the directory where you want to keep px.yaml. It writes a fully-commented px.yaml.example you can copy and edit. For a tutorial walkthrough, see Quick Start, Step 6.

Annotated Template

This is the template px cluster generate-config produces:

---
# PX uses a subset of the SkyPilot task YAML spec.
# Full reference: https://docs.skypilot.co/en/stable/reference/yaml-spec.html

# Number of cloud nodes to provision. The first node is the head node
# and the rest are workers (e.g. 2 = 1 head + 1 worker).
num_nodes: 2

# Resource constraints for instance selection.
# PX picks the cheapest instance matching these constraints.
resources:
  # Cloud provider. Options: gcp
  infra: gcp
  # vCPUs per node
  cpus: 2
  # Attached disk size in GB
  disk_size: 100
  # Disk speed tier: low, medium, high, best, ultra
  disk_tier: low
  # Use spot/preemptible instances (cheaper, but can be reclaimed)
  use_spot: true
  # Ports to open on each node (8020 = PX supervisor)
  ports:
    - 8020

# Environment variables accessible in the setup and run scripts.
# envs:
#   MY_BUCKET: my-data-bucket

# Mount cloud storage buckets on each node. Supports S3, GCS, and Azure Blob.
# Each entry maps a remote mount path to a bucket source and store type.
# Use `persistent: true` to keep the bucket after the cluster is torn down.
# file_mounts:
#   /my-bucket:
#     source: gs://my-gcs-bucket
#     store: gcs
#     persistent: true

# Local directory synced to each node. "." syncs the current project directory
# to ~/sky_workdir on each node.
workdir: .

# Bootstrap script run on each node after provisioning.
# Runs once on first setup, and again on `px cluster sync --run-setup`.
setup: |
  echo "Installing system dependencies..."
  DEBIAN_FRONTEND=noninteractive sudo apt-get update
  DEBIAN_FRONTEND=noninteractive sudo apt-get install --no-install-recommends \
    --no-install-suggests -y \
    build-essential

  echo "Setting up uv..."
  if [[ ! -f ~/.local/bin/uv ]]; then
    curl -LsSf https://astral.sh/uv/install.sh | sh
  else
    uv self update
  fi

  echo "Setting up Python virtual environment..."
  uv venv --allow-existing
  uv sync