Shadeform

https://docs.shadeform.ai/
Admin
Shadeform is a multi-cloud GPU instance platform that provides unified access to GPU availability,...
Tokens:98,866
Snippets:275
Trust Score:7.9
Update:1 year ago
Show doc for...
Tokens:
Raw
### Script Launch Configuration Example

Source: https://docs.shadeform.ai/api-reference/templates/templates-info

Example of configuring a script-based launch for an instance. This involves providing a base64 encoded startup script that will be executed once the instance is active.

```yaml
launch_configuration:
  type: script
  script_configuration:
    base64_script: IyEvYmluL2Jhc2gKCiMgRW5kbGVzcyBsb29wCndoaWxlIHRydWUKZG8KICAgICMgRmV0Y2ggYSBjYXQgZmFjdCB3aXRoIGEgbWF4aW11bSBsZW5ndGggb2YgMTQwIGNoYXJhY3RlcnMKICAgIGN1cmwgLS1uby1wcm9ncmVzcy1tZXRlciBodHRwczovL2NhdGZhY3QubmluamEvZmFjdD9tYXhfbGVuZ3RoPTE0MAoKICAgICMgUHJpbnQgYSBuZXdsaW5lIGZvciByZWFkYWJpbGl0eQogICAgZWNobwoKICAgICMgU2xlZXAgZm9yIDMgc2Vjb25kcyBiZWZvcmUgdGhlIG5leHQgaXRlcmF0aW9uCiAgICBzbGVlcCAzCmRvbmUKCgo=
```

--------------------------------

### Docker Launch Configuration Example

Source: https://docs.shadeform.ai/api-reference/templates/templates-info

Example of how to configure a Docker launch for an instance. This includes specifying the Docker image, arguments, shared memory, environment variables, port mappings, volume mounts, and registry credentials.

```yaml
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: 8000
        container_port: 80
    volume_mounts:
      - host_path: /path/on/host
        container_path: /path/in/container
    registry_credentials:
      username: "my-registry-user"
      password: "my-registry-password"
```

--------------------------------

### Finding a GPU Instance

Source: https://docs.shadeform.ai/getting-started/quickstart

Use the /instances/types API to query for available GPU instances based on criteria like GPU type, number of GPUs, and availability. This example shows how to find the cheapest A6000 instance.

```APIDOC
## GET /v1/instances/types

### Description
Queries for available GPU instances based on specified criteria.

### Method
GET

### Endpoint
/v1/instances/types

#### Query Parameters
- **gpu_type** (string) - Required - The type of GPU to search for (e.g., 'A6000').
- **num_gpus** (integer) - Required - The number of GPUs required.
- **available** (boolean) - Required - Whether the instance must be available.
- **sort** (string) - Optional - Field to sort the results by (e.g., 'price').

### Request Example
```bash
curl --request GET \
  --url 'https://api.shadeform.ai/v1/instances/types?gpu_type=A6000&num_gpus=1&available=true&sort=price' \
  --header 'X-API-KEY: <api-key>'
```

### Response
#### Success Response (200)
- **instance_types** (array) - An array of available instance types matching the criteria.
  - **cloud** (string) - The cloud provider where the instance is available.
  - **shade_instance_type** (string) - Shadeform's internal identifier for the instance type.
  - **cloud_instance_type** (string) - The instance type identifier on the cloud provider.
  - **configuration** (object) - Detailed configuration of the instance.
  - **hourly_price** (number) - The hourly price of the instance.
  - **availability** (array) - List of regions where the instance is available.
    - **region** (string) - The region identifier.
    - **available** (boolean) - Whether the instance is available in this region.

#### Response Example
```json
{
  "instance_types": [
    {
      "cloud": "massedcompute",
      "shade_instance_type": "A6000_plus",
      "cloud_instance_type": "gpu_1x_A6000_high_perf",
      "configuration": {
        "memory_in_gb": 64,
        "storage_in_gb": 256,
        "vcpus": 12,
        "num_gpus": 1,
        "gpu_type": "A6000",
        "interconnect": "pcie",
        "os_options": [
          "ubuntu22.04_cuda12.2_shade_os"
        ],
        "vram_per_gpu_in_gb": 48
      },
      "memory_in_gb": 64,
      "storage_in_gb": 256,
      "vcpus": 12,
      "num_gpus": 1,
      "gpu_type": "A6000",
      "interconnect": "pcie",
      "hourly_price": 57,
      "availability": [
        {
          "region": "us-central-1",
          "available": true,
          "display_name": "US, Wichita, KS"
        }
      ],
      "boot_time": {
          "min_boot_in_sec": 180,
          "max_boot_in_sec": 300
        }
    }
  ]
}
```
```

