---

name: launch-instance description: "Launch a GPU instance on Vast.ai. Use when the user wants to create, start, or spin up a new GPU machine for training, inference, or development." argument-hint: "[offer-id or requirements]" disable-model-invocation: true allowed-tools: Bash

Launch a Vast.ai GPU Instance

Guide the user through launching a GPU instance on Vast.ai.

User Request

$ARGUMENTS

Instructions

Step 1: Determine the Offer

If the user provided an offer ID (number), use it directly.

If they described requirements, search first:

vastai search offers '<query>' -o 'dph_total'

Present top options and ask the user to pick one.

Step 2: Gather Configuration

| Setting | Flag | Default | |---------|------|---------| | Docker image | --image | Ask user (suggest pytorch/pytorch) | | Disk size | --disk | 64 GB | | Access method | --ssh / --jupyter / --jupyter-lab | --ssh | | Direct connect | --direct | No (not all machines support it) | | Startup script | --onstart-cmd | None | | Environment/ports | --env | None | | Pricing | --bid_price | On-demand (no flag) | | Label | --label | None | | Template | --template_hash | None | | Volume | --create-volume / --link-volume | None | | Mount path | --mount-path | None | | Entrypoint | --entrypoint | Container default | | Container user | --user | root |

Common images: pytorch/pytorch, nvidia/cuda:12.1.0-devel-ubuntu22.04, vllm/vllm-openai:latest, tensorflow/tensorflow:latest-gpu

Step 3: Launch

vastai create instance <OFFER_ID> \
  --image <IMAGE> \
  --disk <GB> \
  --ssh \
  [--env '<DOCKER_OPTS>'] \
  [--onstart-cmd '<SCRIPT>'] \
  [--label '<NAME>']

Alternatively, auto-select an offer:

vastai launch instance -g <GPU_NAME> -n <NUM_GPUS> -i <IMAGE> -d <DISK> --ssh

Step 4: Verify & Connect

After creation succeeds (note the new_contract instance ID):

# Wait for running status
vastai show instances

# Get SSH connection
vastai ssh-url <INSTANCE_ID>

Provide the user with the SSH command or Jupyter URL.

Step 5: Volume Setup (if needed)

# With new volume
vastai create instance <OFFER_ID> --image <IMG> --ssh --disk 64 \
  --create-volume <VOLUME_OFFER_ID> --volume-size 100 --mount-path /root/data

# With existing volume
vastai create instance <OFFER_ID> --image <IMG> --ssh --disk 64 \
  --link-volume <VOLUME_ID> --mount-path /root/data

Safety

• Always confirm offer ID and $/hr cost before creating
• Remind user to vastai destroy instance <ID> when done
• Warn about interruptible instances losing work if preempted
• For spot: use --bid_price — if bid is too low, instance won't start