Introduction

SpotWarp is a lightweight, 100% local Python autopilot daemon that runs continuous background backups of your workspace the whole time your Spot instance (Vast.ai, RunPod) is running — so an eviction never costs you training progress, not just downtime.

By exploiting Spot pricing, you can save up to 70% on cloud compute bills. When an eviction fires, SpotWarp races several replacement candidates on Vast.ai concurrently (typically under a minute), restores your already-backed-up workspace, and resumes your training scripts automatically. If Vast has no matching candidate at that moment, it bridges to RunPod instead — spot pricing first, on-demand if needed — then migrates back to Vast.ai on its own once cheaper capacity reopens, so the bridge cloud is never a permanent, more expensive home.

Rent Your GPU

SpotWarp does not rent, resell, or hold any GPU inventory — we never broker compute. You rent directly from Vast.ai (and optionally RunPod), and SpotWarp is the local daemon that watches and protects whatever you've rented there.

1. Sign up directly at vast.ai if you don't already have an account, and generate an API key from your account settings.
2. Optionally, do the same at runpod.io — this enables the cross-cloud bridge, which covers you if Vast.ai has no matching GPU in stock at the moment of an eviction.
3. Rent your GPU instance yourself, directly on Vast.ai's console (choose your GPU model, spot pricing) — this step happens entirely on their platform, not ours.

Installation

Install SpotWarp on your local workstation or orchestrator. Python is completely optional — our standalone C-binaries run with zero external dependencies.

Option A: Universal 1-Liner (Recommended)

Copy# Linux / macOS
curl -fsSL https://gpu-action.com/install.sh | bash

# Windows PowerShell
irm https://gpu-action.com/install.ps1 | iex

Option B: Standalone C-Binaries (Direct Download)

Pre-compiled standalone binaries with embedded C-engine, published on GitHub Releases with SHA256 checksums you can verify:

• Linux x86_64: spotwarp-linux-x86_64 (13MB, glibc 2.31+)
• macOS: spotwarp-darwin-arm64 (6MB, Apple Silicon)
• Windows: spotwarp-windows-x64.zip (6MB) — the same released Windows binary, served from this site as a ZIP because browsers and antivirus commonly block a bare .exe download. Extract it and you get spotwarp.exe, byte-identical to spotwarp-windows-x64.exe on the release page.

Option C: PyPI Package (For Docker / Python Workflows)

Copypip install --upgrade spotwarp

Windows Backup Transport

SpotWarp uses rsync for high-speed incremental workspace backups when natively available (Linux/macOS). On Windows, it automatically uses scp (bundled with Windows' native OpenSSH client) — zero extra setup required.

Quick Setup Wizard

Run the one-time interactive setup wizard to save your keys locally to ~/.spotwarp/config.json:

Copyspotwarp init

The wizard will prompt you for your SpotWarp License Key, Vast.ai API Key, and optional RunPod API Key. Once configured, you never need to export environment variables or pass keys via CLI again.

Alternative: Manual Environment Variables

If you prefer not to use a local config file (e.g. inside ephemeral CI/CD pipelines), you can still export keys via standard environment variables:

Copy# Linux / macOS
export VAST_API_KEY="your_vast_api_key"
export RUNPOD_API_KEY="your_runpod_api_key"

# Windows PowerShell
$env:VAST_API_KEY="your_vast_api_key"
$env:RUNPOD_API_KEY="your_runpod_api_key"

Start Guard Daemon

Once configured, start protecting your workloads with a single command:

Option A: Live Console Mode

Copyspotwarp start

Option B: 24/7 Background Daemon Mode

Run SpotWarp in detached background mode so you can safely close your terminal window:

Copyspotwarp start -d

Daemon Management Commands

Copyspotwarp status   # Check if background guard is alive
spotwarp stop     # Gracefully stop the background guard
spotwarp config   # View your current local configuration

Custom Backup Location

By default, workspace backups are written to ./backups/<instance_id>/. To use a different drive, pass --backup-dir:

Copyspotwarp start --backup-dir "D:\SpotwarpBackups"

Stateful Auto-Resume

You can configure the daemon to automatically resume PyTorch/TensorFlow training scripts on the replacement node pointing to your synced checkpoints:

Copyspotwarp start --license-key YOUR_LICENSE_KEY --resume-cmd "python /workspace/train.py --resume"

When eviction occurs, SpotWarp syncs the final state of your workspace directory, boots the cheapest matching host, restores all cached weights, and executes the --resume-cmd in the background via remote SSH/nohup.

Security & Sandbox

All API calls and status heartbeat transmissions are encrypted in transit via HTTPS using AES-256 tokens.

The CLI daemon runs strictly in user space on your local computer. It does not require root/sudo access, and can run inside isolated docker containers, making it completely safe for enterprise production environments.

Troubleshooting

"License verification endpoint returned status 401"

Your --license-key value doesn't match an active license. This is almost always a copy-paste issue — a prefix like TRIAL_ got dropped, or two keys got concatenated together. Copy the full key directly from your confirmation email and paste it in one piece. Still stuck? Email [email protected] and we'll look it up.

"Monitoring 0 instances"

This is expected if you haven't rented a GPU on Vast.ai or RunPod yet — see Rent Your GPU. If you do have an instance running and it's still showing 0, double-check that your API key (VAST_API_KEY or RUNPOD_API_KEY) is set in the same terminal window you ran spotwarp start in — environment variables don't carry over to a new window.

"[Backup] sync attempt failed (exit 255): Connection closed"

A freshly rented instance can take a minute or so after it shows as "running" on Vast.ai before its SSH server is actually ready to accept connections. A single failed sync attempt right after an instance is first detected is expected — SpotWarp retries automatically every 30 seconds, and a one-off failure like this is not logged to the console (only written to that instance's sync_errors.log) so it doesn't look like an error when it isn't one.

If the same instance fails 3 or more times in a row, SpotWarp prints an explicit warning to the console — that's the signal something is actually wrong (not just still booting) and worth investigating: check that the instance is reachable via ssh -p <port> root@<host> yourself, and that /workspace/ exists inside the container.

Where are my backups?

Locally, in .\backups\<instance_id>\ relative to wherever you ran spotwarp start from — unless you set --backup-dir or SPOTWARP_BACKUP_DIR (see Start Guard Daemon), in which case it's there instead. Nothing is ever uploaded off your machine.

Still stuck?

Email [email protected] with your license key and the console output around the issue — we read every message.