Templates

​

What is a Template?

A template is how Vast helps you launch an instance, setting up your rented machine with whatever software and formatting you need. Templates are generally used for launching instances through the web interface, but they can also be used in the CLI or through the API. In this document, we will focus on the web interface, but we will link to other relevant documentation thoughout. In the simplest technical terms, you can consider a template to be a wrapper around docker run. The template contains all of the information you want to pass to our systems to configure the environment. You can browse the template section of the web interface at cloud.vast.ai/templates

​

Recommended Templates

We provide several recommended templates to help you get started. These are pre-configured environments that you can use as-is, or you can tweak them to your own requirements. Find out more about our recommended templates in the Vast Templates section later in the guide.

​

Quick Start

To Jump right in and run a template, follow these steps Visit the templates section of the console where you will find all of our recommended templates. Browse through the templates until you find one that meets your requirements. In this guide we will use NVIDIA CUDA, which is the first on the list. It’s a great starter template as it just includes the CUDA development environment, plus a few extras to improve the user experience. Now, click the ‘play’ button. This will load the template and take you to the available offers There are filters available at the top of the page to help you target a particular GPU. You will also find many additional filters on the left of the page for more fine-grained control over the instances you find. When you have found a suitable offer, simply click the ‘RENT’ button to create your new instance. You can now visit cloud.vast.ai/instances where you will find your running instance. It may take a few minutes to be ready as everything is being set up. When it is ready you will see the blue open button. This indicates that the instance is ready to connect.

​

Creating Your Own Template

You can create a new template from scratch, or you can edit an existing template. For this gude we will edit the NVIDIA CUDA template we used in the Quick Start section. From the templates page, click the pencil icon on the template card to open up the template editor. You’ll see two tabs Config and ReadMe. We’ll start with the config tab:

​

Identification

The first section helps you to keep your templates organized. Template Name This will be displayed in bold on the template card. Choose something that helps you identify the template amongst your other templates. For this guide, we will change the name to ‘NVIDIA CUDA - Demo’ Template Description This field helps describe the function and purpose of the template. Completely optional for your own purposes, but very helpful if you intend to make this template public or share it with others.

​

Docker Repository And Environment

This is where you define the Docker image you want to run, along with any options we want to pass into the container. Image Path:Tag Here is where you can define the docker image to run. This field must be in the format repository/image_name:tag. Many of our templates pull from DockerHub but you can use any container registry - Just remember to add the full path if you’re using an alternative registry. Eg. nvcr.io/nvidia/pytorch:25.04-py3 Version Tag For many registries we are able to pull the available list of tags so this field allows you to quickly select another version. There is also a special [Automatic] tag you can use. With this selected, the machine you choose for your instance will pull the most recent docker image that is compatible with that machine’s own CUDA version. This will only work if the image tag contains the CUDA version string. For example: my-image-cuda-12.8 would be loaded on a machine supporting CUDA 12.8, but a machine with only CUDA 12.6 would pull my-image-cuda-12.6 Docker Options This field is a textual representation of the ports and environment variables declared in the sections beneath it. You can edit it directly or you can use the page widgets. Ports To access your instance via the external IP address, you will need to add some ports to the template. You can add both TCP and UDP ports. When your instance is created, a port will be randomly assigned to the external interface which will map into the instance port you selected. Environment Variables Here you can add any environment variables that your docker image requires. Do not save any sensitive information here if you are planning to make the template public. Place any variables with sensitive values into the Environment Variables section of your account settings page. They will then be made available in any instance you create, regardless of the template used. You can find out more about port mapping and special environment variables in our Docker Execution Environment guide.

​

Select Launch Mode

Templates offer three launch modes you can select from. Our recommened templates will usually launch in Jupyter mode for easiest access, but you are free to choose whichever suits your needs. Jupyter-python notebook + SSH When you run the template in this mode, we will install Jupyter and SSH at runtime. Jupyter will be available on mapped port 8080 and SSH will be available on mapped port 22. Interactive shell server, SSH As above, but SSH only with no Jupyter installation. docker ENTRYPOINT In this mode, your Docker image will run precisely as it is. We will not include any additional software or access methods. If your Docker image does not offer SSH or another appropriate interface, please select one of the alternative modes if you need to interact with the running instance. An additional field will be showin when using this launch mode to allow passing arguments to the image entrypoint.

