Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.vast.ai/llms.txt

Use this file to discover all available pages before exploring further.

The Vast.ai CLI gives you command-line access to the entire platform, authentication, GPU search, instance lifecycle, templates, volumes, serverless endpoints, and more. Anything you can do in the web console, you can automate from your terminal. This guide walks through the core workflow: install the CLI, authenticate, search for a GPU, rent it, wait for it to boot, connect to it, copy data, and clean up. By the end you’ll understand the commands needed to manage instances without touching the web console.

​
Prerequisites

  • A Vast.ai account with credit (~$0.01-0.05, depending on test instance run time)
  • Python 3 installed

​
1. Install the CLI

Install from PyPI: 
pip install vastai
Or grab the latest version directly from GitHub: 
wget https://raw.githubusercontent.com/vast-ai/vast-cli/master/vast.py -O vastai && chmod +x vastai
Verify the installation: 
vastai --help

​
2. Set Your API Key

Generate an API key from the Keys page by clicking +New. Copy the key, you’ll only see it once. Save it to the CLI: 
vastai set api-key YOUR_API_KEY_HERE
This stores your key in a config file in your home directory. Do not share your API keys with anyone.
The console creates a full-access key by default. You can also create scoped keys with limited permissions using vastai create api-key, useful for CI/CD or shared tooling. See the permissions documentation for details.

​
3. Verify Authentication

Confirm your key works by fetching your account info: 
vastai show user
This returns your user ID, email, balance, and SSH key. If you see an authentication error, double-check your API key.

​
4. Search for GPUs

Find available machines using search offers. This query returns on-demand RTX 4090s on verified machines with direct port access, sorted by deep learning performance per dollar: 
vastai search offers 'gpu_name=RTX_4090 num_gpus=1 verified=true direct_port_count>=1 rentable=true' -o 'dlperf_usd-'
Each parameter in the query controls a different filter:
ParameterMeaning
gpu_name=RTX_4090Filter to a specific GPU model
num_gpus=1Exactly 1 GPU per instance
verified=trueOnly machines verified by Vast.ai (identity-checked hosts)
direct_port_count>=1At least 1 directly accessible port (needed for direct SSH)
rentable=trueOnly machines currently available to rent
-o 'dlperf_usd-'Sort by DL performance per dollar, best value first
Note the ID of the offer you want, you’ll use it in the next step. If no offers are returned, try relaxing your filters (e.g. a different GPU model or removing direct_port_count).
Use vastai search offers --help for the full list of filter fields and options, or see the CLI commands reference.

​
5. Register Your SSH Key

Do this before creating an instance. Your SSH public key must be registered on your account, it is applied at container creation time. 
vastai create ssh-key ~/.ssh/id_ed25519.pub
If you don’t have a key yet, omit the argument and the CLI will generate one: 
vastai create ssh-key
Your key persists on your account, you only need to do this once per key. If you forgot and already created an instance, use the SSH key button on the instance card in the console to add a key without recreating.

​
6. Create an Instance

Rent the machine using create instance with the offer ID from step 4 (search): 
vastai create instance OFFER_ID --image pytorch/pytorch:2.4.0-cuda12.4-cudnn9-runtime --disk 20 --onstart-cmd "echo hello && nvidia-smi" --ssh --direct
FlagMeaning
--imageDocker image to launch
--disk 2020 GB of disk storage
--onstart-cmdCommand to run when the instance boots
--ssh --directDirect SSH access (lower latency than proxy SSH)
The output includes the new instance ID: 
{"success": true, "new_contract": 12345678}
Save the new_contract value, this is your instance ID.
Storage charges begin at creation. GPU charges begin when the instance reaches the running state.
--onstart-cmd is limited to 16KB. For longer scripts, gzip and base64 encode them, see the Template Settings page for the workaround.

​
7. Wait Until Ready

The instance needs time to pull the Docker image and boot. Check the status with: 
vastai show instance INSTANCE_ID
The status field progresses through these states:
StatusMeaning
loadingDocker image is downloading
runningReady to use
Check every 10-30 seconds. Boot time is typically 1-5 minutes depending on the Docker image size.
Always handle non-happy-path statuses in your poll loop. If status becomes exited (container crashed), unknown (no heartbeat from host), or offline (host disconnected), it will never reach running. Without a timeout or error check, your script will loop forever while the instance continues accruing disk charges. Destroy the instance and retry with a different offer if you see these states.

​
8. Connect via SSH

Once the instance is running, get the SSH connection details: 
vastai ssh-url INSTANCE_ID
Then connect: 
ssh root@SSH_HOST -p SSH_PORT

​
9. Copy Data

Use vastai copy to transfer files between your local machine and the instance: 
# Upload to instance
vastai copy local:./data/ INSTANCE_ID:/workspace/data/

# Download from instance
vastai copy INSTANCE_ID:/workspace/results/ local:./results/
You can also copy between instances or to/from cloud storage: 
# Instance to instance
vastai copy INSTANCE_A:/workspace/ INSTANCE_B:/workspace/

# Cloud storage (requires a configured cloud connection)
vastai copy s3.CONNECTION_ID:/bucket/data/ INSTANCE_ID:/workspace/
For cloud storage syncing and instance-to-instance transfers, see the data movement guide.

​
10. Clean Up

When you’re done, destroy the instance to stop all billing. Alternatively, to pause an instance temporarily instead of destroying it, you can stop it. Stopping halts compute billing but disk storage charges continue. Destroy (removes everything): 
vastai destroy instance INSTANCE_ID
Stop (pauses compute, disk charges continue): 
vastai stop instance INSTANCE_ID

​
Next Steps

You’ve now completed the full instance lifecycle through the CLI: installation, authentication, search, creation, polling, data transfer, and teardown. From here:
  • SSH setup, See the SSH guide for key configuration and advanced connection options.
  • Full command reference, Every CLI command is documented under the Reference tab, grouped by domain (Accounts, Instances, Search, Serverless, and more).
  • Use templates, Avoid repeating image and config parameters on every create call. See the templates guide for creating and managing templates.