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:
Or grab the latest version directly from GitHub:
wget https://raw.githubusercontent.com/vast-ai/vast-python/master/vast.py -O vast && chmod +x vast
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
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:
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-'
| Parameter | Meaning |
|---|
gpu_name=RTX_4090 | Filter to a specific GPU model |
num_gpus=1 | Exactly 1 GPU per instance |
verified=true | Only machines verified by Vast.ai (identity-checked hosts) |
direct_port_count>=1 | At least 1 directly accessible port (needed for direct SSH) |
rentable=true | Only machines currently available to rent |
-o 'dlperf_usd-' | Sort by DL performance per dollar, best value first |
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. Create an Instance
Rent the machine using create instance with the offer ID from step 4:
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
| Flag | Meaning |
|---|
--image | Docker image to launch |
--disk 20 | 20 GB of disk storage |
--onstart-cmd | Command to run when the instance boots |
--ssh --direct | Direct SSH access (lower latency than proxy SSH) |
{"success": true, "new_contract": 12345678}
new_contract value — this is your instance ID.
Storage charges begin at creation. GPU charges begin when the instance reaches the running state.
6. Wait Until Ready
The instance needs time to pull the Docker image and boot. Check the status with:
vastai show instance INSTANCE_ID
status field progresses through these states:
| Status | Meaning |
|---|
loading | Docker image is downloading |
running | Ready to use |
7. Connect via SSH
Once the instance is running, get the SSH connection details:
vastai ssh-url INSTANCE_ID
ssh root@SSH_HOST -p SSH_PORT
8. 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/
# 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/
9. 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
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 — See the CLI commands page for every available command.
- Use templates — Avoid repeating image and config parameters on every create call. See the templates guide for creating and managing templates.
