Overview & Quickstart
We provide a python CLI (open-source) for a convenient interface to the rest API. You can use the --explain option with any CLI command and it will print out the underlying API calls.
You can install the latest stable PyPI release with:
Alternatively you can get the very latest version directly from github:
This repository contains the open source python command line interface for vast.ai. This CLI has all of the functionality of the vast.ai website GUI and uses the same underlying REST API. The CLI is self-contained in the single script file vast.py.
In order to authenticate most commands you will need to first login to the vast.ai website and get an api-key. Go to https://vast.ai/https://docs.vast.ai/cli/. Copy the command under the heading "Login / Set API Key" and run it. The command will be something like:
vastai set api-key xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
where the xxxx... is a unique api-key (a long hexadecimal number). Note that if the script is named "vast" in this command on the website and your installed script is named "vast.py" you will need to change the name of the script in the command you run. The set api-key command saves your api-key in a hidden file in your home directory. Do not share your api-keys with anyone as they authenticate commands from your account. Your default main key allows full access to all commands without limitations, but you can use the CLI to create additional keys with fine-grained access restrictions.
For the most up to date help, use 'vast.py --help'. You can then get a list of the available commands. Each command also typically has help documentation:
To see how the API works you can use it to find machines for rent.
There are many parameters that can be used to filter the results. The search command supports all of the filters and sort options that the website GUI uses. To find GPU instances with compute capability 8.0 or higher:
To find instances with a reliability score >= 0.99 and at least 4 gpus, ordering by num of gpus descending:
The output of this command at the time of this writing is
You create instances using the create instance command referencing an instance type ID returned from search offers. So to create an ssh direct instance of type 2459368 (using the ID returned from the search above for 4x 3090 on machine 4637) with the vastai/tensorflow image and 32 GB of disk storage:
Once an instance is created, it then must first pull the image if it is not cached. After the image is loaded the instance boots and transititons to the running state. You are charged for the resources you reserve. As storage is reserved at creation, storage charges begin when the instance is created and end only when it is destroyed. GPU charges begin when the instance transitions to the running state, and end when it is stopped or destroyed.
You can stop an instance to avoid GPU charges, converting it into a storage unit - storage is usually very cheap compared to GPU. Starting an existing instance takes only a second or less whereas creating a new instance can take much longer (to pull a large docker image), so maintaining a pool of stopped instances is useful for many applications.
You can call stop/destroy instance from inside the instance using a special autogenerated instance apikey, to avoid exposing your main apikey.
You can copy data from a stopped instance to a running instance, to/from cloud storage, or to/from another machine.
Once you are done with an instance make sure to destroy it to avoid ongoing storage charges.