--------------------------------

### Configure UFW Rules

Source: https://docs.shadeform.ai/guides/firewall

Provides examples of how to set up firewall rules using the UFW command-line interface. These rules can specify allowed or denied traffic for individual ports, port ranges, and protocols (TCP/UDP).

```bash
sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 1194/udp
sudo ufw deny 25/tcp
sudo ufw allow 3000:4000/tcp
```

--------------------------------

### Launch Configuration Schemas

Source: https://docs.shadeform.ai/api-reference/instances/instances-create

Defines the structure for different launch configurations, including Docker and script-based setups.

```APIDOC
## Launch Configuration Schemas

### Description
These schemas define the available launch configurations for instances, allowing for automated actions upon instance activation. This includes specifying Docker images or startup scripts.

### DockerConfiguration

#### Description
Configuration for running a Docker container on the instance. This is used when `launch_configuration.type` is set to 'docker'.

#### Properties
- **image** (string) - Required - The Docker image to pull and run (e.g., `vllm/vllm-openai:latest`).
- **args** (string) - Optional - Arguments to pass to the Docker container at runtime (e.g., `--model mistralai/Mistral-7B-v0.1`).
- **shared_memory_in_gb** (integer) - Optional - Amount of shared memory allocated for the container in GB.
- **envs** (array) - Optional - List of environment variables for the container.
  - **items** (object) - Environment variable details.
    - **name** (string) - Required - The name of the environment variable.
    - **value** (string) - Required - The value of the environment variable.
- **port_mappings** (array) - Optional - List of port mappings between the host and the container.
  - **items** (object) - Port mapping details.
- **volume_mounts** (array) - Optional - List of volume mounts between the host and the container.
  - **items** (object) - Volume mount details.
- **registry_credentials** (object) - Optional - Credentials for private Docker registries.
  - **username** (string) - Optional - Username for the registry.
  - **password** (string) - Optional - Password for the registry.

### ScriptConfiguration

#### Description
Configuration for running a startup script on the instance. This is used when `launch_configuration.type` is set to 'script'.

#### Properties
- **base64_script** (string) - Required - The startup script, base64 encoded.

### LaunchConfiguration

#### Description
Defines the type of launch configuration for an instance.

#### Properties
- **type** (string) - Required - Specifies the type of launch configuration. Must be one of: `docker`, `script`.
- **docker_configuration** (object) - Optional - Docker specific configuration, used when `type` is 'docker'.
  - **$ref** - `#/components/schemas/DockerConfiguration`
- **script_configuration** (object) - Optional - Script specific configuration, used when `type` is 'script'.
  - **$ref** - `#/components/schemas/ScriptConfiguration`
```

--------------------------------

### Instance Object Schema and Example - OpenAPI

Source: https://docs.shadeform.ai/api-reference/instances/instances-info

Defines the structure of an instance object, including required properties like ID, cloud provider details, instance type, configuration, IP address, SSH credentials, status, and cost estimates. It also provides a detailed example of a complete instance object with various configurations.

```yaml
components:
  schemas:
    InstanceConfiguration:
      type: object
      required:
        - memory_in_gb
        - storage_in_gb
        - vcpus
        - num_gpus
        - gpu_type
        - interconnect
        - os
        - vram_per_gpu_in_gb
        - gpu_manufacturer
      properties:
        memory_in_gb:
          type: integer
          example: 12
          description: >-
            The amount of memory for the instance in gigabytes. Note that this
            is not VRAM which is determined by GPU type and the number of GPUs.
        storage_in_gb:
          type: integer
          example: 256
          description: >-
            The amount of storage for the instance. If this storage is too low
            for the instance type, please email support@shadeform.ai as the
            storage may be adjustable.
        vcpus:
          type: integer
          example: 6
          description: The number of vCPUs for the instance.
        num_gpus:
          type: integer
          example: 1
          description: The number of GPUs for the instance.
        gpu_type:
          type: string
