/instances/create

/instances/create

curl --request POST \
  --url https://api.shadeform.ai/v1/instances/create \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "cloud": "hyperstack",
  "region": "canada-1",
  "shade_instance_type": "A6000",
  "shade_cloud": true,
  "name": "cool-gpu-server",
  "os": "ubuntu22.04_cuda12.2_shade_os",
  "template_id": "template-123",
  "launch_configuration": {
    "type": "docker",
    "docker_configuration": {
      "image": "vllm/vllm-openai:latest",
      "args": "--model mistralai/Mistral-7B-v0.1",
      "shared_memory_in_gb": 8,
      "envs": [
        {
          "name": "HUGGING_FACE_HUB_TOKEN",
          "value": "hugging_face_api_token"
        }
      ],
      "port_mappings": [
        {
          "host_port": 80,
          "container_port": 8000
        }
      ],
      "volume_mounts": [
        {
          "host_path": "~/.cache/huggingface",
          "container_path": "/root/.cache/huggingface"
        }
      ],
      "registry_credentials": {
        "username": "username",
        "password": "password"
      }
    },
    "script_configuration": {
      "base64_script": "IyEvYmluL2Jhc2gKCiMgRW5kbGVzcyBsb29wCndoaWxlIHRydWUKZG8KICAgICMgRmV0Y2ggYSBjYXQgZmFjdCB3aXRoIGEgbWF4aW11bSBsZW5ndGggb2YgMTQwIGNoYXJhY3RlcnMKICAgIGN1cmwgLS1uby1wcm9ncmVzcy1tZXRlciBodHRwczovL2NhdGZhY3QubmluamEvZmFjdD9tYXhfbGVuZ3RoPTE0MAoKICAgICMgUHJpbnQgYSBuZXdsaW5lIGZvciByZWFkYWJpbGl0eQogICAgZWNobwoKICAgICMgU2xlZXAgZm9yIDMgc2Vjb25kcyBiZWZvcmUgdGhlIG5leHQgaXRlcmF0aW9uCiAgICBzbGVlcCAzCmRvbmUKCgo="
    }
  },
  "volume_ids": [
    "78a0dd5a-dbb1-4568-b55c-5e7e0a8b0c40"
  ],
  "ssh_key_id": "78a0dd5a-dbb1-4568-b55c-5e7e0a8b0c40",
  "auto_delete": {
    "date_threshold": "2006-01-02T15:04:05-07:00",
    "spend_threshold": "3.14"
  },
  "alert": {
    "date_threshold": "2006-01-02T15:04:05-07:00",
    "spend_threshold": "3.14"
  },
  "volume_mount": {
    "auto": true
  },
  "tags": [
    "tag1"
  ],
  "envs": [
    {
      "name": "HUGGING_FACE_HUB_TOKEN",
      "value": "hugging_face_api_token"
    }
  ]
}
'

{
  "id": "d290f1ee-6c54-4b01-90e6-d701748f0851"
}

POST

instances

create

/instances/create

