repository·master·Indexed 42 days ago
https://github.com/vast-ai/vast-cliA toolset for managing GPU cloud resources on Vast.ai. It includes a command-line interface (CLI) for terminal users, a Python SDK for programmatic resource management, and a serverless client for high-performance model inference.
The OpenAPI specification source files (per-endpoint YAMLs and the build script) are no longer located in this repository. They have moved to the vast-ai/docs repository.
New location: api-reference/openapi/
Monitoring the actual_status of an instance is critical for managing costs and automation.
actual_status | Meaning |
|---|---|
null | Provisioning |
created | Instance created, not yet provisioned |
loading | Image downloading / container starting |
running | Active — GPU charges apply |
stopped | Halted — disk charges only |
frozen | Paused with memory — GPU charges apply |
exited | Container process exited unexpectedly |
rebooting | Restarting (transient) |
unknown | No recent heartbeat from host |
offline | Host disconnected from Vast servers |
Cost Warning: Storage charges begin at creation. GPU charges only begin once the status reaches running.
The Vast CLI installer attempts to modify your shell configuration (e.g., .bashrc, .zshrc) to add ~/.local/bin to your PATH and enable tab completion.
--no-modify-path flag during installation.<data-root>/env.sh. This ensures the managed CLI takes precedence over any pip-installed version of vastai on your PATH.The Vast CLI uses a curl | bash installer that follows the XDG Base Directory Specification. This ensures that the program, configuration, cache, and state are stored in standard, overridable locations.
On-disk layout:
~/.local/share/vastai/current/ (the single active virtual environment)~/.local/bin/vastai (for easy access from your PATH)~/.config/vastai~/.cache/vastai~/.local/state/vastai (used for persistent state like update throttle timestamps)Each root directory can be independently overridden using standard XDG_* environment variables.
The verification script performs two levels of checks:
vastai --help that lack a corresponding cli/reference/<command>.mdx file.VastAI class that lack a corresponding sdk/python/reference/<method>.mdx file.--check-params flag)--help or method parameters not mentioned in the MDX page.The script matches entities using these conversions:
kebab-case (e.g., show-instances) matches doc filenames like show-instances.mdx.snake_case (e.g., show_instances) matches doc filenames like show-instances.mdx.vastai show instances, the script expects the flattened kebab-case filename show-instances.mdx.Interruptible (spot) instances are cheaper but can be reclaimed by other users.
Critical Note: When using vast.search_offers(type='bid', ...) to find spot offers, you must pass a bid_price to vast.create_instance(...). If you omit bid_price, the SDK defaults to renting the instance at the on-demand price (dph_total) instead of the interruptible price.
If you are outbid, the instance moves to a stopped state (it is not destroyed) and storage charges continue. You can resume the instance by increasing your bid using vast.change_bid(id=..., price=...).
Follow these steps to get started with the CLI:
vastai set api-key YOUR_API_KEYvastai search offers --limit 3vastai set api-key YOUR_API_KEY
vastai search offers --limit 3To update the API documentation, follow these steps in the vast-ai/docs repository:
api-reference/openapi/yaml/<endpoint>.yaml.vast-ai/docs repository, run the build command to regenerate the main api-reference/openapi.yaml file.vast-ai/docs repository. CI will verify the spec, and Mintlify will deploy the changes to docs.vast.ai upon merging.For complete instructions, refer to the docs repo README.
npm run build-openapiFollow these steps to authenticate, find an offer, and launch a GPU instance:
OFFER_ID from the search results. Use --image pytorch/pytorch:@vastai-automatic-tag to automatically select the correct image tag.running, then retrieve the SSH URL.# Authenticate
vastai set api-key <YOUR_API_KEY>
# Verify auth + check balance
vastai show user
# Register SSH key (do BEFORE create)
vastai create ssh-key ~/.ssh/id_ed25519.pub
# Search for offers (e.g., RTX 4090)
vastai search offers 'gpu_name=RTX_4090 num_gpus=1 verified=true direct_port_count>=1 rentable=true' -o 'dlperf_usd-'
# Create instance (replace <OFFER_ID> with ID from search)
vastai create instance <OFFER_ID> --image pytorch/pytorch:@vastai-automatic-tag --disk 20 --ssh --direct
# Poll until actual_status == "running"
vastai show instance <INSTANCE_ID>
# Get SSH connection string
vastai ssh-url <INSTANCE_ID>
# Upload files
vastai copy local:./data/ <INSTANCE_ID>:/workspace/
# Clean up (stops all billing; -y skips confirmation)
vastai destroy instance <INSTANCE_ID> -yTo remove the managed installation, delete the program directory and the binary symlink. Note that your configuration (like API keys) and cache will be preserved.
Default Uninstall Command:
rm -rf "$XDG_DATA_HOME/vastai" ~/.local/bin/vastaiIf you used custom override variables during installation, ensure you use the corresponding paths for removal (e.g., if you set VASTAI_INSTALL_DIR, use that path instead of $XDG_DATA_HOME/vastai).
The SDK automatically looks for an API key in ~/.vast_api_key. You can obtain a key from the Vast.ai Console.
To provide a key explicitly in your code, pass it to the VastAI constructor.
from vastai import VastAI
# Uses ~/.vast_api_key
vast = VastAI()
# Explicitly providing the key
vast = VastAI(api_key="YOUR_API_KEY")vastai package. You can install it using pip. Note that pip install vastai-sdk is still supported and installs the same unified package containing both the SDK and the CLI.pip install vastai-sdk