# Task YAML

The Mithril CLI uses the SkyPilot YAML task spec for defining and launching runs.

Because the spec is SkyPilot-compatible, existing SkyPilot tasks run without modification when targeting Mithril infrastructure.

To run on Mithril, specify:

```yaml
resources:
  infra: mithril
```

Mithril extends the spec with a limit price declared in task config that caps what you’ll pay per hour for each instance. Clusters launch only when capacity is available at or below that price, and often run at lower cost.

```yaml
config:
  mithril:
    limit_price: 32.0  # max $/hour/instance
```

If you’ve launched jobs with SkyPilot, the structure below will be familiar.

→ [SkyPilot YAML reference](https://docs.skypilot.co/en/latest/reference/yaml-spec.html)

***

## Spec structure

A task spec packages everything required to run your code on remote GPUs:

* Compute
* Environment setup
* Code sync
* Storage mounts
* Execution commands

Minimal example:

```yaml
resources:
  accelerators: B200:8

run: python train.py
```

## Execution lifecycle

Tasks execute in a fixed order:

```
Provision cluster
→ Sync workdir
→ Run setup (once)
→ Execute run commands
```

Subsequent runs:

* Skip provisioning if the cluster exists
* Skip setup
* Re-sync code
* Re-run commands

This creates a tight iteration loop for testing changes.

***

### 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        | 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              |

## Core SkyPilot fields

The following fields come directly from the SkyPilot spec.

### resources

```yaml
resources:
  infra: mithril
  accelerators: B200:8
```

Fields

| Field          | Type   | CLI override | Description                                  |
| -------------- | ------ | ------------ | -------------------------------------------- |
| `infra`        | string | `--infra`    | Infrastructure (`mithril`, `mithril/region`) |
| `accelerators` | string | `--gpus`     | GPU type:count (e.g., `B200:8`)              |

→ [infra](https://docs.mithril.ai/mithril-cli/task-yaml/infra "mention") — multi-cloud support, spot bids, reservations, and hosted Kubernetes

### 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
```

→ [File Mounts](https://docs.skypilot.co/en/latest/examples/syncing-code-artifacts.html#uploading-files-outside-of-workdir) for details.

### volumes

Mount Mithril persistent disks

```yaml
volumes:
  /data: my-volume-name
```

### 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.

→ [spot-auction-mechanics](https://docs.mithril.ai/compute-and-storage/spot-bids/spot-auction-mechanics "mention") — how the spot auction, pricing, and preemption work

### Complete example

```yaml
name: llm-training

resources:
  infra: mithril
  accelerators: B200:8

config:
  mithril:
    limit_price: 32.0

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
```