curl --request POST \
  --url https://api.shadeform.ai/v1/instances/create \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "cloud": "hyperstack",
  "region": "canada-1",
  "shade_instance_type": "A6000",
  "shade_cloud": true,
  "name": "cool-gpu-server",
  "os": "ubuntu22.04_cuda12.2_shade_os",
  "template_id": "template-123",
  "launch_configuration": {
    "type": "docker",
    "docker_configuration": {
      "image": "vllm/vllm-openai:latest",
      "args": "--model mistralai/Mistral-7B-v0.1",
      "shared_memory_in_gb": 8,
      "envs": [
        {
          "name": "HUGGING_FACE_HUB_TOKEN",
          "value": "hugging_face_api_token"
        }
      ],
      "port_mappings": [
        {
          "host_port": 80,
          "container_port": 8000
        }
      ],
      "volume_mounts": [
        {
          "host_path": "~/.cache/huggingface",
          "container_path": "/root/.cache/huggingface"
        }
      ],
      "registry_credentials": {
        "username": "username",
        "password": "password"
      }
    },
    "script_configuration": {
      "base64_script": "IyEvYmluL2Jhc2gKCiMgRW5kbGVzcyBsb29wCndoaWxlIHRydWUKZG8KICAgICMgRmV0Y2ggYSBjYXQgZmFjdCB3aXRoIGEgbWF4aW11bSBsZW5ndGggb2YgMTQwIGNoYXJhY3RlcnMKICAgIGN1cmwgLS1uby1wcm9ncmVzcy1tZXRlciBodHRwczovL2NhdGZhY3QubmluamEvZmFjdD9tYXhfbGVuZ3RoPTE0MAoKICAgICMgUHJpbnQgYSBuZXdsaW5lIGZvciByZWFkYWJpbGl0eQogICAgZWNobwoKICAgICMgU2xlZXAgZm9yIDMgc2Vjb25kcyBiZWZvcmUgdGhlIG5leHQgaXRlcmF0aW9uCiAgICBzbGVlcCAzCmRvbmUKCgo="
    }
  },
  "volume_ids": [
    "78a0dd5a-dbb1-4568-b55c-5e7e0a8b0c40"
  ],
  "ssh_key_id": "78a0dd5a-dbb1-4568-b55c-5e7e0a8b0c40",
  "auto_delete": {
    "date_threshold": "2006-01-02T15:04:05-07:00",
    "spend_threshold": "3.14"
  },
  "alert": {
    "date_threshold": "2006-01-02T15:04:05-07:00",
    "spend_threshold": "3.14"
  },
  "volume_mount": {
    "auto": true
  },
  "tags": [
    "tag1"
  ],
  "envs": [
    {
      "name": "HUGGING_FACE_HUB_TOKEN",
      "value": "hugging_face_api_token"
    }
  ]
}
'

{
  "id": "d290f1ee-6c54-4b01-90e6-d701748f0851"
}

The example in the right sidebar is a schema only and will not work out of the box. Only ‘docker_configuration’ or ‘script_configuration’ can be specified but not both.

See the following tutorials related to instance creation:

Creating an Instance

Creating an Instance with a Running Container

Creating an Instance with a Startup Script

Authorizations

X-API-KEY

string

header

required

Body

application/json

cloud

enum<string>

required

Specifies the underlying cloud provider. See this explanation for more details.

Available options:

lambdalabs,

paperspace,

vultr,

datacrunch,

latitude,

massedcompute,

imwt,

hyperstack,

nebius,

crusoe,

denvr,

digitalocean,

tcm,

hotaisle,

cudo,

scaleway,

evergreen,

excesssupply,

voltagepark,

boostrun,

ionstream,

whitefiber,

horizon,

fpt,

hydra,

amaya

Example:

"hyperstack"

region

string

required

Specifies the region.

Example:

"canada-1"

shade_instance_type

string

required

The Shadeform standardized instance type. See this explanation for more details.

Example:

"A6000"

shade_cloud

boolean

required

Specifies if the instance is launched in Shade Cloud or in a linked cloud account.

Example:

true

name

string

required

The name of the instance

Example:

"cool-gpu-server"

string

The operating system of the instance.

Example:

"ubuntu22.04_cuda12.2_shade_os"

template_id

string

The ID of the template to use for this instance

Example:

"template-123"

launch_configuration

object

Defines automatic actions after the instance becomes active.

Show child attributes

launch_configuration.type

enum<string>

required

Specifies the type of launch configuration. See Launch Configuration for more details.

Available options:

docker,

script

Example:

"docker"

launch_configuration.docker_configuration

object

May only be used if launch_configuration.type is 'docker'. Use docker_configuration to automatically pull and run a docker image. See this tutorial for examples.

Show child attributes

launch_configuration.docker_configuration.image

string

required

Specifies the docker image to be pulled and run on the instance at startup.

Example:

"vllm/vllm-openai:latest"

launch_configuration.docker_configuration.args

string

Specifies the container arguments passed into the image at runtime.

Example:

"--model mistralai/Mistral-7B-v0.1"

launch_configuration.docker_configuration.shared_memory_in_gb

integer

Describes the amount of shared memory allocated for the container. Equivalent to using the --shm-size flag in the docker cli. If shared_memory_in_gb is not specified, then the container will use the host namespace which is the equivalent of --ipc=host.

Example:

8

launch_configuration.docker_configuration.envs

