# Launch Overview

`ml launch` creates a cluster and runs a task on it.

## The workflow

1. Write a `task.yaml` describing what to run and what resources you need
2. Launch it: `ml launch task.yaml -c my-cluster`
3. Iterate: `ml exec`, `ssh`, `ml status`
4. Tear down: `ml down my-cluster`

## Define your task

```yaml
# task.yaml
resources:
  accelerators: B200:8
run: python train.py

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

```bash
ml launch task.yaml -c my-cluster
```

→ [Task YAML](yaml/overview.md)

## What happens

1. Validates task and resources
2. Provisions a **cluster** on Mithril Cloud (or reuses an existing one)
3. Syncs workdir to cluster
4. Runs setup commands (if any)
5. Submits the task as a **job** on the cluster
6. Streams logs (unless `--detach-run`)

## Cluster lifecycle

| Flag | Description |
|------|-------------|
| `-c, --cluster` | Name the cluster (reuses if it already exists) |
| `-i, --idle-minutes-to-autostop` | Auto-stop after idle |
| `--down` | Delete cluster after job completes |
| `-d, --detach-run` | Don't stream logs |
| `-y, --yes` | Skip confirmation |
| `--dryrun` | Validate without launching |

After launch:

- Cluster stays running until stopped or terminated
- Use [`ml exec`](../03-clusters/exec.md) to iterate on the launched cluster
- Use `ml down` to terminate

## Reusing a cluster

If `-c` names an existing cluster, `ml launch` will:

- Re-run setup commands
- Re-sync file mounts
- Run the new task

For faster iteration when only `run` changed, use [`ml exec`](../03-clusters/exec.md) instead.

## Topics

- [Task YAML](yaml/overview.md) — YAML spec, resources, file mounts
- [Exec](../03-clusters/exec.md) — run commands on an existing cluster without re-provisioning

## Concepts

- [Tasks, Clusters, and Jobs](concepts/tasks-clusters-jobs.md) — how these relate
- [Limit Price](../concepts/spot-bid.md) — how the spot auction and preemption work
- [GPU Selection](concepts/gpu-selection.md) — choosing GPU types
- [Autostop](concepts/autostop.md) — automatic cluster shutdown
- [Multi-Node](concepts/multi-node.md) — distributed training
- [Detach Mode](concepts/detach.md) — background execution
- [Dryrun](concepts/dryrun.md) — validation without launching