# ... (rest of the schema and example)
```

--------------------------------

### POST /v1/instances/create

Source: https://docs.shadeform.ai/guides/jupyter

Creates a new cloud instance with specified configurations, such as container image, region, and instance type.

```APIDOC
## POST /v1/instances/create

### Description
Creates a new cloud instance with specified configurations, such as container image, region, and instance type.

### Method
POST

### Endpoint
https://api.shadeform.ai/v1/instances/create

### Parameters
#### Headers
- **X-API-KEY** (string) - Required - Your API key for authentication.
- **Content-Type** (string) - Required - Must be `application/json`.

#### Request Body
- **cloud** (string) - Required - The cloud provider to use (e.g., "massedcompute").
- **region** (string) - Required - The region for the instance (e.g., "us-central-2").
- **shade_instance_type** (string) - Required - The type of GPU instance (e.g., "A6000").
- **shade_cloud** (boolean) - Required - Whether to use Shadecloud.
- **name** (string) - Required - A name for the instance.
- **launch_configuration** (object) - Required - Configuration for launching the instance.
  - **type** (string) - Required - The type of launch configuration (e.g., "docker").
  - **docker_configuration** (object) - Required if `type` is "docker".
    - **image** (string) - Required - The Docker image to use (e.g., "quay.io/jupyter/pytorch-notebook:cuda12-python-3.11.8").

### Request Example
```json
{
  "cloud": "massedcompute",
  "region": "us-central-2",
  "shade_instance_type": "A6000",
  "shade_cloud": true,
  "name": "jupyter-notebook",
  "launch_configuration": {
    "type": "docker",
    "docker_configuration": {
      "image": "quay.io/jupyter/pytorch-notebook:cuda12-python-3.11.8"
    }
  }
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the created instance.
- **cloud_assigned_id** (string) - The ID assigned by the cloud provider.

#### Response Example
```json
{
  "id": "26bedfa2-1e98-4ff5-9342-a5b0987a2f0f",
  "cloud_assigned_id": "b9ecaf4e-d6ac-42eb-a89a-60010065388a"
}
```
```

--------------------------------

### Get All Storage Volumes (OpenAPI)

Source: https://docs.shadeform.ai/api-reference/volumes/volumes

This OpenAPI definition describes the GET /volumes endpoint. It specifies the request method, URL, authentication requirements, and the structure of the successful JSON response, including the schema for volume objects and an example.

