Python SDK Usage

PyPI Install

Usage

Resource Methods

Example Usage

Starting and Stopping Instances

Creating a New Instance

Copying Files Between Instances

Managing SSH Keys

Contribution and Issue Reporting

Available Methods

Instance Management

SSH Key Management

API Key Management

Autoscaler Management

Endpoint Management

File Management

Team Management

Host Management

Other Methods

Guides Instances Serverless API Discord

Docs - CLI

Python SDK Usage

We provide a PyPI package, vastai, for convenient Python usage.

PyPI Install #

You can install the latest stable PyPI release with:

pip install vastai

Usage #

Import the package:

from vastai import VastAI

Construct a Vast client with 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().

from vastai 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 #

from vastai 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).

from vastai 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 #

from vastai 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.

from vastai 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.