Field types


name, description, and tags fields are the metadata of Run. They should be ideally represent the specific characteristics or purposes of your run for better identification.

namestringRequiredThe name of the run.
descriptionstringOptionalThe description of the run.
tagslistOptionalThe tags of the run.
Specify run metadata
name: stable-diffusion
description: This is the inference example of stable diffusion.
- "best"
- "A100-80g"
- "20epochs"


resources specifies the resource specs to use for run. Use preset provided by VESSL or request the desired resource with requests.

  1. Common fields
clusterstringOptionalThe cluster to be used for the run. (default: VESSL-managed cluster)
node_nameslistOptionalSpecify candidate nodes for workload assignment. If it’s not set, we’ll find any available node.
  1. Using preset with common fields
presetstringRequired without requestsThe name of resource spec preset that specified in VESSL. If the preset is not specified, we will offer the best option for you based on reqeusts.
  cluster: aws-apne2
  preset: v1.v100-1.mem-52
  1. Using requests with common fields
requestsmapRequired without presetThe desired resource specs.
cpustringOptionalThe number of cpu cores.
memorystringOptionalThe memory size in GB. device_type and quanity of the NVIDIA GPU to be used for the run.
  cluster: aws-apne2
    cpu: "4"
    memory: 12Gi
      device_type: V100
      quantity: "2"
You can list available clusters or resource specs with the CLI command: vessl cluster list or vessl resource list.
pip install vessl
vessl cluster list

Container Image

The image field is a string that specifies the container image to be used in the run. This is typically a Docker image that includes all the necessary dependencies and environment for your machine learning model.

imagestring or mapRequriedContainer image url or map of url and credential_name.
urlstringOptionalContainer image url.
credential_namestringOptionalRegistered credential name at VESSL for private image usage.
You can list available VESSL-managed images with the CLI command: vessl image list.
List VESSL-manged images with the VESSL CLI
pip install vessl
vessl image list


There are three type of volumes: import, mount, and export. Each field is a map that specifies a target path as a key and a source information as a value. The value is either a simple string with prefix or another map that holds more detailed information.

  1. Import The import type signifies that the data will be downloaded from the source to a target path in the running container.
git://stringOptionalImport a git repository. The repository will be cloned into the specified target path when container starts.
vessl-dataset://stringOptionalImport a dataset stored in VESSL Dataset.
vessl-model://stringOptionalImport a model stored in VESSL Model Registry.
vessl-artifact://stringOptionalImport an artifact stored in VESSL Artifact.
s3://stringOptionalImport an AWS S3 bucket.
gs://stringOptionalImport a Google Cloud Storage.
  /import/code: git://{accountName}/{repoName}
  /import/dataset: vessl-dataset://{organizationName}/{datasetName}
  /import/model: vessl-model://{organizationName}/{modelRepositoryName}/{modelNumber}
  /import/artifact: vessl-artifact://{organiztionName}/{projectName}/{artifactName}
  /import/s3: s3://{bucketName}/{path}
  /import/gs: gs://{buckeName}/{path}
  1. Mount The mount type means that the data will be directly mounted to a target path in the run container, providing direct access to the user.
vessl-dataset://stringOptionalMount a dataset stored in VESSL Dataset.
hostpath://stringOptionalMount a file or directory from the host node’s filesystem.
nfs://stringOptionalMount a Network File System(NFS).
readonlybooleanOptionalTrue if readonly mode. (default: True)
  /mount/dataset: vessl-dataset://{organizationName}/{datasetName}
  /mount/hostpath: hostpath://{path}
  /mount/nfs: nfs://{server}/{path}
  1. Export The export type is desgined for uploading data from a path in the run container to a target path after run execution.
vessl-artifact://stringOptionalExport to VESSL Artifact.
vessl-dataset://stringOptionalExport to VESSL Dataset.
vessl-model://stringOptionalExport to VESSL Model.
s3://stringOptionalExport to Amazon S3 bucket.
gs://stringOptionalExport to Google Cloud Storage.
  /export/output-artifact: vessl-artifact://  
  /export/backup-artifact: vessl-artifact://{organizationName}/{projectName}/{artifactName}
  /export/dataset: vessl-dataset://{organizationName}/{datasetName}
  /export/model: vessl-model://{organizationName}/{modelRepositoryName}
  /export/s3: s3://{buckeName}/{prefix}
  /export/gs: gs://{bucketName}/{prefix}

Run Command

The run field is a list that contains commands to be run in the container. Each item in the list is a map with the following keys. run could be empty if it’s an interactive run.

workdirstringOptionalThe working directory for the command.
commandstringRequiredThe command to be run.
waitstringOptionalHow long to wait after a command.
  - command: |
      python --learning_rate=$learning_rate --batch_size=$batch_size


The interactive field is used to specify if the run allows interactive communication with the user. It provides multiple ways to interact with the container during the run, such as JupyterLab, SSH, or a custom service via specified ports.

interactivemapOptionalMark run as an interactive type that includes max_runtime, jupyter, and idle_timeout
max_runtimestringRequiredThe amount of time to run. Set 0 for infintie use.
jupytermapRequiredJupyter configurations that includes idle_timeout
idle_timeoutstringRequiredThe amount of time a server can be inactive before it will be culled.
Maximum runtime 24h and idle_timeout 120m
  max_runtime: 24h
    idle_timeout: 120m


The ports field is a list of map that specifies the port information to expose.

portslistOptionalList of port numbers or port information that includes name, type, and port to expose.
namestringOptionalThe port name.
typestringOptionalThe protocol of port. (http or tcp)
portintOptionalThe port number.
  - 3000

Environment Variables

The env field is a map that specifies the environment variables for the run. Each key-value pair in this map represents an environment variable and its value.

envmapOptionalKey-value pairs for environment variables in the run container.
valuestringOptionalValue of environment variables.
secretbooleanOptionalTrue if the variable is secret.
Set multiple environment variables
  learning_rate: 0.001
    value: OUR_DB_PW
    secret: true