```yaml
paths:
  path: /volumes
  method: get
  servers:
    - url: https://api.shadeform.ai/v1
      description: Shadeform Production
  request:
    security:
      - title: ApiKeyAuth
        parameters:
          query: {}
          header:
            X-API-KEY:
              type: apiKey
          cookie: {}
    parameters:
      path: {}
      query: {}
      header: {}
      cookie: {}
    body: {}
  response:
    '200':
      application/json:
        schemaArray:
          - type: object
            properties:
              volumes:
                allOf:
                  - type: array
                    items:
                      $ref: '#/components/schemas/Volume'
            refIdentifier: '#/components/schemas/VolumesResponse'
            requiredProperties:
              - volumes
        examples:
          example:
            value:
              volumes:
                - id: 78a0dd5a-dbb1-4568-b55c-5e7e0a8b0c40
                  cloud: hyperstack
                  cloud_assigned_id: 13b057d7-e266-4869-985f-760fe75a78b3
                  region: canada-1
                  name: My storage volume
                  fixed_size: true
                  size_in_gb: 100
                  cost_estimate: '103.4'
                  supports_multi_mount: true
                  mounted_by: 13b057d7-e266-4869-985f-760fe75a78b3
        description: Returns an VolumesResponse object
  deprecated: false
  type: path
components:
  schemas:
    Cloud:
      type: string
      example: hyperstack
      enum:
        - 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
      description: >-
        Specifies the underlying cloud provider. See this
        [explanation](/getting-started/concepts#cloud-cloud-provider) for more
        details.
    Region:
      type: string
      example: canada-1
      description: Specifies the region.
    CostEstimate:
      type: string
      example: '103.4'
      description: >-
        The cost incurred by the instance. This only the cost via Shadeform. If
        the instance is deployed in your own cloud account, then all billing is
        through your cloud provider.
    Volume:
      type: object
      required:
        - id
        - cloud
        - cloud_assigned_id
        - region
        - name
        - fixed_size
        - size_in_gb
        - cost_estimate
        - supports_multi_mount
        - mounted_by
      properties:
        id:
          $ref: '#/components/schemas/VolumeID'
        cloud:
          $ref: '#/components/schemas/Cloud'
        cloud_assigned_id:
          $ref: '#/components/schemas/VolumeCloudAssignedId'
        region:
          $ref: '#/components/schemas/Region'
        name:
          $ref: '#/components/schemas/VolumeName'
        fixed_size:
          $ref: '#/components/schemas/VolumeFixedSize'
        size_in_gb:
          $ref: '#/components/schemas/VolumeSizeInGB'
        cost_estimate:
          $ref: '#/components/schemas/CostEstimate'
        supports_multi_mount:
          $ref: '#/components/schemas/VolumeSupportsMultiMount'
        mounted_by:
          $ref: '#/components/schemas/VolumeMountedBy'
    VolumeID:
      type: string
      example: 78a0dd5a-dbb1-4568-b55c-5e7e0a8b0c40
      description: The ID of the storage volume.
    VolumeName:
      type: string
      example: My storage volume
      description: The name of the storage volume.
    VolumeCloudAssignedId:
      type: string
      example: 13b057d7-e266-4869-985f-760fe75a78b3
      description: >-
        The unique identifier of the storage volume issued by the underlying
        cloud provider.
    VolumeFixedSize:
      type: boolean
      example: true
      description: Denotes whether the volume is fixed in size or elastically scaling.
    VolumeSizeInGB:
      type: integer
      example: 100
      description: Storage volume size in GB
    VolumeSupportsMultiMount:
      type: boolean
      example: true
      description: >-
        Denotes whether the volume supports multiple instances mounting to it at
        the same time.
    VolumeMountedBy:
      type: string
      example: 13b057d7-e266-4869-985f-760fe75a78b3
      description: The ID of the instance that is currently mounting the volume.
```

--------------------------------

### Get Featured Templates API Endpoint (OpenAPI)

Source: https://docs.shadeform.ai/api-reference/templates/templates-featured

Defines the GET /templates/featured endpoint for retrieving a list of featured templates. It includes server information, authentication requirements (API Key), request/response schemas, and an example response.

```yaml
paths:
  path: /templates/featured
  method: get
  servers:
    - url: https://api.shadeform.ai/v1
      description: Shadeform Production
  request:
    security:
      - title: ApiKeyAuth
        parameters:
          query: {}
          header:
            X-API-KEY:
              type: apiKey
          cookie: {}
    parameters:
      path: {}
      query: {}
      header: {}
      cookie: {}
    body: {}
  response:
    '200':
      application/json:
        schemaArray:
          - type: object
            properties:
              templates:
                allOf:
                  - type: array
                    items:
                      $ref: '#/components/schemas/Template'
            refIdentifier: '#/components/schemas/TemplatesResponse'
            requiredProperties:
              - templates
        examples:
          example:
            value:
              templates:
                - id: d290f1ee-6c54-4b01-90e6-d701748f0851
                  name: My AwesomeTemplate
                  description: A template for running vLLM
                  author: John Doe
                  logo: https://example.com/logo.png
                  public: true
                  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=
                  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
                  networking:
                    ufw_rules:
                      - rule: allow
                        from_ip: 192.168.1.0/24
                        to_ip: 10.0.0.0/8
                        port: '80'
                        proto: tcp
        description: Returns a list of featured templates
  deprecated: false
  type: path
components:
  schemas:
    LaunchConfiguration:
      type: object
      required:
        - type
      description: Defines automatic actions after the instance becomes active.
      properties:
        type:
          type: string
          example: docker
          enum:
            - docker
            - script
          description: >-
            Specifies the type of launch configuration. See [Launch
            Configuration](/getting-started/concepts#launch-configuration) for
            more details.
        docker_configuration:
          $ref: '#/components/schemas/DockerConfiguration'
        script_configuration:
          $ref: '#/components/schemas/ScriptConfiguration'
    DockerConfiguration:
      type: object
      required:
        - image
      description: >-
        May only be used if launch_configuration.type is 'docker'. Use
        docker_configuration to automatically pull and run a docker image. See
        this [tutorial](/guides/dockercontainers) for examples.
      properties:
        image:
          type: string
          example: vllm/vllm-openai:latest
          description: >-
            Specifies the docker image to be pulled and run on the instance at
            startup.
        args:
          type: string
          example: '--model mistralai/Mistral-7B-v0.1'
          description: Specifies the container arguments passed into the image at runtime.
        shared_memory_in_gb:
          type: integer
          example: 8
          description: >-

```

