vastai

vastai

Manage GPU instances, templates, volumes, serverless endpoints, SSH keys, and billing on Vast.ai.

Command is vastai (lowercase). Always use --raw for machine-readable JSON output.

Install

# PyPI (recommended)
pip install vastai

Quick start

vastai set api-key <YOUR_API_KEY>                   # Authenticate (one-time); Create API Key in account at https://console.vast.ai/manage-keys/
vastai show user                                    # Verify auth + check balance
vastai create ssh-key ~/.ssh/id_ed25519.pub         # Register SSH key (do BEFORE create)
vastai search offers 'gpu_name=RTX_4090 num_gpus=1 verified=true direct_port_count>=1 rentable=true' -o 'dlperf_usd-'
# Note the offer ID from the output
vastai create instance <OFFER_ID> --image pytorch/pytorch:@vastai-automatic-tag --disk 20 --ssh --direct
# Automatically grab appropriate image tag; Response:  {"success": true, "new_contract": <INSTANCE_ID>}
vastai show instance <INSTANCE_ID>                  # Poll until actual_status == "running" (see Instance status values below)
vastai ssh-url <INSTANCE_ID>                        # Get SSH connection string
vastai copy local:./data/ <INSTANCE_ID>:/workspace/ # Upload files
vastai destroy instance <INSTANCE_ID> -y             # Clean up (stops all billing; -y skips confirmation)

API key: https://console.vast.ai/manage-keys/

Global flags

Available on every command:

--api-key KEY    Override stored API key
--raw            Output machine-readable JSON (agents should always use this)
--full           Print full results (don't page with less)
--explain        Show underlying API calls (useful for debugging)
--curl           Show equivalent curl command
--no-color       Disable colored output
--url URL        Override server REST API URL
--retry RETRY    Set retry limit for API calls
--version        Show CLI version

Query syntax

Search commands accept filter expressions. Operators: =, !=, >, >=, <, <=, in, notin.

# Examples
'gpu_name=RTX_4090 num_gpus=1'           # Exact match + numeric
'gpu_ram>=48 reliability>0.95'           # Greater-than filters
'geolocation=EU dph_total<=2.0'          # Region + price cap

Common filter fields: num_gpus, gpu_name, gpu_ram, cpu_ram, disk_space, reliability, compute_cap, inet_up, inet_down, dph_total, geolocation, direct_port_count, verified, rentable

Common sort fields: score (default — overall value), dlperf_usd (DL perf per dollar), dph_total (price), num_gpus, reliability

Commands

Instances

vastai show instances                                    # List all your instances
vastai show instances-v1                                 # Paginated instances with full filter/sort/cols support
vastai show instances-v1 --status running loading        # Filter by status
vastai show instances-v1 --gpu-name 'RTX 4090'           # Filter by GPU
vastai show instances-v1 --label training                # Filter by label
vastai show instances-v1 --order-by start_date desc      # Sort by column
vastai show instances-v1 --cols id,status,gpu,dph        # Custom columns
vastai show instance <id>                                # Poll single instance (use for status checks)
vastai create instance <offer-id> --image pytorch/pytorch:2.4.0-cuda12.4-cudnn9-runtime --disk 20 --ssh --direct
# Response includes "new_contract": <id> — that is your instance ID
vastai launch instance --gpu-name RTX_4090 --num-gpus 1 --image pytorch/pytorch
vastai start instance <id>                               # Start stopped instance
vastai stop instance <id>                                # Stop (preserves disk, no GPU charges)
vastai reboot instance <id>                              # Stop + start
vastai destroy instance <id> -y                          # Delete permanently (irreversible; -y required for non-interactive use)
vastai destroy instances <id1> <id2> -y                  # Batch delete (-y skips confirmation prompt)
vastai label instance <id> --label "training-run-1"      # Tag instance
vastai update instance <id>                              # Recreate from updated template
vastai prepay instance <id>                              # Deposit credits into reserved instance
vastai recycle instance <id>                             # Destroy + recreate

Recommended Vast.ai images (use @vastai-automatic-tag to get the right tag for the machine automatically; browse pre-configured models at https://vast.ai/model-library):

<!-- Note: @vastai-automatic-tag is resolved server-side — CLI passes it unchanged -->

vastai/base-image:@vastai-automatic-tag          # Minimal Ubuntu base
vastai/pytorch:@vastai-automatic-tag             # PyTorch + CUDA
vastai/linux-desktop:@vastai-automatic-tag       # Linux desktop (VNC/RDP)

# vLLM — set model via env vars with huggingface model example
vastai create instance <id> --image vastai/vllm:@vastai-automatic-tag --disk 40 --ssh --direct \
  --env '-e MODEL_NAME=Qwen/Qwen2.5-3B-Instruct -e HF_TOKEN=hf_xxx'

# ComfyUI — set model checkpoint via env vars with huggingface model example
vastai create instance <id> --image vastai/comfy:@vastai-automatic-tag --disk 40 --ssh --direct \
  --env '-e CHECKPOINT_MODEL=black-forest-labs/FLUX.1-schnell -e HF_TOKEN=hf_xxx'

create instance flags:

• --image IMAGE — Docker image
• --disk DISK — Local disk in GB
• --ssh / --jupyter — Connection type
• --direct — Faster direct connections
• --label LABEL — Instance label
• --env ENV — Env vars and port mappings, e.g. '-e TZ=UTC -p 8080:8080'
• --onstart FILE — Path to a startup script file
• --onstart-cmd CMD — Startup script as inline string (for longer scripts use --onstart or gzip+base64 encode)
• --bid_price PRICE — Interruptible (spot) pricing in $/hr
• --template_hash HASH — Create from template
• --create-volume ID — Attach new volume
• --link-volume ID — Attach existing volume
• --cancel-unavail — Fail if no machine available (vs. create stopped)

Instance status values:

| actual_status | Meaning | |-----------------|---------| | null | Provisioning | | created | Instance created, not yet provisioned | | loading | Image downloading / container starting | | running | Active — GPU charges apply | | stopped | Halted — disk charges only | | frozen | Paused with memory — GPU charges apply | | exited | Container process exited unexpectedly | | rebooting | Restarting (transient) | | unknown | No recent heartbeat from host | | offline | Host disconnected from Vast servers |

Poll loop warning: If actual_status becomes exited, unknown, or offline it will never reach running. Always add a timeout and error branch — otherwise your script loops forever while disk charges accrue. Destroy and retry with a different offer.

Charges: Storage charges begin at creation. GPU charges begin when status reaches running.

Interruptible (spot) rentals

Interruptible (spot) instances are priced below on-demand instances, but can be interrupted at any time by another user with a lower bid. Note: search offers --type bid exposes min_bid, but create instance defaults to on-demand at dph_total unless you pass --bid_price <floor>. Always pass --bid_price after a --type bid search, otherwise the instance will be rented as an on-demand instance/price instead of as an interruptible.

When outbid, the instance moves to stopped (not destroyed) and storage charges continue. Resume by raising the bid via update instance --bid_price.

Search

vastai search offers                                     # Default: verified, on-demand, sorted by score
vastai search offers 'gpu_name=RTX_4090 num_gpus=1 verified=true direct_port_count>=1' -o 'dlperf_usd-'
vastai search offers 'num_gpus>=4 reliability>0.99' -o 'num_gpus-'
vastai search offers --type bid