object[]

List of environment variable name-value pairs that will be passed to the docker container.

Show child attributes

launch_configuration.docker_configuration.envs.name

string

required

Name of the environment variable

Example:

"HUGGING_FACE_HUB_TOKEN"

launch_configuration.docker_configuration.envs.value

string

required

Value of the environment variable

Example:

"hugging_face_api_token"

launch_configuration.docker_configuration.port_mappings

object[]

List of port mappings between the host instance and the docker container. Equivalent of -p flag for docker run command.

Show child attributes

launch_configuration.docker_configuration.port_mappings.host_port

integer

required

Port of the host.

Example:

80

launch_configuration.docker_configuration.port_mappings.container_port

integer

required

Port of the container.

Example:

8000

launch_configuration.docker_configuration.volume_mounts

object[]

List of volume mounts between the host instance and the docker container. Equivalent of -v flag for docker run command.

Show child attributes

launch_configuration.docker_configuration.volume_mounts.host_path

string

required

Filepath of the host.

Example:

"~/.cache/huggingface"

launch_configuration.docker_configuration.volume_mounts.container_path

string

required

Filepath of the container.

Example:

"/root/.cache/huggingface"

launch_configuration.docker_configuration.registry_credentials

object

Show child attributes

launch_configuration.docker_configuration.registry_credentials.username

string

The username for the docker registry.

Example:

"username"

launch_configuration.docker_configuration.registry_credentials.password

string

The password for the docker registry.

Example:

"password"

launch_configuration.script_configuration

object

May only be used if launch_configuration.type is 'script'. Configures a startup script to be run automatically after the instance is active. See this [tutorial]/guides/startupscript) for examples.

Show child attributes

launch_configuration.script_configuration.base64_script

string

required

A startup script that is base64 encoded.

Example:

"IyEvYmluL2Jhc2gKCiMgRW5kbGVzcyBsb29wCndoaWxlIHRydWUKZG8KICAgICMgRmV0Y2ggYSBjYXQgZmFjdCB3aXRoIGEgbWF4aW11bSBsZW5ndGggb2YgMTQwIGNoYXJhY3RlcnMKICAgIGN1cmwgLS1uby1wcm9ncmVzcy1tZXRlciBodHRwczovL2NhdGZhY3QubmluamEvZmFjdD9tYXhfbGVuZ3RoPTE0MAoKICAgICMgUHJpbnQgYSBuZXdsaW5lIGZvciByZWFkYWJpbGl0eQogICAgZWNobwoKICAgICMgU2xlZXAgZm9yIDMgc2Vjb25kcyBiZWZvcmUgdGhlIG5leHQgaXRlcmF0aW9uCiAgICBzbGVlcCAzCmRvbmUKCgo="

volume_ids

string[]

List of volume IDs to be mounted. Currently only supports 1 volume at a time.

The ID of the storage volume.

ssh_key_id

string

The ID of the SSH Key.

Example:

"78a0dd5a-dbb1-4568-b55c-5e7e0a8b0c40"

auto_delete

object

Set a date or spend threshold to automatically delete the instance

Show child attributes

auto_delete.date_threshold

string

RFC3339 date string

Example:

"2006-01-02T15:04:05-07:00"

auto_delete.spend_threshold

string

Valid decimal representation of a dollar amount

Example:

"3.14"

alert

object

Set a date or spend threshold to receive an email alert

Show child attributes

alert.date_threshold

string

RFC3339 date string

Example:

"2006-01-02T15:04:05-07:00"

alert.spend_threshold

string

Valid decimal representation of a dollar amount

Example:

"3.14"

volume_mount

object

Settings for mounting volumes onto file systems

Show child attributes

volume_mount.auto

boolean

Set to true to automatically mount unmounted disks to a default filesystem.

Response

200 - application/json

Returns a CreateResponse object

Response of the /instances/create API call

string<uuid>

required

The unique identifier for the instance. Used in the instances for the /instances/{id}/info and /instances/{id}/delete APIs.

Example:

"d290f1ee-6c54-4b01-90e6-d701748f0851"

/instances/{id}/info

⌘I

Instances

SSH Keys

Volumes

Templates

API Documentation

Authorizations

Body

Response