runpod

runpod

RunPod operations for generic container workloads. Turn workload requirements into one bounded, verified allocation; diagnose it without leaking credentials or burning through repeated guesses; prove the immutable result; then clean up compute and evidence. Provider documentation supplies the current interface; this skill supplies the safety gates and battle-tested operating sequence.

When to use this skill

• Inspect RunPod balance, spend, Pods, network volumes, datacenters, or live GPU inventory before a workload is allocated.
• Compare alternative GPU types or regions against VRAM, CUDA, cloud tier, price, stock, ports, and storage locality.
• Create or update a Pod/template from a pinned public or private image.
• Debug a Pod with missing storage, no ports, slow image pull, restart loop, provider/application log disagreement, or a proxy that does not answer.
• Connect to one explicitly approved interactive Pod to iterate on a workload, then convert the result back into an immutable deployment.
• Validate HTTP proxy isolation, workload cancellation, evidence artifacts, billing, deletion, and authoritative zero-Pod cleanup.
• Cross-references:
  • Choose uv versus Docker, pin the base image/CUDA contract, and establish local-to-remote parity first with environments.
  • Build application Dockerfiles or multi-container wiring with integration.
  • Use cloud-run for Google Cloud Run and a framework skill such as lerobot, isaac-sim, or isaac-lab for workload mechanics.

Key directives

• Delegation posture: embed + links. Embed RunPod-specific safety, selection, verification, and recovery patterns here; verify changing CLI, REST, GraphQL, pricing, and product behavior against official RunPod documentation before acting.
• Inventory first; allocate only after an explicit paid-compute gate. Read balance/current spend, running Pods, persistent storage, exact GPU IDs, stock, price, and datacenter locality before proposing one bounded resource. Stop if credentials, funding, licensing, or required infrastructure are unavailable. Approval names the allocation and lifetime; it is not blanket permission for retries.
• Treat accepted create inputs as unverified until a safe-field re-read. Compare the resulting Pod's exact image digest, GPU ID/count, cloud tier, datacenter, network-volume ID, mount path, ports, registry auth identity, operational mode, and termination time. Delete a mismatched Pod instead of debugging it as though the request succeeded.
• Never print a full authenticated Pod or environment object. Provider responses can contain injected credentials. Query an explicit allowlist, redact values, and keep API keys out of URLs, shell history, evidence, and committed files.
• Use multiple startup signals before classifying or terminating. Combine safe control-plane state, system logs, container logs, storage identity, durable phase/failure markers, object timestamps, and a health endpoint. runtime: null, missing ports, or repeated start events alone do not distinguish a cold pull from a crash loop.
• Interactive overlays diagnose; only an exact immutable rerun proves. Bound interactive work by one approved Pod and deadline. Apply reviewed source overlays only to isolate defects, then rebuild and rerun the clean digest without diagnostic bypasses before claiming deployment readiness.
• Cleanup and production enablement are separate gates. Download and validate evidence, record the observed cost window, delete temporary objects and Pods, and verify zero Pods. Never enable production as a side effect of a passing feasibility or proxy test; require separate explicit approval.

Quick start

1. Write the allocation contract before touching paid compute. Record:

• workload and acceptance test;
• minimum VRAM/GPU architecture/CUDA support and GPU count;
• immutable image digest and registry credential identity;
• required network volume, mount path, region, ports, and cloud tier;
• maximum hourly price, total budget, deadline, and termination control;
• operational mode flags, especially the production-disabled value.

2. Run read-only inventory. Current official CLI surfaces, directly verified 2026-08-24:

runpodctl user
runpodctl pod list --all
runpodctl network-volume list
runpodctl gpu list --include-unavailable
runpodctl datacenter list

Do not paste full output into chat or logs. Extract only the safe fields needed for the decision. See references/provisioning.md for the contract worksheet, interface selection, and volume-aware placement flow.

3. Stop for paid approval. Present one candidate with exact GPU ID, region, cloud tier, volume, image digest, price, and lifetime. If approved, create one Pod and immediately perform the exact post-create comparison.

4. Monitor and validate. Use references/diagnostics-and-lifecycle.md for the multi-signal startup tree, bounded interactive loop, service/proxy tests, artifact checks, billing, and cleanup.

Usage patterns

Choose a GPU and region

Start from the workload floor, not a favorite SKU. Filter live inventory by VRAM, architecture/CUDA compatibility, GPU count, cloud tier, and price. Then intersect with datacenters that satisfy the volume and networking contract. Report unavailable candidates separately from incompatible ones; “no stock” and “wrong region for the volume” require different fixes.

Network volumes are a placement constraint, not an afterthought. Official RunPod storage guidance says Pod network volumes are Secure Cloud resources, available GPU choices depend on the volume location, and the volume must be attached at deployment. See references/provisioning.md.

Provision an exact contract