--------------------------------

### OpenAPI Specification for GET /volumes/types

Source: https://docs.shadeform.ai/api-reference/volumes/volumes-types

This OpenAPI specification defines the structure and behavior of the GET /volumes/types API endpoint. It includes details on the request parameters, response schema, and example responses for retrieving supported storage volume types. The specification also outlines the components for cloud providers, regions, and volume characteristics.

```yaml
paths:
  path: /volumes/types
  method: get
  servers:
    - url: https://api.shadeform.ai/v1
      description: Shadeform Production
  request:
    security:
      - title: ApiKeyAuth
        parameters:
          query: {}
          header:
            X-API-KEY:
              type: apiKey
          cookie: {}
    parameters:
      path: {}
      query: {}
      header: {}
      cookie: {}
    body: {}
  response:
    '200':
      application/json:
        schemaArray:
          - type: object
            properties:
              volume_types:
                allOf:
                  - $ref: '#/components/schemas/VolumeTypes'
            refIdentifier: '#/components/schemas/VolumesTypesResponse'
            requiredProperties:
              - volume_types
        examples:
          example:
            value:
              volume_types:
                - cloud: hyperstack
                  region: canada-1
                  supports_multi_mount: true
                  fixed_size: true
                  price_per_gb_per_hour: '0.0001'
        description: Returns an VolumesTypesResponse object.
  deprecated: false
  type: path
components:
  schemas:
    Cloud:
      type: string
      example: hyperstack
      enum:
        - 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
      description: >-
        Specifies the underlying cloud provider. See this
        [explanation](/getting-started/concepts#cloud-cloud-provider) for more
        details.
    Region:
      type: string
      example: canada-1
      description: Specifies the region.
    VolumeFixedSize:
      type: boolean
      example: true
      description: Denotes whether the volume is fixed in size or elastically scaling.
    VolumeSupportsMultiMount:
      type: boolean
      example: true
      description: >-
        Denotes whether the volume supports multiple instances mounting to it at
        the same time.
    VolumePricePerGBPerHour:
      type: string
      example: '0.0001'
      description: Price of the specified volume type per GB per hour
    VolumeTypes:
      type: array
      items:
        type: object
        required:
          - cloud
          - region
          - supports_multi_mount
          - fixed_size
          - price_per_gb_per_hour
        properties:
          cloud:
            $ref: '#/components/schemas/Cloud'
          region:
            $ref: '#/components/schemas/Region'
          supports_multi_mount:
            $ref: '#/components/schemas/VolumeSupportsMultiMount'
          fixed_size:
            $ref: '#/components/schemas/VolumeFixedSize'
          price_per_gb_per_hour:
            $ref: '#/components/schemas/VolumePricePerGBPerHour'

```

--------------------------------

### POST /v1/instances/create

Source: https://docs.shadeform.ai/guides/startupscript

Create a new GPU instance with a startup script included in the `base64_script` property.

