vastai-install-auth

Vast.ai Install & Auth

Overview

Set up the Vast.ai CLI and REST API access for renting GPU compute instances. Vast.ai is a marketplace where individual hosts and data centers list GPU machines at prices significantly below hyperscaler providers.

Prerequisites

• Python 3.8+
• Vast.ai account at https://cloud.vast.ai
• Credit card or credits loaded for GPU rental

Instructions

Step 1: Install the CLI

set -euo pipefail
pip install vastai
vastai --version

Step 2: Get Your API Key

1. Log in at https://cloud.vast.ai
2. Navigate to Account > API Keys (or visit https://cloud.vast.ai/cli/)
3. Copy your API key (a long hexadecimal string)

Step 3: Configure Authentication

# Save API key to ~/.vast_api_key
vastai set api-key YOUR_API_KEY_HERE

# Verify authentication
vastai show user

For programmatic use, set the environment variable:

export VASTAI_API_KEY="your-api-key-here"
echo 'VASTAI_API_KEY=your-api-key' >> .env

Step 4: Verify with REST API

# Direct REST API call — base URL is cloud.vast.ai/api/v0
curl -s -H "Authorization: Bearer $VASTAI_API_KEY" \
  "https://cloud.vast.ai/api/v0/users/current" | jq '{id, username, balance}'

Step 5: Python Client Setup

# vastai_client.py
import os
import requests
from typing import Optional, Dict, Any, List

class VastClient:
    BASE_URL = "https://cloud.vast.ai/api/v0"

    def __init__(self, api_key: Optional[str] = None):
        self.api_key = api_key or os.environ.get("VASTAI_API_KEY")
        if not self.api_key:
            # Fall back to ~/.vast_api_key
            key_file = os.path.expanduser("~/.vast_api_key")
            if os.path.exists(key_file):
                self.api_key = open(key_file).read().strip()
        if not self.api_key:
            raise ValueError("No API key found. Run: vastai set api-key YOUR_KEY")

        self.session = requests.Session()
        self.session.headers.update({
            "Authorization": f"Bearer {self.api_key}",
            "Accept": "application/json",
        })

    def _request(self, method: str, endpoint: str, **kwargs) -> Dict[str, Any]:
        url = f"{self.BASE_URL}{endpoint}"
        resp = self.session.request(method, url, **kwargs)
        resp.raise_for_status()
        return resp.json()

    def search_offers(self, query: Dict[str, Any]) -> List[Dict]:
        return self._request("GET", "/bundles/", params={"q": str(query)})

    def create_instance(self, offer_id: int, image: str, disk_gb: float = 20,
                        onstart: str = "", env: Dict = None) -> Dict:
        body = {"client_id": "me", "image": image, "disk": disk_gb,
                "onstart": onstart, "env": env or {}}
        return self._request("PUT", f"/asks/{offer_id}/", json=body)

    def show_instances(self) -> List[Dict]:
        return self._request("GET", "/instances/")["instances"]

    def destroy_instance(self, instance_id: int) -> Dict:
        return self._request("DELETE", f"/instances/{instance_id}/")

# Quick verification
if __name__ == "__main__":
    client = VastClient()
    user = client._request("GET", "/users/current")
    print(f"Authenticated as: {user['username']}")
    print(f"Balance: ${user.get('balance', 0):.2f}")

Step 6: Verify Connection

# CLI verification
vastai show user
vastai search offers 'num_gpus=1 gpu_name=RTX_4090' --limit 3

# Python verification
python vastai_client.py

Output

• vastai CLI installed and authenticated
• API key saved to ~/.vast_api_key and/or environment variable
• Python client wrapper with search, create, show, destroy methods
• Successful authentication verification

Error Handling

Error	Cause	Solution
Invalid API key	Wrong or expired key	Regenerate at cloud.vast.ai/cli/
403 Forbidden	Insufficient balance	Add credits at cloud.vast.ai
Connection refused	Firewall blocking HTTPS	Allow outbound 443 to cloud.vast.ai
Module not found: vastai	pip install failed	Run pip install --upgrade vastai
~/.vast_api_key not found	CLI not configured	Run vastai set api-key YOUR_KEY

Resources

• Vast.ai CLI Documentation
• REST API Reference
• API Introduction
• GitHub: vast-cli

Next Steps

After successful auth, proceed to vastai-hello-world for your first GPU instance rental.

Examples

Quick CLI test: Run vastai search offers 'reliability > 0.99 num_gpus=1' --order 'dph_total' to find the cheapest reliable single-GPU offers. Verify your key works before writing any code.

REST API test: Use curl with your Bearer token to hit cloud.vast.ai/api/v0/users/current and confirm your username and balance are returned correctly.