vastai

Vast.ai CLI Skill

This skill helps you use the vastai CLI to manage GPU cloud resources on the Vast.ai marketplace. Vast.ai is an open marketplace for GPU compute — you can search for available machines, rent them, deploy Docker containers, transfer data, and manage billing, all from the command line.

Prerequisites

• Install: pip install vastai (or uv pip install vastai)
• Authenticate: Get your API key from https://cloud.vast.ai/cli/ then run:

  vastai set api-key YOUR_API_KEY
  

  The key is stored at ~/.vast_api_key. Never share API keys.

Core Workflow

The typical workflow is: Search -> Create -> Use -> Destroy.

1. Search for GPU Offers

vastai search offers '<query>' -o '<sort_field>'

The query uses a simple field operator value syntax. Multiple conditions are space-separated (implicit AND).

Operators: >, >=, <, <=, =, !=

Common examples:

# Find RTX 4090 machines with 99%+ reliability
vastai search offers 'gpu_name=RTX_4090 reliability>0.99 num_gpus=1'

# Find multi-GPU A100 setups, sorted by price
vastai search offers 'gpu_name=A100_SXM4 num_gpus>=4 reliability>0.98' -o 'dph'

# Find any GPU with 24GB+ VRAM under $0.50/hr
vastai search offers 'gpu_ram>=24 dph<0.5 reliability>0.95' -o 'dph'

# Datacenter-only machines with fast internet
vastai search offers 'datacenter=true inet_down>500 inet_up>500'

Key search fields (see references/search-fields.md for full list):

Field	Description
gpu_name	GPU model (use underscores: RTX_4090, A100_SXM4)
num_gpus	Number of GPUs
gpu_ram	Per-GPU VRAM in GB
gpu_total_ram	Total VRAM across all GPUs
cpu_cores	vCPU count
cpu_ram	System RAM in GB
disk_space	Available storage in GB
dph	Cost per hour ($/hr)
reliability	Machine reliability score (0-1)
cuda_vers	Max supported CUDA version
compute_cap	CUDA compute capability (e.g., 800 = 8.0)
inet_down / inet_up	Network speed in Mb/s
datacenter	Datacenter-only flag (true/false)
dlperf	Deep learning performance score
total_flops	Combined GPU TFLOPs
rentable	Currently available
static_ip	Has stable IP
verified	Verification status

Sorting: Use -o 'field' for ascending, -o 'field-' for descending.

Pricing type: Add -d (on-demand), -b (bid/spot), or -r (reserved).

2. Create an Instance

vastai create instance OFFER_ID --image IMAGE --disk DISK_GB [OPTIONS]

Key options:

• --image IMAGE: Docker image (e.g., pytorch/pytorch:latest, vastai/tensorflow)
• --disk DISK_GB: Local disk size in GB
• --ssh: Enable SSH access
• --jupyter: Enable Jupyter access
• --direct: Direct connection (vs proxied)
• --onstart SCRIPT: Startup script filename
• --label LABEL: Human-readable label
• --env ENV: Environment variables and port mappings
• --price PRICE: Bid price for spot instances ($/hr)

Example:

# Rent offer 2459368 with PyTorch, 50GB disk, SSH access
vastai create instance 2459368 --image pytorch/pytorch:latest --disk 50 --ssh --direct

Billing starts immediately for storage; GPU billing starts once the instance reaches "running" state.

3. Manage Instances

# List your instances
vastai show instances

# View specific instance details
vastai show instance ID

# Get SSH connection string
vastai ssh-url ID

# View logs
vastai logs ID --tail 100

# Stop (preserves data, stops GPU billing)
vastai stop instance ID

# Start a stopped instance
vastai start instance ID

# Reboot without losing GPU priority
vastai reboot instance ID

# Label for easy identification
vastai label instance ID "my-training-run"

4. Transfer Data

# Copy local file to instance
vastai copy local_file instance_id:/path/on/instance

# Copy from instance to local
vastai copy instance_id:/path/on/instance local_destination

# Cloud storage transfers
vastai cloud copy --src cloud_service:path --dst instance_id:/path --transfer "Cloud To Instance"

Warning: Never copy to /root or / as destination — this corrupts SSH permissions.

5. Destroy When Done

# Destroy single instance (irreversible!)
vastai destroy instance ID

# Destroy multiple
vastai destroy instances ID1 ID2 ID3

Always destroy instances when done to stop storage charges.

Additional Features

For detailed documentation on these topics, read the corresponding reference file:

• Instance management (stop/start/reboot/recycle/update, labels, SSH, logs, execute): references/instances.md
• Search fields & query syntax: references/search-fields.md
• Volumes (persistent storage): references/volumes.md
• Autoscaling & Endpoints (serverless GPU): references/autoscaling.md
• Hosting (list your own machines): references/hosting.md
• Billing & Account (invoices, credits, teams): references/billing.md

Quick Reference

# Check account balance
vastai show user

# Get help on any command
vastai COMMAND --help

# Output raw JSON (for scripting)
vastai show instances --raw

# Show the equivalent curl command
vastai search offers 'gpu_name=RTX_4090' --curl

Common Patterns

Find the cheapest GPU for a given task:

vastai search offers 'gpu_ram>=24 reliability>0.98 inet_down>200' -o 'dph'

Deploy a training job:

# 1. Find an offer
vastai search offers 'gpu_name=A100_SXM4 num_gpus=1 reliability>0.99' -o 'dph'

# 2. Create instance with your training image
vastai create instance OFFER_ID --image your-registry/training:latest \
  --disk 100 --ssh --direct --onstart setup.sh

# 3. Monitor
vastai logs INSTANCE_ID --tail 50

# 4. Copy results back
vastai copy INSTANCE_ID:/workspace/results ./local_results

# 5. Destroy
vastai destroy instance INSTANCE_ID

Manage spot instances (cheaper but interruptible):

# Search for bid-type offers
vastai search offers 'gpu_name=RTX_4090 reliability>0.95' -b -o 'dph'

# Create with a max bid price
vastai create instance OFFER_ID --image pytorch/pytorch:latest --disk 50 --ssh --price 0.30

# Change bid later
vastai change bid INSTANCE_ID --price 0.35