```APIDOC
## POST /v1/instances/create

### Description
Creates a new instance with a specified configuration, including an optional startup script.

### Method
POST

### Endpoint
/v1/instances/create

### Parameters
#### Query Parameters
None

#### Request Body
- **cloud** (string) - Required - The cloud provider to use.
- **region** (string) - Required - The region within the cloud provider.
- **shade_instance_type** (string) - Required - The type of instance to create.
- **shade_cloud** (boolean) - Required - Whether to use Shadeform's cloud infrastructure.
- **name** (string) - Required - The name of the instance.
- **launch_configuration** (object) - Required - Configuration for launching the instance.
  - **type** (string) - Required - The type of launch configuration, e.g., 'script'.
  - **script_configuration** (object) - Required if type is 'script' - Configuration for script-based launch.
    - **base64_script** (string) - Required - The base64 encoded startup script.
```

```APIDOC
### Request Example
```json
{
  "cloud": "massedcompute",
  "region": "us-central-2",
  "shade_instance_type": "A6000",
  "shade_cloud": true,
  "name": "docker-example",
  "launch_configuration": {
    "type": "script",
    "script_configuration": {
      "base64_script": "IyEvYmluL2Jhc2gKY291bnRlcj0xCgojIEluZmluaXRlIGxvb3AKd2hpbGUgdHJ1ZTsgZG8KICBlY2hvICRjb3VudGVyCiAgIyBJbmNyZW1lbnQgdGhlIGNvdW50ZXIKICAoKGNvdW50ZXIrKykpCiAgIyBXYWl0IGZvciAzIHNlY29uZHMKICBzbGVlcCAzCmRvbmUK"
    }
  }
}
```
```

```APIDOC
### Response
#### Success Response (200)
- **instance_id** (string) - The ID of the created instance.
- **status** (string) - The current status of the instance.

#### Response Example
```json
{
  "instance_id": "inst-12345abcde",
  "status": "pending"
}
```
```

--------------------------------

### GET /instances Endpoint Definition (OpenAPI/YAML)

Source: https://docs.shadeform.ai/api-reference/instances/instances

Defines the GET /instances endpoint for retrieving instance information from the Shadeform AI API. It specifies the server URL, security requirements (API Key), request parameters, and the structure of the 200 OK response, including an example instance.

```yaml
paths:
  path: /instances
  method: get
  servers:
    - url: https://api.shadeform.ai/v1
      description: Shadeform Production
  request:
    security:
      - title: ApiKeyAuth
        parameters:
          query: {}
          header:
            X-API-KEY:
              type: apiKey
          cookie: {}
    parameters:
      path: {}
      query: {}
      header: {}
      cookie: {}
    body: {}
  response:
    '200':
      application/json:
        schemaArray:
          - type: object
            properties:
              instances:
                allOf:
                  - type: array
                    items:
                      $ref: '#/components/schemas/Instance'
            refIdentifier: '#/components/schemas/InstancesResponse'
            requiredProperties:
              - instances
        examples:
          example:
            value:
              instances:
                - id: d290f1ee-6c54-4b01-90e6-d701748f0851
                  cloud: hyperstack
                  region: canada-1
                  shade_instance_type: A6000
                  cloud_instance_type: gpu_1x_a6000
                  cloud_assigned_id: 13b057d7-e266-4869-985f-760fe75a78b3
                  shade_cloud: true
                  name: cool-gpu-server
                  configuration:
                    memory_in_gb: 12
                    storage_in_gb: 256
                    vcpus: 6
                    num_gpus: 1
                    gpu_type: A100
                    interconnect: pcie
                    nvlink: true
                    vram_per_gpu_in_gb: 48
                    gpu_manufacturer: nvidia
                    os: ubuntu_22_shade_os
                  ip: 1.0.0.1
                  ssh_user: shadeform
                  ssh_port: 22
                  status: active
                  status_details: downloading
                  cost_estimate: '103.4'
                  hourly_price: 210
                  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=
                  tags:
                    - tag1
                  port_mappings:
                    - internal_port: 8000
                      external_port: 80
                  active_at: '2016-08-29T09:12:33.001Z'
                  created_at: '2016-08-29T09:12:33.001Z'
                  deleted_at: '2016-08-29T09:12:33.001Z'
                  boot_time:
                    min_boot_in_sec: 180
                    max_boot_in_sec: 300
        description: Returns an InstancesResponse object.
  deprecated: false
  type: path
components:
  schemas:
    Instance:
      type: object
      required:
        - id
        - cloud
        - region
        - shade_instance_type
        - cloud_instance_type
        - cloud_assigned_id
        - shade_cloud
        - name
        - configuration
        - ip
        - ssh_user
        - ssh_port
        - status
        - cost_estimate
        - created_at
        - deleted_at
      properties:
        id:
          $ref: '#/components/schemas/Id'
        cloud:
          $ref: '#/components/schemas/Cloud'
        region:
          $ref: '#/components/schemas/Region'
        shade_instance_type:
          $ref: '#/components/schemas/ShadeInstanceType'
        cloud_instance_type:
          $ref: '#/components/schemas/CloudInstanceType'
        cloud_assigned_id:
          $ref: '#/components/schemas/CloudAssignedId'
        shade_cloud:
          $ref: '#/components/schemas/ShadeCloud'
        name:
          $ref: '#/components/schemas/Name'
        configuration:
          allOf:
            - $ref: '#/components/schemas/InstanceConfiguration'
            - type: object
              required:
                - os
```

