CLI

Python SDK Usage

19min

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
pip install vastai-sdk
﻿
Usage
Import the package:
Text
from vastai_sdk import VastAI
from vastai_sdk import VastAI
﻿
Construct a Vast client with your API key:
Text
vast_sdk = VastAI(api_key='YOUR_API_KEY')
vast_sdk = VastAI(api_key='YOUR_API_KEY')
﻿
Resource Methods
Most useful available VastAI resources are implemented. Commands for Vast CLI usage should have equivalent class methods on your Vast client object. Most IDEs should show type hints and relevant class methods and their expected arguments for VastAI, due to the implementation of our base class.
For example, the CLI command vastai show instances has the equivalent, vast_sdk.show_instances().
Text
from vastai_sdk import VastAI

vast_sdk = VastAI(api_key='YOUR_API_KEY')

output = vast_sdk.show_instances()
print(output)
from vastai_sdk import VastAI

vast_sdk = VastAI(api_key='YOUR_API_KEY')

output = vast_sdk.show_instances()
print(output)
﻿
Example Usage
Here are some example usages of our Python SDK class VastAI:
Starting and Stopping Instances
Text
from vastai_sdk import VastAI

vast_sdk = VastAI(api_key='YOUR_API_KEY')

vast_sdk.start_instance(ID=12345678)

vast_sdk.stop_instance(ID=12345678)
from vastai_sdk import VastAI

vast_sdk = VastAI(api_key='YOUR_API_KEY')

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
from vastai_sdk import VastAI

vast_sdk = VastAI(api_key='YOUR_API_KEY')

vast_sdk.launch_instance(num_gpus="1", gpu_name="RTX_3090", image="pytorch/pytorch")
from vastai_sdk import VastAI

vast_sdk = VastAI(api_key='YOUR_API_KEY')

vast_sdk.launch_instance(num_gpus="1", gpu_name="RTX_3090", image="pytorch/pytorch")
﻿
Copying Files Between Instances
Text
from vastai_sdk import VastAI

vast_sdk = VastAI(api_key='YOUR_API_KEY')

vast_sdk.copy(src='source_path', dst='destination_path', identity='identity_file')
from vastai_sdk import VastAI

vast_sdk = VastAI(api_key='YOUR_API_KEY')

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
from vastai_sdk import VastAI

vast_sdk = VastAI(api_key='YOUR_API_KEY')

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)
from vastai_sdk import VastAI

vast_sdk = VastAI(api_key='YOUR_API_KEY')

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
Method
Description
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
Method
Description
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
Method
Description
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
Method
Description
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
Method
Description
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
Method
Description
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
Method
Description
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
Method
Description
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
Method
Description
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.
Please refer to the VastAI Python SDK API Reference for detailed information on all available methods and their usage.

Method	Description
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.

Method	Description
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.

Method	Description
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.

Method	Description
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.

Method	Description
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.

Method	Description
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.

Method	Description
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.

Method	Description
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.

Method	Description
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.

Permissions-and-authorization