Prefer the simplest current official interface that exposes every required field. The CLI is convenient; REST and GraphQL offer explicit object fields; SDKs can make repeated automation safer. Do not assume those interfaces are behaviorally identical. Verify current help/schema, submit once, and re-read the created object with network-volume details included.

Issue #69 evidence (2026-08-24): runpodctl v2.8 accepted network-volume flags but two Pods reported networkVolume: null; direct REST rejected the live inventory's exact Server Edition GPU ID; the official GraphQL create mutation expressed the full contract and attached the volume when passed the exact GPU ID, networkVolumeId, volumeInGb: 0, and volumeMountPath. Treat this as dated provider behavior and a permanent reason to verify, not a rule that GraphQL is always required.

Diagnose a slow or restarting Pod

Large private images may take many minutes to pull. Repeated “start container” events may instead indicate restarts. Check both provider log types: system logs describe lifecycle events; container logs contain application stdout and stderr. Confirm storage attachment and durable markers before changing GPU or image. Preserve the exact bounded error, ruled-out causes, and timestamps.

Iterate interactively without losing immutability

When repeated rebuild/pull cycles dominate diagnosis, request approval for one time-bounded interactive Pod. Confirm its contract first; use SSH, Web Terminal, or a durable command/evidence channel supported by the workload. Overlay only reviewed source, run focused checks, and stop once the defect is isolated. Commit the fix, rebuild the image, and repeat the acceptance test from the exact digest. Never promote the overlay result itself.

Validate a service and close the allocation

Test localhost inside the Pod before the provider proxy. Then test the public URL, authentication/capability isolation, expected success path, foreign-scope denial, cancellation, and return-to-ready behavior as applicable. Hash downloaded evidence independently. Query billing for the observed time window, delete the Pod, and re-list all Pods. Persistent volumes keep accruing storage cost until intentionally deleted; do not delete them unless that destructive scope was explicitly approved.

Platform gotchas

• Exact GPU IDs are provider data. Use live gpuId values from inventory. Display names, REST enums, GraphQL IDs, and marketing names can differ or drift.
• Volume attachment changes placement and lifecycle. Network volumes constrain the Pod to their datacenter and must be attached at creation. Official docs say Pods with network volumes cannot use the ordinary stop lifecycle; terminate compute while preserving the independent volume.
• A template is not the resulting Pod. Re-read the allocated resource even when the template was re-read just before creation. Provider defaults or interface omissions can still change image, volume, ports, or mode.
• RunPod exposes system and container logs separately. A healthy image pull can have no application output; a restart loop can repeat system start events. Inspect both before attributing the delay to capacity or CUDA.
• Proxy access requires a declared HTTP port. Current official CLI docs use https://<pod-id>-<port>.proxy.runpod.net; declare ports at creation and verify localhost before proxy behavior. Workload authentication remains your responsibility.
• Editing/resetting can erase nonpersistent data. Export evidence first and know whether data lives on container disk, Pod volume, or network volume.
• Balance and storage outlive the Pod. Compute deletion does not remove a network volume or its hourly storage charge. Low balance can stop or terminate compute and eventually endanger persistent data; keep external backups.

Customization

• CPU workload: use the same approval, exact-object verification, diagnostics, and cleanup sequence; omit GPU/CUDA fields and validate the CPU flavor instead.
• Spot workload: add interruption handling, resumable checkpoints, and an external source of truth. Do not use interruptible compute for a one-shot acceptance gate unless the protocol explicitly allows restart.
• No persistent data: omit volumes, keep artifacts external, and confirm the container/Pod disk loss semantics before deletion or reset.
• Private registry: identify the registry credential by provider-side ID; never materialize its secret in a command, Pod readback, or evidence bundle.
• Different service protocol: HTTP proxy guidance applies only to declared HTTP services. For TCP/SSH/WebSocket details, verify the current official connection documentation and test the actual protocol end to end.

References

• references/provisioning.md: safe inventory, workload contract, interface choice, network-volume placement, immutable image creation, and post-create verification. Read before any allocation.
• references/diagnostics-and-lifecycle.md: multi-signal startup diagnosis, interactive iteration, proxy/cancellation validation, evidence, cost, and cleanup. Read after a Pod is created or when one is unhealthy.
• Upstream: RunPod CLI reference, Pod management, Pod REST create API, GraphQL Pod management, live GraphQL schema, network volumes, and billing. Interface claims in this version were directly fetched from these official pages on 2026-08-24; re-verify before paid operations.
• Evidence: Robium issue #69 and learnings/2026-08-24-vla-pick-and-place.md entries lrn-0824-05 through lrn-0824-29. Sibling skills: environments, integration, cloud-run, testing, and the workload-specific framework skills.

Changelog

• 0.1.0 (2026-08-24): created as the generic RunPod operations owner; absorbs issue #69's volume-verification, safe-diagnostics, interactive-iteration, immutable-revalidation, proxy/cancellation, cost, cleanup, and production-gate evidence while delegating changing provider syntax to official documentation.