The YAML Spec

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)   │
└─────────────┘     └──────────────────┘     └──────────────────┘

You send a YAML spec to POST /get_offers
The API queries all eligible vendors in real-time
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)
Only validated offers are returned, sorted by price

Spec structure

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

compute:
  gpu_type: H100
  gpu_count: 1

Budget-conscious testing

region: US
compute:
  gpu_type: A100
  gpu_count: 8
  max_price_per_gpu_hour: 2.00
  contract_type: spot

Production inference with storage

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

Getting Started

Concepts

Overview

Discovery

Offers

Resources

What is the YAML spec?

How it works

Spec structure

Sections in detail

`compute`

`storage`

`network`

`cloud_init`

What we validate

Examples

Minimal

Budget-conscious testing

Production inference with storage

​What is the YAML spec?

​How it works

​Spec structure

​Sections in detail

​compute

​storage

​network

​cloud_init

​What we validate

​Examples

​Minimal

​Budget-conscious testing

​Production inference with storage

What is the YAML spec?

How it works

Spec structure

Sections in detail

`compute`

`storage`

`network`

`cloud_init`

What we validate

Examples

Minimal

Budget-conscious testing

Production inference with storage