Python SDK Usage - Vast.ai Documentation – Affordable GPU Cloud Marketplace

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

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.

For a complete list of methods and their usage, please refer to Commands.

​PyPI Install

​Usage

​Resource Methods

​Getting help

​Example Usage

​Search offers

​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

PyPI Install

Usage

Resource Methods

Getting help

Example Usage

Search offers

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