Skip to main content
We provide a PyPI package, vastai-sdk, for convenient Python usage.

​
PyPI Install

You can install the latest stable PyPI release with:
Text
pip install vastai-sdk

​
Usage

Import the package:
Text
from vastai_sdk import VastAI
Construct a Vast client with your API key:
Text
vast_sdk = VastAI(api_key='YOUR_API_KEY')

​
Resource Methods

Most CLI commands have direct equivalents in the Python SDK. Your VastAI client exposes the same functionality through class methods and IDE’s will surface type hints and arguments automatically. For example, the CLI command vastai show instances has the equivalent, vast_sdk.show_instances().
Text
output = vast_sdk.show_instances()
print(output)

​
Getting help

Use the built-in help() method to view detailed documentation for any SDK method. This will show you the method’s description, parameters, query syntax, and usage examples.
Text
help(vast_sdk.search_offers)

​
Example Usage

Here are some example usages of our Python SDK class VastAI:

​
Search offers

Find an available RTX 3090 GPU
Text
vast_sdk.search_offers(query='gpu_name=RTX_5090 rented=False rentable=True)

​
Starting and Stopping Instances

Text
vast_sdk.start_instance(ID=12345678)

vast_sdk.stop_instance(ID=12345678)

​
Creating a New Instance

Create a new instance based on given parameters (performs search offers + create instance).
Text
vast_sdk.launch_instance(num_gpus="1", gpu_name="RTX_3090", image="pytorch/pytorch")

​
Copying Files Between Instances

Text
vast_sdk.copy(src='source_path', dst='destination_path', identity='identity_file')

​
Managing SSH Keys

Create a new SSH key, show all SSH keys, and delete an SSH key.
Text
vast_sdk.create_ssh_key(ssh_key='your_ssh_key')

ssh_keys = vast_sdk.show_ssh_keys()
print(ssh_keys)

vast_sdk.delete_ssh_key(ID=123456)

​
Contribution and Issue Reporting

This code repository is open source and can be rapidly changing at times. If you find a potential bug, please open an issue on GitHub. If you wish to contribute to improving this code and its functionality, feel welcome to open a PR with any improvements on our GitHub repository.

​
Available Methods

Below is a list of the available methods you can call on the VastAI client. These methods are categorized for better readability.

​
Instance Management

MethodDescription
start_instance(ID: int)Start an instance.
stop_instance(ID: int)Stop an instance.
reboot_instance(ID: int)Reboot an instance.
destroy_instance(id: int)Destroy an instance.
destroy_instances(ids: List[int])Destroy multiple instances.
recycle_instance(ID: int)Recycle an instance.
label_instance(id: int, label: str)Label an instance.
show_instance(id: int)Show details of an instance.
show_instances(quiet: bool = False)Show all instances.
logs(INSTANCE_ID: int, tail: Optional[str] = None)Retrieve logs for an instance.
execute(ID: int, COMMAND: str)Execute a command on an instance.
launch_instance(...)Launch a new instance with various parameters.

​
SSH Key Management

MethodDescription
create_ssh_key(ssh_key: str)Create a new SSH key.
delete_ssh_key(ID: int)Delete an SSH key.
show_ssh_keys()Show all SSH keys.
attach_ssh(instance_id: int, ssh_key: str)Attach an SSH key to an instance.
detach_ssh(instance_id: int, ssh_key_id: str)Detach an SSH key from an instance.

​
API Key Management

MethodDescription
create_api_key(name: Optional[str] = None, ...)Create a new API key.
delete_api_key(ID: int)Delete an API key.
reset_api_key()Reset the API key.
show_api_key(id: int)Show details of an API key.
show_api_keys()Show all API keys.
set_api_key(new_api_key: str)Set a new API key.

​
Autoscaler Management

MethodDescription
create_autoscaler(test_workers: int = 3, ...)Create a new autoscaler.
update_autoscaler(ID: int, min_load: Optional[float] = None, ...)Update an autoscaler.
delete_autoscaler(ID: int)Delete an autoscaler.
show_autoscalers()Show all autoscalers.

​
Endpoint Management

MethodDescription
create_endpoint(min_load: float = 0.0, ...)Create a new endpoint.
update_endpoint(ID: int, min_load: Optional[float] = None, ...)Update an endpoint.
delete_endpoint(ID: int)Delete an endpoint.
show_endpoints()Show all endpoints.

​
File Management

MethodDescription
copy(src: str, dst: str, identity: Optional[str] = None)Copy files between instances.
cloud_copy(src: Optional[str] = None, dst: Optional[str] = "/workspace", ...)Copy files between cloud and instance.
cancel_copy(dst: str)Cancel a file copy operation.
cancel_sync(dst: str)Cancel a file sync operation.
scp_url(id: int)Get the SCP URL for transferring files to/from an instance.

​
Team Management

MethodDescription
create_team(team_name: Optional[str] = None)Create a new team.
destroy_team()Destroy a team.
invite_team_member(email: Optional[str] = None, role: Optional[str] = None)Invite a new member to the team.
remove_team_member(ID: int)Remove a member from the team.
create_team_role(name: Optional[str] = None, permissions: Optional[str] = None)Create a new team role.
remove_team_role(NAME: str)Remove a role from the team.
update_team_role(ID: int, name: Optional[str] = None, permissions: Optional[str] = None)Update details of a team role.
show_team_members()Show all team members.
show_team_role(NAME: str)Show details of a specific team role.
show_team_roles()Show all team roles.

​
Host Management

MethodDescription
cleanup_machine(ID: int)Clean up a machine’s configuration and resources.
list_machine(ID: int, price_gpu: Optional[float] = None, price_disk: Optional[float] = None, price_inetu: Optional[float] = None, price_inetd: Optional[float] = None, discount_rate: Optional[float] = None, min_chunk: Optional[int] = None, end_date: Optional[str] = None)List details of a single machine with optional pricing and configuration parameters.
list_machines(IDs: List[int], price_gpu: Optional[float] = None, price_disk: Optional[float] = None, price_inetu: Optional[float] = None, price_inetd: Optional[float] = None, discount_rate: Optional[float] = None, min_chunk: Optional[int] = None, end_date: Optional[str] = None)List details of multiple machines with optional pricing and configuration parameters.
remove_defjob(id: int)Remove the default job from a machine.
set_defjob(id: int, price_gpu: Optional[float] = None, price_inetu: Optional[float] = None, price_inetd: Optional[float] = None, image: Optional[str] = None, args: Optional[List[str]] = None)Set a default job on a machine with specified parameters.
set_min_bid(id: int, price: Optional[float] = None)Set the minimum bid price for a machine.
schedule_maint(id: int, sdate: Optional[float] = None, duration: Optional[float] = None)Schedule maintenance for a machine.
cancel_maint(id: int)Cancel scheduled maintenance for a machine.
unlist_machine(id: int)Unlist a machine from being available for new jobs.
show_machines(quiet: bool = False, filter: Optional[str] = None)Retrieve and display a list of machines based on specified criteria.

​
Other Methods

MethodDescription
get_gpu_names()Returns a set of GPU names available on Vast.ai.
show_connections()Show all connections.
show_deposit(ID: int)Show deposit details for an instance.
show_earnings(quiet: bool = False, start_date: Optional[str] = None, end_date: Optional[str] = None, machine_id: Optional[int] = None)Show earnings information.
show_invoices(quiet: bool = False, start_date: Optional[str] = None, end_date: Optional[str] = None, ...)Show invoice details.
show_ipaddrs()Show IP addresses.
show_user(quiet: bool = False)Show user details.
show_subaccounts(quiet: bool = False)Show all subaccounts of the current user.
transfer_credit(recipient: str, amount: float)Transfer credit to another account.
update_ssh_key(id: int, ssh_key: str)Update an SSH key.
generate_pdf_invoices(quiet: bool = False, start_date: Optional[str] = None, end_date: Optional[str] = None, only_charges: bool = False, only_credits: bool = False)Generate PDF invoices based on filters.
For a complete list of methods and their usage, please refer to Commands.