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.
set -euo pipefail
pip install vastai
vastai --version
# 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
# 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}'
# 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}")
# CLI verification
vastai show user
vastai search offers 'num_gpus=1 gpu_name=RTX_4090' --limit 3
# Python verification
python vastai_client.py
vastai CLI installed and authenticated~/.vast_api_key and/or environment variable| 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 |
After successful auth, proceed to vastai-hello-world for your first GPU instance rental.
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.