Your first GPU run

Walk through a complete GPU run from prompt to output.

Prerequisites

A Volspan account with Vault balance
An API key created in the dashboard
MCP configured in your agent client

Example: generate an image with SDXL

Ask your agent something like:

“Generate an image of a mountain landscape at sunset using Stable Diffusion XL. Use an A100 GPU.”

Your agent will compose Python code and call run_on_gpu:

from diffusers import StableDiffusionXLPipeline
import torch

pipe = StableDiffusionXLPipeline.from_pretrained(
    "stabilityai/stable-diffusion-xl-base-1.0",
    torch_dtype=torch.float16
).to("cuda")

image = pipe("mountain landscape at sunset, photorealistic").images[0]
image.save("/output/landscape.png")

What happens behind the scenes

1. Submit

Your code is SHA-256 hashed (we never store raw code). A Vault reserve is placed for the estimated cost.

2. Provision

A RunPod serverless worker spins up with the requested GPU tier. Cold starts are typically 5-15 seconds.

3. Execute

Your code runs in an isolated container with full GPU access. stdout/stderr stream to R2 storage.

4. Upload

Any files written to /output/ are uploaded to R2 and returned as signed artifact URLs.

5. Settle

Actual compute time is billed per-second. The reserve is settled to the exact amount and any excess is released back to your Vault.

Reading the output

The run response contains:

{
  "run_id": "run_8Kx2mP...",
  "status": "complete",
  "duration_seconds": 47,
  "cost_cents": 28,
  "stdout": "Image generated successfully\n",
  "stderr": "",
  "artifacts": [
    {
      "filename": "landscape.png",
      "url": "https://r2.volspan.dev/run_8Kx2mP.../landscape.png",
      "size_bytes": 2841600
    }
  ]
}

stdout — everything your code printed
artifacts — signed URLs for files in /output/
cost_cents — exact cost in cents deducted from your Vault

Common first-run issues

INSUFFICIENT_BALANCE

Your Vault doesn't have enough credit for the estimated run cost. Add funds in the dashboard.

Timeout after 300s

The default timeout is 5 minutes. For long-running tasks like model downloads, pass a higher timeout value.

ModuleNotFoundError

The base image includes PyTorch, numpy, and common ML libraries. For others, pass them in the packages parameter.

MCP tool not showing up

Restart your agent client after editing the MCP config. Check that your API key is valid and starts with vc_live_.

Need help? Reach out at [email protected]