> ## Documentation Index
> Fetch the complete documentation index at: https://docs.compute-desk.com/llms.txt
> Use this file to discover all available pages before exploring further.

# The YAML Spec

> Your contract for GPU infrastructure — what you need, verified and delivered

## What is the YAML spec?

The YAML spec is how you tell the Compute Clear API exactly what infrastructure you need. It's a declarative document — you describe **what** you want, not **how** to get it. The API finds the best match across 20+ cloud providers.

Think of it as a **contract**: you specify your requirements, and we guarantee that every offer returned meets them. Our proprietary validation layer verifies each offer against your spec before presenting it, so you never procure something that doesn't match.

## How it works

```
┌─────────────┐     ┌──────────────────┐     ┌──────────────────┐
│  Your YAML   │ ──▶ │  Multi-vendor     │ ──▶ │  Validated offers │
│  spec        │     │  query + validate │     │  (contract met)   │
└─────────────┘     └──────────────────┘     └──────────────────┘
```

1. You send a YAML spec to `POST /get_offers`
2. The API queries all eligible vendors in real-time
3. Each offer is **validated** against your requirements:
   * GPU type and count match exactly
   * Price is within your budget
   * Region, contract type, and network requirements are met
   * Boot disk meets minimum size (if specified)
   * Storage capabilities are compatible (if storage requested)
4. Only validated offers are returned, sorted by price

## Spec structure

```yaml theme={null}
# Top-level filters
region: EU                    # Geographic filter
vendor: nebius                # Specific vendor (optional)
max_procure_time_seconds: 300 # Machine ready within this time

# Compute requirements (required unless storage-only)
compute:
  gpu_type: H100              # What GPU you need
  gpu_count: 8                # How many GPUs
  type: vm                    # vm (default) or container
  max_price_per_gpu_hour: 3.5 # Your budget per GPU per hour
  contract_type: ondemand     # ondemand or spot
  min_boot_disk_gb: 200       # Minimum boot disk size

# Network requirements (optional)
network:
  supports_cilium: true       # Require Cilium networking

# Storage volumes (optional)
storage:
  - type: filesystem          # block_disk or filesystem
    class: standard           # standard, performance, economy, premium
    size: 1TB                 # Size with unit
    persistent: true          # Survives VM deletion

# Instance configuration (optional)
cloud_init: |                 # Startup script
  #cloud-config
  packages:
    - htop
```

## Sections in detail

### `compute`

Defines your GPU requirements. This is the core of most specs.

| Field                    | Required | Description                                                                                                                                                     |
| ------------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `gpu_type`               | Yes      | GPU family (`H100`) or canonical name (`nvidia-h100-sxm5-80gb`). Use `\|` for multiple: `"H100 \| A100"`                                                        |
| `gpu_count`              | Yes      | Number of GPUs: 1, 2, 4, or 8                                                                                                                                   |
| `type`                   | No       | `vm` (default) or `container`. VMs give you full OS access via SSH. Containers run on shared infrastructure (e.g., Vast.ai).                                    |
| `max_price_per_gpu_hour` | No       | Price cap in USD. Offers above this are excluded                                                                                                                |
| `contract_type`          | No       | `ondemand` or `spot`. Omit for both                                                                                                                             |
| `min_boot_disk_gb`       | No       | Minimum boot disk size. Excludes offers below this size and vendors without verified boot disk reporting. Less relevant when procuring with additional storage. |

### `storage`

A list of storage volumes. Each volume has three dimensions:

| Field        | Required | Description                                                                 |
| ------------ | -------- | --------------------------------------------------------------------------- |
| `type`       | Yes      | `block_disk` (single VM) or `filesystem` (shared across VMs)                |
| `class`      | No       | Performance tier: `standard` (default), `performance`, `economy`, `premium` |
| `persistent` | No       | `false` (default) = deleted with VM. `true` = independent lifecycle         |
| `size`       | No       | Size with unit: `500GB`, `2TB`                                              |
| `mount`      | No       | Mount path (e.g., `/data`, `/scratch`). Default varies by vendor.           |

When you include storage, the API automatically filters to vendors that support your requested type and class.

### `network`

| Field             | Required | Description                                           |
| ----------------- | -------- | ----------------------------------------------------- |
| `supports_cilium` | No       | When `true`, only Cilium-capable vendors are included |

### `cloud_init`

A startup script that runs on first boot. Two formats:

* **`#cloud-config`** — Declarative YAML (packages, files, commands)
* **`#!/bin/bash`** — Shell script

See the [Cloud-Init guide](/guides/cloud-init) for details.

## What we validate

Every offer returned by the API has been verified against your spec:

| Requirement       | Validation                                                                  |
| ----------------- | --------------------------------------------------------------------------- |
| GPU type          | Exact match against vendor's reported GPU model                             |
| GPU count         | Exact match (no partial fulfillment)                                        |
| Price cap         | `gpu_price_per_hour <= max_price_per_gpu_hour`                              |
| Region            | Offer's region matches your filter                                          |
| Contract type     | Exact match (`ondemand` or `spot`)                                          |
| Boot disk         | Size verified against vendor's reported value (excludes unverified vendors) |
| Storage type      | Vendor supports the requested storage type                                  |
| Storage class     | Vendor has a matching storage class                                         |
| Network           | Vendor supports Cilium (if requested)                                       |
| Provisioning time | Machine will be ready within your specified time limit (if set)             |

## Examples

### Minimal

```yaml theme={null}
compute:
  gpu_type: H100
  gpu_count: 1
```

### Budget-conscious testing

```yaml theme={null}
region: US
compute:
  gpu_type: A100
  gpu_count: 8
  max_price_per_gpu_hour: 2.00
  contract_type: spot
```

### Production inference with storage

```yaml theme={null}
compute:
  gpu_type: L40S
  gpu_count: 1
  max_price_per_gpu_hour: 2.00
  contract_type: ondemand
  min_boot_disk_gb: 200
storage:
  - type: filesystem
    class: standard
    size: 500GB
    persistent: true
network:
  supports_cilium: true
cloud_init: |
  #cloud-config
  packages:
    - nvidia-container-toolkit
  runcmd:
    - docker pull my-inference-image:latest
```