> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vast.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# vastai create instance

Create a new instance

## Usage

```bash theme={null}
vastai create instance ID [OPTIONS] [--args ...]
```

## Arguments

<ParamField path="id" type="integer" required>
  id of instance type to launch (returned from search offers)
</ParamField>

## Options

<ParamField path="--template_hash" type="string">
  Create instance from template info
</ParamField>

<ParamField path="--user" type="string">
  User to use with docker create. This breaks some images, so only use this if you are certain you need it.
</ParamField>

<ParamField path="--disk" type="number" default="10">
  size of local disk partition in GB
</ParamField>

<ParamField path="--image" type="string">
  docker container image to launch
</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="--force" type="boolean">
  Skip sanity checks when creating from an existing instance
</ParamField>

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

<ParamField path="--bid_price" type="number">
  (OPTIONAL) create an INTERRUPTIBLE instance with per machine bid price in \$/hour
</ParamField>

<ParamField path="--create-volume" type="integer">
  Create a new local volume using an ID returned from the "search volumes" command and link it to the new instance
</ParamField>

<ParamField path="--link-volume" type="integer">
  ID of an existing rented volume to link to the instance during creation. (returned from "show volumes" cmd)
</ParamField>

<ParamField path="--volume-size" type="integer">
  Size of the volume to create in GB. Only usable with `--create-volume` (default 15GB)
</ParamField>

<ParamField path="--mount-path" type="string">
  The path to the volume from within the new instance container. e.g. /root/volume
</ParamField>

<ParamField path="--volume-label" type="string">
  (optional) A name to give the new volume. Only usable with `--create-volume`
</ParamField>

## Description

Performs the same action as pressing the "RENT" button on the website at [https://console.vast.ai/create/](https://console.vast.ai/create/)
Creates an instance from an offer ID (which is returned from "search offers"). Each offer ID can only be used to create one instance.
Besides the offer ID, 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}
# create an on-demand instance with the PyTorch (cuDNN Devel) template and 64GB of disk
vastai create instance 384826 --template_hash 661d064bbda1f2a133816b6d55da07c3 --disk 64

# create an on-demand instance with the pytorch/pytorch image, 40GB of disk, open 8081 udp, direct ssh, set hostname to billybob, and a small onstart script
vastai create instance 6995713 --image pytorch/pytorch --disk 40 --env '-p 8081:8081/udp -h billybob' --ssh --direct --onstart-cmd "env | grep _ >> /etc/environment; echo 'starting up'";

# create an on-demand instance with the bobsrepo/pytorch:latest image, 20GB of disk, open 22, 8080, jupyter ssh, and set some env variables
vastai create instance 384827  --image bobsrepo/pytorch:latest --login '-u bob -p 9d8df!fd89ufZ docker.io' --jupyter --direct --env '-e TZ=PDT -e XNAME=XX4 -p 22:22 -p 8080:8080' --disk 20

# create an on-demand instance with the pytorch/pytorch image, 40GB of disk, override the entrypoint to bash and pass bash a simple command to keep the instance running. (args launch without ssh/jupyter)
vastai create instance 5801802 --image pytorch/pytorch --disk 40 --onstart-cmd 'bash' --args -c 'echo hello; sleep infinity;'

# create an interruptible (spot) instance with the PyTorch (cuDNN Devel) template, 64GB of disk, and a bid price of $0.10/hr
vastai create instance 384826 --template_hash 661d064bbda1f2a133816b6d55da07c3 --disk 64 --bid_price 0.1

Return value:
Returns a json reporting the instance ID of the newly created instance:
{'success': True, 'new_contract': 7835610}
```

## 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`) |