> ## Documentation Index
> Fetch the complete documentation index at: https://vastai-80aa3a82-auto-cli-sdk-preview-pr-398.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# vastai launch instance

Launch the top instance from the search offers based on the given parameters

## Usage

```bash theme={null}
vastai launch instance [--help] [--api-key API_KEY] <gpu_name> <num_gpus> <image> [geolocation] [disk_space]
```

## Options

<ParamField path="--gpu-name" type="string">
  Name of the GPU model, replace spaces with underscores
  Allowed values: 970, A10, A100\_PCIE, A100\_SXM4, A40, A800\_PCIE, B200, B300, GB10, GTX\_1050, GTX\_1050\_Ti, GTX\_1060, GTX\_1070, GTX\_1070\_Ti, GTX\_1080, GTX\_1080\_Ti, GTX\_1650, GTX\_1650\_S, GTX\_1660, GTX\_1660\_S, GTX\_1660\_Ti, GTX\_TITAN\_X, H100\_NVL, H100\_PCIE, H100\_SXM, H200, H200\_NVL, InstinctMI100, L4, L40, L40S, Q\_RTX\_4000, Q\_RTX\_6000, Q\_RTX\_8000, Quadro\_P4000, Quadro\_P5000, RTX\_2000Ada, RTX\_2060, RTX\_2060S, RTX\_2070, RTX\_2070S, RTX\_2080, RTX\_2080S, RTX\_2080\_Ti, RTX\_3050, RTX\_3060, RTX\_3060\_laptop, RTX\_3060\_Ti, RTX\_3070, RTX\_3070\_laptop, RTX\_3070\_Ti, RTX\_3080, RTX\_3080\_Ti, RTX\_3090, RTX\_3090\_Ti, RTX\_4000Ada, RTX\_4060, RTX\_4060\_laptop, RTX\_4060\_Ti, RTX\_4070, RTX\_4070S, RTX\_4070S\_Ti, RTX\_4070\_Ti, RTX\_4080, RTX\_4080S, RTX\_4090, RTX\_4090D, RTX\_4500Ada, RTX\_5000Ada, RTX\_5060, RTX\_5060\_laptop, RTX\_5060\_Ti, RTX\_5070, RTX\_5070\_Ti, RTX\_5080, RTX\_5090, RTX\_5880Ada, RTX\_6000Ada, RTX\_A2000, RTX\_A4000, RTX\_A4500, RTX\_A5000, RTX\_A6000, RTX\_PRO\_4000, RTX\_PRO\_4500, RTX\_PRO\_5000, RTX\_PRO\_6000\_S, RTX\_PRO\_6000\_WS, Tesla\_P100, Tesla\_P4, Tesla\_P40, Tesla\_T4, Tesla\_V100, Titan\_RTX, Titan\_V, Titan\_Xp
</ParamField>

<ParamField path="--num-gpus" type="string">
  Number of GPUs required
  Allowed values: 1, 2, 4, 8, 12, 14
</ParamField>

<ParamField path="--region" type="string">
  Geographical location of the instance
</ParamField>

<ParamField path="--image" type="string">
  Name of the image to use for instance
</ParamField>

<ParamField path="--disk" type="number" default="16.0">
  Disk space required in GB
</ParamField>

<ParamField path="--limit" type="integer" default="3" />

<ParamField path="--order" type="string" default="score-">
  Comma-separated list of fields to sort on. postfix field with - to sort desc. ex: -o 'num\_gpus,total\_flops-'.  default='score-'
</ParamField>

<ParamField path="--login" type="string">
  docker login arguments for private repo authentication, surround with ''
</ParamField>

<ParamField path="--label" type="string">
  label to set on the instance
</ParamField>

<ParamField path="--onstart" type="string">
  filename to use as onstart script
</ParamField>

<ParamField path="--onstart-cmd" type="string">
  contents of onstart script as single argument
</ParamField>

<ParamField path="--entrypoint" type="string">
  override entrypoint for args launch instance
</ParamField>

<ParamField path="--ssh" type="boolean">
  Launch as an ssh instance type
</ParamField>

<ParamField path="--jupyter" type="boolean">
  Launch as a jupyter instance instead of an ssh instance
</ParamField>

<ParamField path="--direct" type="boolean">
  Use (faster) direct connections for jupyter & ssh
</ParamField>

<ParamField path="--jupyter-dir" type="string">
  For runtype 'jupyter', directory in instance to use to launch jupyter. Defaults to image's working directory
</ParamField>

<ParamField path="--jupyter-lab" type="boolean">
  For runtype 'jupyter', Launch instance with jupyter lab
</ParamField>

<ParamField path="--lang-utf8" type="boolean">
  Workaround for images with locale problems: install and generate locales before instance launch, and set locale to C.UTF-8
</ParamField>

<ParamField path="--python-utf8" type="boolean">
  Workaround for images with locale problems: set python's locale to C.UTF-8
</ParamField>

<ParamField path="--env" type="string">
  env variables and port mapping options, surround with ''
</ParamField>

<ParamField path="--args" type="string">
  list of arguments passed to container ENTRYPOINT. Onstart is recommended for this purpose. (must be last argument)
</ParamField>

<ParamField path="--cancel-unavail" type="boolean">
  Return error if scheduling fails (rather than creating a stopped instance)
</ParamField>

<ParamField path="--template_hash" type="string">
  template hash which contains all relevant information about an instance. This can be used as a replacement for other parameters describing the instance configuration
</ParamField>

## Description

Launches an instance based on the given parameters. The instance will be created with the top offer from the search results.
Besides the gpu\_name and num\_gpus, you must pass in an '--image' argument as a minimum.

If you use args/entrypoint launch mode, we create a container from your image as is, without attempting to inject ssh and or jupyter.
If you use the args launch mode, you can override the entrypoint with --entrypoint, and pass arguments to the entrypoint with --args.
If you use --args, that must be the last argument, as any following tokens are consumed into the args string.
For ssh/jupyter launch types, use --onstart-cmd to pass in startup script, instead of --entrypoint and --args.

## Examples

```bash theme={null}
# launch a single RTX 3090 instance with the pytorch image and 16 GB of disk space located anywhere
    python vast.py launch instance -g RTX_3090 -n 1 -i pytorch/pytorch

    # launch a 4x RTX 3090 instance with the pytorch image and 32 GB of disk space located in North America
    python vast.py launch instance -g RTX_3090 -n 4 -i pytorch/pytorch -d 32.0 -r North_America

Available fields:

    Name                    Type      Description

    num_gpus:               int       # of GPUs
    gpu_name:               string    GPU model name
    region:                 string    Region of the instance
    image:                  string    Docker image name
    disk_space:             float     Disk space in GB
    ssh, jupyter, direct:   bool      Flags to specify the instance type and connection method.
    env:                    str       Environment variables and port mappings, encapsulated in single quotes.
    args:                   list      Arguments passed to the container's ENTRYPOINT, used only if '--args' is specified.
```

## Global Options

The following options are available for all commands:

| Option          | Description                                           |
| --------------- | ----------------------------------------------------- |
| `--url URL`     | Server REST API URL                                   |
| `--retry N`     | Retry limit                                           |
| `--raw`         | Output machine-readable JSON                          |
| `--explain`     | Verbose explanation of API calls                      |
| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |