CLI Hello World

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:

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

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

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)

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:

Status	Meaning
loading	Docker image is downloading
running	Ready 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.