vastai

name

vastai

description

Manage Vast.ai GPU cloud instances via the vastai CLI. Use this skill whenever the user mentions Vast.ai, GPU rentals, cloud GPU instances, searching for GPU offers, creating/destroying instances, vast.ai billing, or any task involving the vastai command-line tool. Also trigger when the user wants to rent GPUs, find cheap GPUs, deploy Docker containers on remote GPUs, manage remote training infrastructure, or transfer data to/from cloud GPU machines. Even if the user just says "spin up a GPU" or "find me an A100", this skill likely applies.

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