# Task YAML Specification

Complete reference for task YAML files.

## Top-level fields

| Field | Type | Required | CLI override | Description |
|-------|------|----------|-------------|-------------|
| `name` | string | No | `-n, --name` | Task name (auto-generated if omitted) |
| `resources` | object | Yes | See [resources](#resources) | Compute requirements |
| `run` | string | Yes | Inline command arg | Main commands to execute |
| `setup` | string | No | — | Setup commands (run once per cluster) |
| `workdir` | string | No | `--workdir` | Local directory to sync |
| `file_mounts` | object | No | — | Remote storage mounts |
| `volumes` | object | No | — | Mithril volumes to mount |
| `envs` | object | No | `-e KEY=VALUE` | Environment variables |
| `num_nodes` | int | No | `--num-nodes` | Number of nodes (default: 1) |
| `config` | object | No | `--config KEY=VALUE` | Provider-specific config |

## resources

See [Resources](resources.md) for full specification.

```yaml
resources:
  infra: mithril
  accelerators: B200:8
  cpus: 32+
  memory: 256+
  disk_size: 500
```

## run

Main task commands. Runs every time the task is launched.

```yaml
run: python train.py
```

Multi-line:

```yaml
run: |
  cd /app
  python train.py --epochs 100
  python eval.py
```

## setup

One-time setup commands. Runs once when cluster is provisioned.

```yaml
setup: |
  pip install -r requirements.txt
  apt-get update && apt-get install -y vim
```

## workdir

Sync local directory to cluster.

```yaml
workdir: .
```

Files are synced to `~/sky_workdir/` on the cluster.

## file_mounts

Mount remote storage (S3, GCS, etc.).

```yaml
file_mounts:
  /data: s3://my-bucket/data
  /models: gs://my-bucket/models
```

See [File Mounts](file-mounts.md) for details.

## volumes

Mount Mithril persistent or ephemeral volumes.

```yaml
volumes:
  /data: my-data-volume
  /scratch:
    type: ephemeral
    size: 100GB
```

## envs

Environment variables available in setup and run.

```yaml
envs:
  WANDB_API_KEY: xxx
  BATCH_SIZE: 32
  DEBUG: "true"
```

## num_nodes

Multi-node distributed training.

```yaml
num_nodes: 2
```

SkyPilot sets up distributed environment variables automatically.

## config

Provider-specific configuration.

```yaml
config:
  mithril:
    limit_price: 8.0  # max $/hour/instance you'll pay
```

**Default**: $32.00/hour/instance if not specified.

→ [Limit Price](../../concepts/spot-bid.md) — how the spot auction, pricing, and preemption work

## Complete example

```yaml
name: llm-training

resources:
  infra: mithril
  accelerators: B200:8

num_nodes: 4

workdir: .

file_mounts:
  /data: s3://my-bucket/training-data

volumes:
  /checkpoints: my-checkpoints-volume

envs:
  WANDB_PROJECT: my-project
  WANDB_API_KEY: ${WANDB_API_KEY}

setup: |
  pip install -r requirements.txt
  wandb login

run: |
  torchrun \
    --nproc_per_node=8 \
    --nnodes=$SKYPILOT_NUM_NODES \
    train.py \
    --data /data \
    --output /checkpoints

config:
  mithril:
    limit_price: 8.0
```