--------------------------------

### Launch GPU Instance (CLI)

Source: https://docs.shadeform.ai/getting-started/quickstart

Launches a GPU instance using the Shadeform API with specified cloud, region, and instance type. Requires an API key and accepts a JSON payload. The response contains the instance 'id', which is needed for further operations.

```bash
curl --request POST \
  --url 'https://api.shadeform.ai/v1/instances/create' \
  --header 'X-API-KEY: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "cloud": "massedcompute",
    "region": "us-central-1",
    "shade_instance_type": "A6000_plus",
    "shade_cloud": true,
    "name": "quickstart"
  }'
```

--------------------------------

### Check UFW Status

Source: https://docs.shadeform.ai/guides/firewall

Verifies if the Uncomplicated Firewall (UFW) is installed and its current status on the machine. UFW is typically pre-installed on Shadeform instances.

```bash
sudo ufw status
```

--------------------------------

### Find Cheapest A6000 GPU Instance (CLI)

Source: https://docs.shadeform.ai/getting-started/quickstart

Queries the Shadeform API to find the cheapest available A6000 GPU instance. Requires an API key. Returns a JSON object containing instance details, from which 'cloud', 'region', and 'shade_instance_type' are extracted.

```bash
curl --request GET \
  --url 'https://api.shadeform.ai/v1/instances/types?gpu_type=A6000&num_gpus=1&available=true&sort=price' \
  --header 'X-API-KEY: <api-key>'
```

--------------------------------

### GET /volumes/types

Source: https://docs.shadeform.ai/guides/attachvolume

Retrieves a list of available volume types, including their cloud provider, region, and pricing details. This is the first step to understanding what storage options are available.

```APIDOC
## GET /volumes/types

### Description
Retrieves a list of available volume types, including their cloud provider, region, and pricing details. This is the first step to understanding what storage options are available.

### Method
GET

### Endpoint
/v1/volumes/types

### Parameters
#### Query Parameters
- **x-api-key** (string) - Required - Your Shadeform API key for authentication.

### Request Example
```bash
curl --location 'https://api.shadeform.ai/v1/volumes/types' \
--header 'x-api-key: <api-key>'
```

### Response
#### Success Response (200)
- **volume_types** (array) - A list of available volume type objects.
  - **cloud** (string) - The cloud provider for the volume type.
  - **region** (string) - The region where the volume type is available.
  - **supports_multiple_mounts** (boolean) - Indicates if the volume type supports mounting to multiple instances.
  - **fixed_size** (boolean) - Indicates if the volume type has a fixed size.
  - **price_per_gb_per_hour** (string) - The cost per gigabyte per hour for this volume type.

#### Response Example
```json
{
  "volume_types": [
    {
      "cloud": "datacrunch",
      "region": "FIN-01",
      "supports_multiple_mounts": false,
      "fixed_size": true,
      "price_per_gb_per_hour": "0.00028"
    },
    {
      "cloud": "nebius",
      "region": "eu-north1",
      "supports_multiple_mounts": false,
      "fixed_size": true,
      "price_per_gb_per_hour": ".000097"
    },
    {
      "cloud": "digitalocean",
      "region": "tor1",
      "supports_multiple_mounts": false,
      "fixed_size": true,
      "price_per_gb_per_hour": ".000084"
    }
  ]
}
```
```

