runpod-usage

SKILL.md

Runpod usage (concepts)

Background knowledge for making the right choice before you act. This skill runs
nothing — once you know what to do, execute with runpod-mcp/runpodctl
(infra), flash (your own code), or companion-clis (models/images/data).

This skill explains; the golden paths demonstrate. When the question is really "how do I
do X" rather than "how does X work", the verified end-to-end example is the faster answer —
runpod/golden-paths/README.md. Read the concept here, then
follow the path.

Read the one reference file that matches the question:

Question
Read

First-run setup / auth — get + set RUNPOD_API_KEY, SSH, companion creds
reference/getting-started.md

Pods vs serverless, workers, cold starts, FlashBoot, queue vs load-balanced
reference/concepts.md

The development loop for ANY workload (start here) — plan → prefer prebuilt → provision → verify → teardown
reference/development-loop.md

Stand up / iterate a workload on a pod — the pod sub-loop
reference/pod-workflows.md

Deploy / iterate a serverless endpoint — Hub vs flash vs custom, invoke + verify
reference/endpoint-workflows.md

Install software on a pod — package hygiene, uv, non-interactive, caching
reference/on-pod-setup.md

Build a Docker image Runpod can run (handler contract, Dockerfile, --platform=linux/amd64)
reference/docker.md

How to build an image well — base image, layering, bake-in vs volume, pod vs serverless (queue/LB) contract
reference/building-images.md

Where data lives — container disk vs network volume, model caching, S3 access
reference/storage.md

Which GPU / how much VRAM / which CUDA version / cost & availability / data centers
reference/gpu-selection.md

Why a stopped pod may not restart with a GPU — pods are bound to one machine; what else is per machine
reference/pods-and-machines.md

Endpoint releases, rolling updates, version overlap, GitHub builds
reference/endpoint-builds-and-releases.md

Storing API tokens and keys as secrets and referencing them from env vars
reference/secrets.md

Reaching a pod or endpoint over HTTP (proxy URLs, exposed ports)
reference/networking.md

Common mistakes and how to avoid them
reference/gotchas.md

Exact facts: the concept files

The reference files explain. For a precise fact, or a rule an action must satisfy, read
the concept files in concepts/ next to this file. There is one YAML file per concept
(pod.yaml, network-volume.yaml, machine.yaml, …), each with its fields, states,
relations and rules, and every rule cites the public source it comes from.

grep -il "volume disk" concepts/*.yaml    # find the concept by name or alias
grep -n "statement:" concepts/pod-volume-disk.yaml

rules[].statement is the fact. see: points at related rules on other concepts.

A rule with conflict: true records two public sources that disagree. Give both readings.

A kind: process file explains a flow step by step. pod-deployment.yaml covers deploy,
stop and restart, including why a restart can fail while the data center has stock.