VastAI.launch_instance

Launch the best matching instance based on GPU/image criteria.

Searches for available offers and creates an instance from the top result.

Signature

VastAI.launch_instance(
    gpu_name: str,
    num_gpus: str,
    image: str,
    region: str = None,
    disk: float = 16.0,
    limit: int = 3,
    order: str = "score-",
    login: str = None,
    label: str = None,
    onstart: str = None,
    onstart_cmd: str = None,
    entrypoint: str = None,
    ssh: bool = False,
    jupyter: bool = False,
    direct: bool = False,
    jupyter_dir: str = None,
    jupyter_lab: bool = False,
    lang_utf8: bool = False,
    python_utf8: bool = False,
    extra: str = None,
    env: str = None,
    args: list = None,
    force: bool = False,
    cancel_unavail: bool = False,
    template_hash: str = None,
    explain: bool = False,
    raw: bool = False
) -> str

Parameters

gpu_name · str · required

Name of the GPU model (replace spaces with underscores, e.g. “RTX_4090”).

num_gpus · str · required

Number of GPUs required (choices: 1, 2, 4, 8, 12, 14).

image · str · required

Docker image name to use for the instance.

region · str

Geographical region filter for the instance location.

disk · float · default: "16.0"

Disk space to allocate in GB.

limit · int · default: "3"

Maximum number of offers to consider when selecting the best match.

order · str · default: "\"score-\""

Sort order for offers; append ’-’ to sort descending (e.g. “score-”).

login · str

Docker login credentials for private registry authentication.

label · str

Label to attach to the instance.

onstart · str

Filename of an onstart script to run on instance start.

onstart_cmd · str

Shell command to run on instance start.

entrypoint · str

Override the Docker image entrypoint.

ssh · bool · default: "False"

Enable SSH access to the instance.

jupyter · bool · default: "False"

Enable Jupyter notebook server.

direct · bool · default: "False"

Enable direct (peer-to-peer) connections.

jupyter_dir · str

Directory to serve Jupyter from.

jupyter_lab · bool · default: "False"

Enable JupyterLab instead of classic Jupyter.

lang_utf8 · bool · default: "False"

Set system language encoding to UTF-8.

python_utf8 · bool · default: "False"

Set Python I/O encoding to UTF-8.

extra · str

Extra Docker run arguments passed verbatim.

env · str

Environment variables to set (formatted as Docker -e flags).

args · list

Additional positional arguments.

force · bool · default: "False"

Skip sanity checks when creating from an existing instance.

cancel_unavail · bool · default: "False"

Return an error if scheduling fails rather than creating a stopped instance.

template_hash · str

Hash of an instance template to use for configuration.

explain · bool · default: "False"

Print verbose explanations of API calls made.

raw · bool · default: "False"

Return raw JSON responses.

Returns

str — Result from the API call.

Example

from vastai import VastAI

client = VastAI(api_key="YOUR_API_KEY")
result = client.launch_instance(gpu_name="...", num_gpus="...", image="...")
print(result)