Vast.ai Node.js SDK

A Node.js client for the Vast.ai API that allows you to programmatically rent and manage GPU instances for machine learning and AI workloads.

Features

• 🔎 Search for available GPU instances based on various criteria
• 🚀 Create, start, stop, and delete instances
• 📋 List running instances and available images
• 👤 Access user account information
• 🔄 Automatic retries for failed requests
• ⏱️ Rate limiting to prevent API throttling
• 📊 Detailed logging for debugging

Installation

npm install @sschepis/vast-node

Quick Start

import { VastClient } from '@sschepis/vast-node';

// Initialize with your API key
const client = new VastClient('your-api-key');

// Search for available machines
async function findCheapestGPUs() {
  const offers = await client.searchOffers({
    num_gpus: 1,
    cuda_max_good: 11.7,
    order: 'dph_total+'  // Sort by price (cheapest first)
  });
  
  console.log(`Found ${offers.length} available machines`);
  
  // Print details of the top 3 cheapest offers
  offers.slice(0, 3).forEach((offer, i) => {
    console.log(`\n[${i+1}] Machine ID: ${offer.id}`);
    console.log(`   GPU: ${offer.num_gpus}x ${offer.gpu_name}`);
    console.log(`   Price: $${offer.dph_total.toFixed(4)}/hour`);
    console.log(`   Location: ${offer.datacenter?.geolocation || 'Unknown'}`);
  });
}

// Run the example
findCheapestGPUs().catch(console.error);

Getting your API Key

1. Log in to your Vast.ai account
2. Navigate to your user settings
3. Copy your API key from the API section

Basic Usage

Initializing the Client

import { VastClient } from '@sschepis/vast-node';

// Initialize with API key
const client = new VastClient('your-api-key');

// Or initialize without API key and set it later
const client = new VastClient();
client.setApiKey('your-api-key');

Searching for Available Machines

// Search with filters
const offers = await client.searchOffers({
  num_gpus: 2,                // Number of GPUs
  cuda_max_good: 11.7,        // CUDA version
  order: 'dph_total+',        // Sort by hourly price (cheapest first)
  disk_space: 30,             // Minimum disk space in GB
  inet_down: 100,             // Minimum download speed in Mbps
  inet_up: 100                // Minimum upload speed in Mbps
});

// Get details of a specific machine
const machineDetails = await client.getOffer(12345);

Managing Instances

// List all your instances
const instances = await client.listInstances();

// List only running instances
const runningInstances = await client.listInstances({ q: 'running' });

// Get details of a specific instance
const instanceDetails = await client.getInstance(67890);

// Create a new instance
const newInstance = await client.createInstance({
  image: 'pytorch/pytorch:2.0.0-cuda11.7-cudnn8-runtime',
  machineId: 12345,
  diskSpace: 20,
  jupyterLab: true,
  env: {
    JUPYTER_PASSWORD: 'vastai'
  }
});

// Start, stop, or delete an instance
await client.startInstance(67890);
await client.stopInstance(67890);
await client.deleteInstance(67890);

Listing Available Images

// Get all available Docker images
const images = await client.listImages();

Getting User Information

// Get your user account details
const userInfo = await client.getUserInfo();
console.log(`Account Balance: $${userInfo.balance.toFixed(2)}`);

Advanced Usage

For more advanced usage and detailed API documentation, see the API Reference and Getting Started Guide.

Development

Building the Project

git clone https://github.com/sschepis/vast-node.git
cd vast-node
npm install
npm run build

Running Tests

npm test

Running Examples

# Set your API key
export VAST_API_KEY=your-api-key-here

# Run the basic example
npx ts-node examples/basic-usage.ts

# Run diagnostics
npx ts-node examples/debug-sdk.ts

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT © Sebastian Schepis

Acknowledgments

• Vast.ai for providing the original API and Python SDK
• The vast-node SDK team for this Node.js implementation