--------------------------------

### Execute Startup Script in Container (Base64 Encoded)

Source: https://docs.shadeform.ai/api-reference/instances/instances

Defines a startup script to be executed automatically after the instance becomes active. The script must be provided as a base64 encoded string. The example script fetches a cat fact indefinitely.

```YAML
script_configuration:
  base64_script: "IyEvYmluL2Jhc2gKCiMgRW5kbGVzcyBsb29wCndoaWxlIHRydWUKZG8KICAgICMgRmV0Y2ggYSBjYXQgZmFjdCB3aXRoIGEgbWF4aW11bSBsZW5ndGggb2YgMTQwIGNoYXJhY3RlcnMKICAgIGN1cmwgLS1uby1wcm9ncmVzcy1tZXRlciBodHRwczovL2NhdGZhY3QubmluamEvZmFjdD9tYXhfbGVuZ3RoPTE0MAoKICAgICMgUHJpbnQgYSBuZXdsaW5lIGZvciByZWFkYWJpbGl0eQogICAgZWNobwoKICAgICMgU2xlZXAgZm9yIDMgc2Vjb25kcyBiZWZvcmUgdGhlIG5leHQgaXRlcmF0aW9uCiAgICBzbGVlcCAzCmRvbmUKCgo="
```

--------------------------------

### Launch Configuration - Script Execution

Source: https://docs.shadeform.ai/api-reference/instances/instances-info

Defines how to launch an instance using a script. The script content is provided in Base64 encoding. This allows for custom initialization or execution logic upon instance startup.

```yaml
launch_configuration:
  type: script
  script_configuration:
    base64_script: >-
      IyEvYmluL2Jhc2gKCiMgRW5kbGVzcyBsb29wCndoaWxlIHRydWUKZG8KICAgICMgRmV0Y2ggYSBjYXQgZmFjdCB3aXRoIGEgbWF4aW11bSBsZW5ndGggb2YgMTQwIGNoYXJhY3RlcnMKICAgIGN1cmwgLS1uby1wcm9ncmVzcy1tZXRlciBodHRwczovL2NhdGZhY3QubmluamEvZmFjdD9tYXhfbGVuZ3RoPTE0MAoKICAgICMgUHJpbnQgYSBuZXdsaW5lIGZvciByZWFkYWJpbGl0eQogICAgZWNobwoKICAgICMgU2xlZXAgZm9yIDMgc2Vjb25kcyBiZWZvcmUgdGhlIG5leHQgaXRlcmF0aW9uCiAgICBzbGVlcCAzCmRvbmUKCgo=
```

--------------------------------

### Check GPU Availability with PyTorch (Python)

Source: https://docs.shadeform.ai/guides/jupyter

This Python code snippet utilizes the PyTorch library to determine if a GPU is available on the machine. It's intended to be run within the launched Jupyter Notebook instance to confirm GPU access. Ensure PyTorch is installed in your environment.

```python
import torch
```

--------------------------------

### Create Instance with Startup Script (CLI)

Source: https://docs.shadeform.ai/guides/startupscript

Example of creating a GPU instance using the Shadeform API via cURL. It includes a base64 encoded startup script in the launch configuration.

```bash
curl --request POST \
  --url 'https://api.shadeform.ai/v1/instances/create' \
  --header 'X-API-KEY: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{ \
    "cloud": "massedcompute", \
    "region": "us-central-2", \
    "shade_instance_type": "A6000", \
    "shade_cloud": true, \
    "name": "docker-example", \
    "launch_configuration": { \
      "type": "script", \
      "script_configuration": { \
        "base64_script": "IyEvYmluL2Jhc2gKY291bnRlcj0xCgojIEluZmluaXRlIGxvb3AKd2hpbGUgdHJ1ZTsgZG8KICBlY2hvICRjb3VudGVyCiAgIyBJbmNyZW1lbnQgdGhlIGNvdW50ZXIKICAoKGNvdW50ZXIrKykpCiAgIyBXYWl0IGZvciAzIHNlY29uZHMKICBzbGVlcCAzCmRvbmUK" \
      } \
    } \
  }'

```
Tokens:
Raw