​

On-start Script

Here you can enter a short Bash script which will be run during instance startup. It is only available when using the Jupyter or SSH launch modes, and is most useful for starting any services that your docker image would have launched if run if the entrypoint had been executed. In our example ‘NVIDIA CUDA’ template we are simply calling the entrypoint.sh script which contains the logic for preparing the instance.

​

Extra Filters

Use this area to place restrictions on the machines that should show up in the search page when the template is selected.

​

Docker Repository Authentication

If you are using a private Docker image then you will need to add authentication credentials so the machine running the instance can download it.

​

Disk Space

By setting the disk space in the template, you can ensure that new instances created from the template with use this amount as a minimum.

​

Template Visibility

Any template marked as public will be available in the template search system, while private images will not. Private templates can still be used by others if you have shared the template URL.

​

CLI Command

Templates can be translated directly into CLI launch commands. This read-only area shows what you would need to type or copy to the CLI if you wanted to programatically launch an instance this way. To learn more about starting instance from the CLI, check out our quickstart guide.

​

Save the Template

Finally, you can save the template. If you are creating a new template or editing one which is not associated with your account - Such as one of our recommended templates - The buttons you see will be labelled ‘Create’. For your own templates, you will see them labelled ‘Save’ The ‘Create’ button will create a copy of the templaye in the ‘My Templates’ section of the templates page for you to use later The ‘Create & Use’ button will save the template, load it and then open up the offers page.

​

Updating a Template

If you want to make changes to a template you previously saved, simply navigate back to the templates page and select ‘My Templates’. Here you’ll be able to make your changes by clicking the pencil icon.

​

Sharing a Template

It’s really easy to share your template with other users. We have two special links you can use and both include your referral code so you can earn if new users sign up - Find more about that here. To share, click the three dots icon in the bottom right of the template card.

​

Copy referral link

This will copy a link that contains your referral ID, creator ID and the template name. It will always point to the most recent template you created with this name - Really useful if you want people clicking the link to always get the most recent version.

​

Copy template link

This will copy a link containing your referral ID and the template hash ID. It points to this specific template at this point in time. Templates all have a unique hash after every save. This is useful as it allows you to find a previous version if you have tracked the hash ID, but for sharing you probably want the referral link above.

​

Vast Templates

Templates that we have created will often be found in the Recommended section as they go through a QA process to ensure they function correctly and provide a positive user experience. They contain extras not found in all templates so we will address the differences here.

​

Instance Portal

You will notice that after clicking the Open button on template running one of the Vast.ai templates a screen like this will appear. This is our Instance Portal and it provides easy to access links to services running in your instance. It places an authentication layer in front of these services to prevent access by anyone who does not have the correct authentication token. You are also able to create tunnels to your services without exposing ports. Full documentation for the Instance Portal is available here.

​

Provisioning Script

Vast.ai templates support running a remote script on start to help configure the instance and download models and extensions that may not already be available in the Docker image. To use this feature, simply add environment variable PROVISIONING_SCRIPT and set the value to a plain text shell script URL. The file will be downloaded and run on first start of the instance.

​

Base Image

You can find the source code for the Docker images we used to create the Vast templates on GitHub. These are large Docker images that contain CUDA development libraries, node + npm, OpenCL and other useful libraries. Despite their large size you’ll find they generally start quickly because they have been cached on many of the host machines. This makes them ideal for using as a base for your own images.

​

Virtual Machine Templates

Currently we offer two VM templates; A CLI and a desktop GUI. These differ from a standard template because they launch a full virtual machine environment rather than a docker container. You can edit these templates as described above, but you should not change the docker image field. Only the images we distribue from docker.io/vastai/kvm will work, but feel free to add extra environment variables and ports. Use the VM templates when you need to:

• Run applications that require namespace support
• Run more than one Docker container in an instance
• Load kernel modules or run profiling jobs
• Mount remote drives with rclone or similar

​

Advanced Configuration

For advanced template configuration options and variables, please see the Docker Execution Environment guide.