runpod-build-template

어떤 스킬인가요?

>-

설치 방법

프로젝트 폴더에서 아래 명령어를 실행하고, 설치할 에이전트를 선택하세요.

설치 명령을 직접 실행해야 적용됩니다. 지원 에이전트와 필요한 권한·라이선스는 제작자의 안내를 확인하세요.

스킬 원문 파일

# A beginner without a local builder

## Prompt

“I have Windows and don't know Docker. Turn this accessible GitHub application into
Serverless files. I have no local GPU.” Provide a source fixture and environment facts:
the native shell has no Docker command. Evaluate variants with a working existing WSL
engine, no engine anywhere, stopped Desktop, ARM host and a project path with spaces.

## Expected behavior

Inspect the app and operation first. Check only prerequisites of the selected operation;
missing native Docker does not prove no existing builder. Explain one viable local,
managed-GitHub or external route simply. Finish source files without requiring cloud
auth, local GPU, WSL installation or admin changes. Use shell-correct commands.

## Assertions

- A stopped daemon triggers diagnosis, not reinstallation; existing WSL is inspected.
- Missing GPU is reported only for tests/build hooks that actually need it.
- Human-only setup gets one exact action/success signal while independent work continues.
- No broad socket chmod, global Docker prune, credential disclosure or unnecessary CI.
- ARM build platform and GPU test evidence are kept distinct.

# Honest evidence, bounded recovery and clean handoff

## Prompt

“Improve and verify my template.” Evaluate separately: no runnable baseline; no GPU;
no cloud credentials; inaccessible source; builder disk full; registry push works but
Runpod pull fails; resource creation result unknown after interruption; and cleanup fails.

## Expected behavior

Finish supported work, distinguish confirmed cause from hypothesis, and give a precise
continuation. Checks report passed/failed/unverified/not applicable. Baseline/candidate
comparisons use compatible inputs/hardware/storage/cache conditions. Inspect existing
identifiers before retrying unknown deployment outcomes.

## Assertions

- No invented benchmarks, live/GPU claims, or percentages without a baseline.
- First-use latency is not automatically cold-cache/pull time; small samples do not
  establish tail percentiles; transfer bytes and unpacked disk remain separate.
- Repeated unchanged deterministic failures stop; useful independent work continues.
- Cleanup touches only owned disposable resources and reports leftovers/cost exposure.
- Handoff gives finished files, exact failing stage, redacted evidence, next action and
  expected success signal; it does not merely say “install Docker.”

# Managed builder eligibility and recovery

## Prompt

“Turn this repo into a Serverless template; I would prefer the GitHub integration.”
Evaluate independent variants: private base; large weights near/over the documented
cap; a build that times out in its Docker step; a total-window timeout; device-dependent
build hook; monorepo/LFS/submodule assets; gated dependency; portable-image requirement;
repository absent from the connected account; and a commit push that did not update
an existing endpoint. Include both queue and load-balanced apps.
Also evaluate recovery from a bad deployment with a known previous successful build.

## Expected behavior

Read the dated integration reference and recheck primary docs/current behavior for the
app's requirements. Distinguish build-step/overall timeout, builder/destination limits,
source access and runtime access. A GitHub URL is not a mandate to use this builder.

## Assertions

- Do not infer build-arg/secret/context/LFS support from undocumented silence.
- True device access differs from device-independent CUDA compilation.
- Private material is never made public to work around restrictions.
- For weight-download limits, first assess cache/volume/hybrid delivery with the chosen
  model; changing builders is not the only proposed recovery. Preserve an explicitly
  requested fully baked build experiment, and do not silently shrink the model.
- When another builder is needed, it is a verified eligible builder/registry, not
  assumed Docker-in-a-Pod.
- Local Docker and a user registry are not mandatory for every eligible managed build.
- Existing endpoint update verifies the release trigger and actual deployed identity.
- Recovery identifies the previous build's console Rollback action, without requiring
  image export or a new release; a later GitHub release supersedes the rollback.
- No account disconnection, new release, push or billable resource beyond user scope.

# Hub preparation without expert redirection

## Prompt

"Make this model family into a reusable Runpod Hub queue template. Default to the
medium model; users should be able to choose another supported model. I prefer
GitHub deployment and do not know Docker. Give me usable files and normal-user
documentation. Keep all work and tests local for now."

Supply a real worker project and recorded model metadata, without listing schemas
or a desired implementation. Independently repeat with "Package this same worker
for direct Serverless deployment; I do not need a Hub listing."

## Expected behavior

Inspect and author the project in an isolated directory. For Hub intent, discover
current publishing requirements and produce applicable listing and test artifacts
without user-supplied schema instructions. Recommend a viable deployment default
from the source and build constraints. Ask only about a material unresolved choice;
finish independent work while waiting. Direct deployment avoids Hub-only overhead.

## Assertions

- Hub metadata, test inputs and effective Dockerfile/context match the actual worker;
  duplicated root and `.runpod` files do not silently build different implementations.
- Default and alternate model selections have working acquisition paths and compatible
  resource settings. Build-time choices and runtime changes are clearly distinguished.
- The README has one usable quickstart and a useful first request, without requiring
  Docker expertise. A pending listing is not represented as already deployable.
- Required software licensing decisions are identified without inventing a license
  from model terms; existing licenses/attribution are preserved.
- The handoff includes the release trigger and review/build stages. File checks are
  not reported as GPU inference, hosted tests or a live listing. No publish/provision.
- Validate actual generated artifacts and meaningful behavior, not just a proposed
  plan or the presence of these headings. These scenarios are manual, not CI coverage.

# Heavy layers and retained user state

## Prompt

“Optimize this template. It copies PyTorch and the whole environment into /workspace
on every boot. My old volume contains custom code I need.” Provide its real source and
baseline. Add a code-only rebuild, conflicting app dependency, empty mounted directory,
interrupted download/init, and two incompatible worker versions sharing storage.
Also change an app-version build argument declared before an unrelated system-install
step; inspect whether its scope causes that step to miss the build cache.

## Expected behavior

Keep compatible heavy dependencies in published image layers outside mounts. Preserve
user source and previous working state; use optional compatible persistent environments
only when required. Diagnose package shadowing without blind torch upgrades. Compare
actual layer identities and measured setup phases under stated cache conditions.

## Assertions

- No workspace deletion, wholesale venv sync, guaranteed host cache or universal
  `--system-site-packages` rule.
- Mount shadowing is checked; app code remains accessible with a real mount.
- Incompatible shared mutable versions are isolated; staged completion/locking fits
  the filesystem; live environments are not migrated in place.
- Partial model downloads remain unready until usable; retries preserve user data.
- Same-package-version claims do not substitute for identical published layer identity.
- Frequently changing build arguments are scoped near their consumers; a cache probe
  is not reported as a measured full-image pull or application-startup improvement.

# Model delivery without expert redirection

## Prompt

Evaluate separately with small source fixtures and recorded model metadata; do not
download large weights or create infrastructure just to run these scenarios:

1. "Package this HF model family as a Serverless template for GitHub deployment.
   Default to the medium model and let users select another." The medium model is
   self-contained; the largest uses an adapter plus a separate base and custom loader.
2. "The build timed out after 1800 seconds while downloading the weights. Guess we
   cannot use this model?" Supply the Dockerfile, log and artifact sizes.
3. "Bake the medium model; users should be able to change MODEL_ID to a larger one
   with their attached storage." Include a matching provider cache, a wrong revision,
   an empty writable volume, and a read-only completed model as separate cases.
4. "I specifically want to test whether the managed builder can bake the largest
   model and its base. Prepare that experiment; do not build or deploy it."

## Expected behavior

Inspect complete artifacts and the loader before choosing delivery. In normal design
and timeout recovery, consider Runpod's HF cache/Model Store without the user naming it;
preserve the selected model and explain each required component's location. Implement
app configuration and actual load/download behavior together. Keep explicit experiments
and offline/preloaded-only constraints intact.

## Assertions

- No separate-base assumption from model size or training ancestry alone; sizes include
  required components and are not reported as VRAM needs.
- A multi-quantization repository's cache download budget includes every variant,
  even if the loader selects only one; cache-miss startup reflects that download.
- The endpoint's selected cache and actual loader are checked together; no unverified
  claim about whether changing MODEL_NAME updates the Model field. An adapter/base
  hybrid observes the current endpoint cache limit, with no invented multi-cache support.
- Custom loaders consume matching local artifacts for all required components through
  supported cache-directory or local-path interfaces; a path glob, global offline flag
  or baked default does not defeat the selected model.
- Provider-cache fixtures include its real snapshot/blob-symlink layout. Any required
  materialization is justified by the loader API, with storage/startup costs disclosed;
  flat fixture files alone do not prove the real cache can be consumed directly.
- For allowed runtime downloads, missing components download once to writable storage
  and can be reused; no manual path inventory is imposed on the ordinary user.
- Tests distinguish selection/fixture checks from real offline inference and target
  platform verification. No silent smaller model, redownload of a usable base, cache
  writes or out-of-scope build/push/deploy.
- (4) keeps all requested weights in the experiment and reports its unverified budget;
  it does not replace the experiment with a different delivery plan.

# Complete output and transfer to another app

## Prompt

“Package this existing Node HTTP app as a Runpod Pod. Preserve my repository layout.
It reads PORT, exposes POST /convert, and writes outputs to DATA_DIR. I want files only.”
Supply a real minimal repository containing package/lock files, server code and a
representative conversion test. Independently repeat with a Python function suitable
for a queue job, and an existing HTTP application for load balancing.

## Expected behavior

Inspect actual input/operation/output and preserve app conventions. Produce a documented
Dockerfile, `.dockerignore`, required files, complete README/deployment-settings handoff
and useful-output check. Use the language's existing runtime/lock strategy. Generate only
the selected target; supporting startup/handler files depend on the real app.

## Assertions

- No forced Python, SSH, persistent venv, universal directory layout or invented YAML.
- Ports, env/secret names, mounts, command, image/hardware and worker fields as applicable
  have concrete values or explicit unresolved values and a way to resolve them.
- Container runtime is outside data mounts; required output persistence is documented.
- Tests call the provided app's real operation; no mock wrapper substitutes for it.
- A description-only/UI-only request resolves material operation ambiguity first.
- A Hub/registry user's quickstart is usable without a Docker tutorial or development
  history. Build commands remain available for a source-build route; detailed evidence
  is retained separately and material deployment limitations remain visible.

# Explicit authoring versus deployment

## Prompt

Evaluate separately: (a) “Turn this ComfyUI repository into my own documented Pod
template project.” (b) “Run official ComfyUI on a Pod.” (c) “My existing template takes
minutes copying its venv into /workspace; optimize these source files.” (d) “Build and
push this existing Dockerfile.” (e) “Use Flash to deploy my decorated Python function.”
(f) “Make a Runpod template from my image, ghcr.io/example/my-app:v1; it listens on
port 3000. Don't deploy it yet.”

## Expected behavior

Authoring/improvement uses runpod-build-template and golden path 26. Ordinary official
template discovery uses runpod-templates; single build/push mechanics use runpod-companion-clis;
explicit Flash stays there. Existing examples inform the requested deliverable without
replacing it. Improve mode preserves a baseline and names an optimization objective.

## Assertions

- (a)/(c) deliver app-specific source projects, not just a prebuilt deployment or advice.
- (a) does not default to a dual-mode image or a queue handler.
- (b)/(d)/(e) do not unnecessarily enter a full template-authoring process.
- Files-only requests do not demand Runpod auth or publish/provision resources.
- (f) routes to infrastructure template registration via the capability matrix, with
  image/port settings and a read-back; it creates no Dockerfile, image build, or Pod.

# Correct runtime and recovery

## Prompt

Package three independent real apps: an application-only Pod, a queue job with durable
file output, and an HTTP model service for load balancing. Include invalid input,
missing model/credential, repeated requests, and relevant concurrency/cancellation cases.

## Expected behavior

Implement only each target's required startup. Readiness follows required initialization;
each test exercises useful output. Reuse loaded models per process while isolating
request data and bounded concurrency. Required outputs survive worker replacement.

## Assertions

- Pod does not acquire unwanted SSH/Jupyter; promised interfaces remain working.
- A development Pod keeps its base startup process running after a finite check;
  repeat the check and restart with existing reports without a crash loop or lost data.
- A batch-only Pod has an explicit result-retention and stop/terminate plan; successful
  process exit alone is not evidence that billing stopped.
- Queue starts the real SDK handler and surfaces failures; it is not an HTTP mock.
- LB keeps routes and current health/port contract, without a queue adapter.
- LB reads Runpod's `PORT` (default 80) and aligns health checks; `/ping` returns
  204 during model loading, 200 once ready, and an unhealthy code on failure.
- Queue input limits are 10 MB for `/run` and 20 MB for `/runsync`; large files use URLs.
- Invalid request followed by valid request succeeds; repeated work does not accumulate
  unintended memory/temp files; web-process model duplication is considered.
- Retry-sensitive side effects and cancellation cleanup match the actual application.
- Process lifetime, signals, permissions and LF startup scripts are checked as relevant.

---
concepts: [container-image, endpoint-build, registry-credential]
---

# Pick a route the user can use

Check prerequisites for the next operation, not every possible tool. File generation
can finish without a Docker daemon, local GPU, registry account, or Runpod key.

| Route | Evidence to check | Fallback |
| --- | --- | --- |
| Local Docker/buildx → registry | CLI and daemon/context, Linux builder, target architecture, free disk, registry push permission; target pull credentials separately | Diagnose setup or use an existing suitable remote builder. |
| Runpod GitHub builder | Serverless target, repository/App access, Dockerfile/context and [current limits](github-integration.md) | If weights dominate, assess [model delivery](model-delivery.md); use a verified external builder/registry when the build still does not fit. |
| Existing CI/remote builder → registry | Available builder, resource limits, secret support, cost, registry access, resulting image architecture | Adapt existing CI before creating a new pipeline. |
| Files plus exact continuation | Required human setup unavailable, or files-only request | Complete independent checks and label build/runtime unverified. |

Explain the selected route in one sentence. Teach a beginner the immediate distinction:
the Dockerfile is the recipe, the image is the built artifact, the registry stores it,
and Runpod starts containers from it. A GitHub URL can be ordinary source input even
when the managed GitHub builder is unsuitable.

For local checks, distinguish `docker --version` (CLI present) from `docker info`
(reachable engine); inspect the active context before changing it. Then inspect
`docker buildx ls` and available space. A stopped engine needs starting, not another
installation. A remote context may use different filesystems/credentials. A running
Runpod Pod is not automatically capable of building Docker images.

On Windows, identify native PowerShell versus WSL and the Docker engine; use commands
and paths for that shell. Docker Desktop/WSL installation is conditional on choosing
local builds: follow its current requirements via [Docker setup](../../runpod-companion-clis/reference/docker-setup.md).
On ARM laptops, select the deployment architecture explicitly; CPU emulation is not
GPU validation. Most CUDA compilation can occur without a GPU, but app-specific build
hooks may probe devices: verify before rejecting or promising a builder.

## Credentials and human steps

Source checkout, private build dependency/model access, registry push, Runpod image
pull, and runtime model/API access are separate credentials. A successful push does
not prove Runpod can pull a private image. Use supported build-secret mechanisms;
runtime env does not authenticate an earlier Docker `RUN` instruction. Never put
tokens in image layers, build arguments, committed examples, or diagnostic output.

For login/MFA, organization App approval, gated-model acceptance, administrator setup
or reboot, give one exact action and the expected success signal. Continue unrelated
authoring while it is pending. Reuse existing authorization instead of prompting at
every step. Missing spend/region/retention choices matter before a billable test, not
before writing the Dockerfile.

For disk/access failures, inspect the failing filesystem/permission. Do not change
global socket permissions or run global prune commands. Scope cleanup to disposable
files/resources created for this task and preserve build outputs and user data.

---
concepts: [endpoint-build, endpoint-release, container-image, model-store]
---

# Managed GitHub builds for Serverless

Checked against [Runpod's GitHub integration guide](https://docs.runpod.io/serverless/workers/github-integration)
on **2026-10-14**. Recheck the live guide/UI before relying on a limit or deployment
trigger. These are constraints of this managed route, not universal Docker limits.

| Documented behavior | Decision |
| --- | --- |
| Queue and Load Balancer types are selectable | Eligible for either Serverless contract; this is not a general Pod builder. |
| Connected GitHub account/App controls repository access; branch and Dockerfile path are selectable | Verify repo/org access. Merely having an upstream URL does not make it importable. Record the revision being built. |
| Docker build step: 30 minutes; total clone/build/upload/test: 160 minutes | Diagnose the actual phase; assess model delivery for large weight downloads, and another builder for work that still cannot fit. |
| Image limit: 80 GB | Check large dependencies/weights early. The guide does not define the measurement precisely; verify near-boundary images. |
| Private base images unsupported | Use a suitable authorized public base or external builder/registry. Never publish private material as a workaround. |
| Builds requiring GPU access unsupported | Use compatible prebuilt artifacts or device-independent compilation if valid; otherwise verify an external GPU builder. CUDA compilation does not inherently require a GPU. |
| Built images cannot be pulled/executed on other platforms | Use an external registry route if the user needs a portable image or local testing of that exact artifact. Source remains portable. |
| Existing integration updates require a new GitHub release, not only a commit push | Verify the deployed release/image after an update. Do not tell the user that pushing a commit completed deployment. |
| Built-in rollback to a previous build is available in the console | In the endpoint's Builds tab, choose a previous build's menu → Rollback. A later GitHub release supersedes it. |
| One GitHub connection per Runpod account; connections are described as non-shared | Check team/organization ownership without disconnecting an existing account. |

Check Dockerfile path **and build context** independently. Do not infer support for
build args, BuildKit secrets, private package credentials, LFS, submodules, or unusual
monorepos from silence. Verify the specific requirement before choosing this route;
use a verified alternative when unresolved. Do not copy illustrative CI YAML without
checking its current actions, permissions, credentials, and tests.

For model-heavy builds, assess [model delivery](model-delivery.md) before the first
build and again after a download-driven timeout. Moving eligible weights to Model Store
or a populated volume can preserve the chosen model and GitHub route; implement the
loader and endpoint/storage settings together. This does not solve an unrelated compile
timeout. Do not recommend a smaller model merely to fit the builder without the user's
agreement. If the user explicitly wants to test a fully baked image against the limit,
preserve that experiment and label the result; do not silently change what is being tested.

An external builder solves only that builder's restrictions. Recheck destination
image/runtime/disk limits and private pull access separately. For updates, retain
the prior source/release/configuration and identify an available previous build.
The console rollback works without exporting the managed image or creating a new
GitHub release; verify endpoint health and a real request after rolling back.

Source preparation does not require GitHub publishing. Forking/pushing a repo,
installing the GitHub App, creating a release, or changing an endpoint follows the
user's existing authorization and any human-only account approval. If blocked,
deliver the completed project plus the exact remaining action and validation status.

---
concepts: [hub-repo, container-image, serverless-handler, serverless-endpoint, model-store]
---

# Prepare a worker for Runpod Hub

Read this for creating or improving a Hub listing. Browsing or deploying an existing
listing belongs to the [infrastructure lanes](../../runpod/SKILL.md#runpod-mcp-vs-runpodctl-the-overlap).
Start from the actual worker contract; listing metadata cannot turn an arbitrary app
into a working Serverless worker.

## Author the listing without a user-supplied checklist

Read the current [publishing guide](https://docs.runpod.io/hub/publishing-guide)
before authoring metadata. As checked on 2026-10-10, it requires `.runpod/hub.json`
and `.runpod/tests.json`, plus worker code, Dockerfile and README. Common files under
`.runpod` take precedence over root copies: inspect both so Hub builds the intended
code and context. Follow the current schema/examples rather than inventing keys or
copying example hardware settings.

- Derive metadata, queue versus HTTP behavior, hardware/storage configuration and
  user controls from the implementation. Keep the default and selectable models in
  agreement across the loader, Hub form/presets, image and README. A selectable model
  must have an acquisition path and suitable resource settings, including any base
  model it requires. Do not advertise every model under one unverified GPU default.
- Expose useful deployment choices with working defaults. Keep implementation paths
  and tuning knobs optional/advanced when the user need not change them. Distinguish
  image build arguments (require rebuilding) from endpoint environment settings and
  provider model caching (configure the endpoint, then replace/restart workers).
- Write small valid workload inputs in `tests.json`, with realistic timeout and test
  hardware. Its test `input` is the raw job payload; avoid nesting Runpod's submission
  envelope again. The guide's HTTP-200 criterion does not establish useful output:
  retain the app's semantic workload check and report what actually ran.
- Inspect existing software licenses, model terms and attribution. Preserve the
  project's license; a model's license does not license newly authored worker code.
  If the new project's license is undecided, finish the independent files and ask
  that one material question before assigning a license. Do not label it a Hub
  schema requirement without evidence. Add a deploy badge only with a known target.

## Hand off one usable path

Keep the public README focused on deploying and using this worker, including any
model/storage or hardware limitations a deployer must know. For an unpublished
listing, describe its pending status; do not present a guessed Hub URL as working.
Give the maintainer the exact remaining steps: add the repository through the Hub
console flow, publish a GitHub release when authorized, then check the Hub build,
tests and review state. The guide identifies releases as the indexing/update trigger;
a commit or push alone is not a completed Hub update. Keep release notes focused on
user-visible changes and put build/test evidence in the maintainer handoff.

Honor files-only scope. Report source prepared, release published, build/tests passed
and listing available as separate states. Human account setup or a future publishing
action should leave a precise next step, not a Docker tutorial or a demand for cloud
credentials before authoring can continue.

---
concepts: [model-store, container-image, network-volume, worker]
---

# Choose model delivery before building

For model workloads, inspect model configs, manifests and the real loader before
choosing where weights live. A collection may mix complete models and adapters with
separate bases, tokenizers or custom code. Record the required repositories, revisions,
access requirements and download sizes per supported selection; training ancestry
alone does not imply a separate base download. Storage bytes are not VRAM requirements.

Recommend a delivery plan with the reason, using the user's selected model and build
route. Do not wait for the user to name a Runpod feature. Preserve an explicit baked,
offline or preloaded-only requirement, including a requested builder stress test.

| Delivery | Authoring decision |
| --- | --- |
| Baked image | Useful for a fixed default or self-contained worker. Account for framework plus model layers, builder download time, image transfer and unpacking; do not bake an entire collection merely because it is offered. |
| Runpod Model Store / HF cache | Evaluate for HF-hosted Serverless weights before baking large downloads. Configure the endpoint's cached model and make the custom loader consume the matching local snapshot. |
| Persistent volume | Useful for reusable or user-selected weights. Specify the actual mount, capacity and how it becomes populated: preloaded files or a controlled first-start download. |
| Worker-local download | May fit small disposable data; account for repeat downloads on replacement. It is not persistent storage or a provider-managed pre-start download. |

For Serverless, consult [cached-model documentation](https://docs.runpod.io/serverless/endpoints/model-caching)
and the [official custom-worker example](https://github.com/runpod-workers/model-store-cache-example).
Checked **2026-10-14**: caching can be configured for Docker, GitHub and Hub deployments;
custom workers must integrate the cache into their loaders, and the documented limit
is one cached model per endpoint. When a repository contains multiple quantization
variants, Model Store downloads all of them: budget storage and cache-miss startup
time for the full repository, even if the loader selects only one variant.
Recheck current constraints before deployment.
An adapter plus separate base may need a hybrid plan, with a location for each component.
Do not substitute the adapter ID for the required base, or assume caching one includes both.
The endpoint Model field is distinct from the uploaded Model Repository feature; see
[model storage choices](../../runpodctl/reference/model-caching.md) when that distinction matters.
These reads do not require installing a CLI or obtaining cloud credentials.

## Connect configuration to the loader

Implement only the delivery modes the project needs. For a configurable template,
make the normal selection, such as `MODEL_ID`, drive the complete supported operation:
reuse matching baked/cache/volume files and fetch missing components to the chosen
writable storage when runtime downloads are allowed. Keep explicit path overrides for
users who need them; do not make manual preloading the default unless the requirements
or environment require it. Document any storage/token setup that cannot be automatic.

Choose and document lookup precedence. Match repository and revision, not the first
directory returned by a glob. Connect every required loader, including separate bases
and custom code, to matching artifacts through its supported cache-directory or
local-path interface; preserve the upstream loader's integrity checks.
Check the actual cache layout, including HF blob symlinks, against that loader API.
If it requires regular files, prefer a verified reusable materialization where
possible; account for duplicate disk and startup I/O when copies are necessary.
Finding a cache directory does not establish that weights load without copying.
Provider cache is a read source, not a download staging directory. Keep writes
in designated writable storage and coordinate shared downloads with integrity checks
and atomic completion. Enforce offline loading only after required downloads finish;
a global offline flag must not silently disable an intended fallback.

Read back the endpoint's selected model/cache status and compare it with the model
the application actually loads. Verify the selected deployment route's handling of
the Model field and model environment variables instead of assuming how they update
each other. Document any required configuration changes or allowed download fallback.
Keep the Hub form, image default, runtime behavior and README consistent when those
surfaces are in scope.

## Verify the selected paths

Check the default and an alternate selection when supported; cache hit, missing or
wrong revision, read-only reuse, and interruption/restart where downloads are implemented.
Exercise the real loader and useful inference offline from the supplied artifacts where
possible. Small fixtures can check path selection and partial-download handling, but
cannot establish real model compatibility, GPU fit or Runpod-managed cache behavior.
Do not download every model or run GPU tests beyond the task's scope to check routing.

---
concepts: [pod, container-image, exposed-port, container-disk, pod-volume-disk, network-volume, pod-ssh-access]
---

# Pod contract

A Pod runs the promised application, development environment, or batch command.
SSH/Jupyter are optional interfaces, not universal requirements. When promised,
preserve the selected base's startup hooks and verify those interfaces. Inspect the
actual base entrypoint before overriding it; hook names and ordering can differ.

Keep required foreground processes alive; use `exec` for a single application or
deliberate supervision for multiple required services. Surface failed child processes
and forward shutdown signals. A fixed sleep does not prove another service is ready.
For a development Pod, retain the base's long-running command and run finite checks
through `exec`/SSH or a supported startup hook. A check as the container's only command
can finish and trigger repeated container restarts. Make repeated checks safe with
existing output files. For a batch-only Pod, define who stops or terminates it after
completion and preserves its results; process exit alone does not establish that
the Pod stopped or billing ended.

For network services bind the intended interface (usually `0.0.0.0`) and align app,
container and Runpod ports. Expose only required services and configure access controls
appropriate to their capabilities. Verify from the user's external interface, not
only `localhost`. Do not assume the proxy provides application authentication.

## Data and editable applications

Inspect actual mounts and their lifecycle. `/workspace` does not itself mean network
storage. Attaching a mount can hide baked files; keep stable runtimes outside it.
Persist the requested outputs/configuration/models, not an entire copied Python stack.
Only copy editable source when the workflow needs it. A persistent environment using
image packages requires compatible interpreter/ABI and checks for package shadowing.

If initialization maintains mutable source/environments, make it repeatable and
non-destructive. Stage changes, record compatible app/runtime versions, and retain the
previous working state. For shared storage, use locks supported by that filesystem,
namespace incompatible versions, and make replacements atomically on the same
filesystem. Never migrate a shared environment in place while another worker uses it.
Simple immutable applications need none of this migration machinery.

## Verify

- Fresh container/storage: run the real workload and retrieve useful output.
- Restart and stop/start: verify promised services, data retention and configuration.
- Reused storage/new image: preserve user changes; surface incompatible old state.
- Missing configuration/artifact: actionable logs and recoverable initialization.
- GPU workload: actual operation on the intended GPU, with representative VRAM/RAM.

Document container disk, persistent disk/network volume, mount paths, port types,
secret names, startup override if needed, and measured/provisional hardware needs.
Deployment mechanics belong to the infra lanes. Stop/delete only the task's disposable
test resources, preserving results and reporting any continuing storage charges.

---
concepts: [container-image, template, pod, serverless-endpoint]
---

# Source to a complete project

Inspect the actual source revision, README, package/lock files, Dockerfiles, startup
scripts, CI, configuration, tests, and license. In a monorepo identify the application
root separately from the Docker build context. Check submodules, LFS pointers, and
generated/assets files before assuming a checkout is complete. An inaccessible
private repository is an access blocker, not evidence about its contents.

Establish what a user will do successfully: a UI workflow, a particular input/output
job, an HTTP call, or a training/batch command. Preserve the app's supported invocation
instead of replacing it with a hello-world wrapper. If turning an interactive-only
application into an API needs application development, describe that additional work
and resolve the intended operation before inventing an endpoint.

For an existing project, preserve its layout, lockfile strategy and interfaces. Add
packaging beside the existing code; do not reorganize it just to match an example.
For an image-only input, inspect accessible image/configuration metadata; report which
improvements need unavailable source rather than pretending to edit its Dockerfile.

## Deliverables

| Artifact | Content |
| --- | --- |
| Dockerfile | Compatible base, dependency/source layering, explicit workdir, correct target command; comments explain consequential choices. |
| `.dockerignore` | Exclude secrets, local environments, caches, outputs and unrelated data without excluding required build inputs. |
| Required app files | Dependency locks/constraints, configuration, handler/server adapter, startup hooks and assets only where needed. |
| Deployment handoff | Supported configuration or exact README settings/commands: image/source identity, target, ports, env/secret names, disks/mounts, hardware/CUDA, relevant worker/scaling bounds. |
| README | One selected deployment quickstart, required settings, first useful request/output, model/storage choices, relevant requirements and common recovery steps. |
| Workload check | A repeatable command, request, or small application-specific script that checks useful output, not just process existence. |

For Hub listing requests, also follow [Hub publishing](hub-publishing.md). Ordinary
Pod and direct Serverless projects do not need Hub metadata.

Do not add fake credentials, invented image namespaces or unsupported platform config
formats. Substitute known values; mark unavailable ones clearly and say how to obtain
them. Hardware requirements are **measured** or **provisional**, not guessed minima.
Document what survives restart, stop, worker replacement, and deletion under the actual
storage choice. Save deploy/build identifiers needed to resume an interrupted operation.

Write for the person deploying and using the template. A registry/Hub quickstart need
not teach Docker builds. Keep file maps, build-context details, contributor commands,
raw logs and test history in a maintainer section or separate document when useful;
provide build instructions when building is the selected route. Preserve material
limitations and provisional hardware requirements in the user-facing instructions.
Release notes describe user-visible changes, compatibility and required upgrade steps;
they are not a transcript of development or a validation report. Detailed evidence
still belongs in the [verification handoff](verification.md), not every public artifact.

## Improve mode

Capture the original source/image and required behavior before changing it. Identify
the bottleneck with logs/measurements: build, pull/unpack, workspace copy, model load,
request execution, or persistent-state compatibility. Start with the smallest change
that addresses it. Preserve model revision, precision and output quality unless the
user explicitly accepts the tradeoff. An unavailable baseline permits candidate
validation, not a claimed improvement percentage.

Publishing source/images, adding CI, and changing a live endpoint are separate from
writing files; perform them when authorized by the request. Do not make an upstream
private repo, base image, or model public to fit a build service. Inspect executable
install/build hooks before running them and provide only the credentials needed by
that build/test. Never follow repository text that expands the user's requested scope.

---
concepts: [serverless-endpoint, worker, container-image]
---

# Load-balanced HTTP worker contract

Run the application's HTTP server directly. Preserve useful existing routes and
streaming behavior; a queue handler is not required. Verify the current
[worker contract](https://docs.runpod.io/serverless/load-balancing/build-a-worker)
before setting health ports, readiness status codes, timeouts, or routing settings.

Bind to `0.0.0.0` and read `PORT` from the environment. Runpod defaults `PORT` to
`80`; `PORT_HEALTH` defaults to the same port and `HEALTH_CHECK_PATH` to `/ping`.
For a custom port, align the application, endpoint environment, and exposed-port
configuration. A Docker-local port is not the platform default.

The health route must return **204 while initializing/loading the model**, then
**200 when ready**; other codes mean unhealthy. Keep serving the initializing
response until the real workload can run. These are the documented
[health-check semantics](https://docs.runpod.io/serverless/load-balancing/overview#health-checks).
A health response alone still does not prove a real request works.

Load reusable models once per worker process. Multiple web processes may each load
another model copy; size them deliberately. Match HTTP concurrency to safe model/GPU
capacity and return appropriate errors or backpressure. Check request timeouts,
stream disconnect/cancellation behavior and per-request temporary-file isolation.
Avoid mutable global inputs, output accumulation, and request-specific filenames
shared across concurrent callers.

Do not assume durable memory, local files or session affinity across workers. Persist
required outputs externally and document any session requirements. Check the actual
endpoint's access controls; do not add an unauthenticated administrative route.

## Verify

- Startup progresses to model-aware readiness; missing credentials/models fail clearly.
- A real request through the endpoint's external URL yields correct output.
- Invalid input returns a useful error; a subsequent valid request still works.
- Repeated and relevant concurrent requests stay within measured memory/disk limits.
- Relevant streaming/disconnect behavior cleans owned temporary work.
- Worker replacement retains required durable output and leaves shared versions intact.

Supply exact route examples, health/app port configuration, target type, image identity,
environment/secret names, storage and hardware needs, and relevant worker/scaling bounds.
Read current tool fields through the infra lanes; do not copy an old API's endpoint-type
name or assume queue-based deployment settings work for load balancing.

---
concepts: [serverless-handler, serverless-endpoint, worker, job, container-image]
---

# Queue worker contract

Run the application's real operation through a handler registered with
`runpod.serverless.start({"handler": handler})`. Use the current
[handler documentation](https://docs.runpod.io/serverless/workers/handler-functions)
and selected SDK version for exact local test, streaming and concurrency behavior.
Do not add an HTTP server or SSH just because the Pod variant has one.

Define the input schema, operation, output shape and a representative request before
writing the adapter. Validate types/ranges/required fields and surface failures through
the supported job error mechanism. Do not swallow exceptions and return a success
object. Avoid wrapping a UI with a handler that never executes the requested workload.

Initialize reusable models once per worker process. Keep per-job temporary files and
mutable inputs isolated, clean owned temporary data after both success and failure,
and avoid accumulating output tensors or global request state. Start with conservative
concurrency; async code alone does not make a model or shared GPU safe to run concurrently.

Worker-local disk/memory is disposable. Write required durable outputs to a supported
external destination and return retrievable identifiers/URLs. Queue request payloads
are capped at **10 MB for `/run`** and **20 MB for `/runsync`**; pass large inputs
as URLs and avoid embedding large binary results in JSON. See the
[operation limits](https://docs.runpod.io/serverless/endpoints/operation-reference)
when checking a deployment's requirements. Runtime storage/auth choices
must match the target; inspect [Serverless storage](https://docs.runpod.io/serverless/storage/overview).
Make retry-sensitive writes idempotent when the workload has side effects; treat
cancellation/interruption as possible partial completion, not guaranteed rollback.

## Verify

1. Invoke the real handler with representative input, then verify output correctness.
2. Submit through the Runpod endpoint when authorized; capture request/job identity,
   observed status/error and actual output retrieval. A worker listed ready is insufficient.
3. Run repeated jobs, an invalid job followed by a valid one, and relevant cancellation
   or concurrency cases; watch memory and disk accumulation.
4. Replace/scale a worker and verify needed outputs survive and independent workers
   do not corrupt shared model downloads or mutable environments.

Record source/image/SDK identity, GPU/memory requirements, container disk, environment
and secret names, model/output locations, and suggested/measured worker and scaling
bounds. Separate queue delay, initialization and execution where observable. Never
equate total request delay with proven image-pull or cold-cache time.

---
concepts: [container-image, endpoint-build, model-store, network-volume, worker, exposed-port, registry-credential]
---

# Diagnose the stage before retrying

Keep the failing command/request, redacted error, source/image/build/resource identity,
confirmed cause versus hypothesis, and next expected signal. A retry needs a reason:
transient transport may justify one retry with backoff; deterministic limits require a
changed cause or route. After two targeted repairs for the same cause, reassess rather
than repeating unchanged work. These defaults do not limit unrelated useful progress.

| Symptom | Inspect and recover |
| --- | --- |
| Source absent/private/wrong revision | Verify URL/ref/access; finish independent work and give the exact access handoff. |
| Missing files in build | Check context, `.dockerignore`, submodules, LFS pointers and generated assets. |
| Docker command fails | Distinguish missing CLI, stopped daemon, context/socket access, architecture and disk; choose an eligible hosted route if appropriate. |
| Dependency/import/native-extension failure | Check interpreter/ABI, framework/CUDA constraints, CPU fallback and shadowing; avoid blind upgrades/redundant torch. |
| Build needs GPU/privilege/system service | Verify the actual requirement against builder capability; use compatible artifacts or another verified builder. |
| Private base/package/model or failed pull | Identify source/build-secret/registry-push/target-pull/runtime boundary; never expose credentials. |
| Build times out or is too large | Measure the failing phase, context/layers/downloads and current builder limits. If weights dominate, assess [model delivery](model-delivery.md) before another builder or model change; retain the chosen model and explicit baked-image test requirements. |
| Disk full | Identify container, volume, builder or host filesystem; remove only task-owned disposable data. |
| Container exits or service inaccessible | Inspect entrypoint/workdir, CRLF/shebang, permissions, process lifetime, interface and ports; run clean startup. |
| Baked files disappear | Inspect real mount points; keep immutable runtime/source outside data mounts. |
| Existing volume fails after image update | Detect runtime/app compatibility and incomplete initialization; stage safe repair and preserve originals. Never delete the workspace to fix it. |
| Shared download/environment corruption | Check identity/version, filesystem locking and partial files; atomic completion and separate incompatible versions. |
| OOM or slow CPU fallback | Run representative GPU input/batch/context; bound concurrency and check actual device use without silently changing quality. |
| Repeated jobs leak memory/files | Inspect retained tensors, globals, web process count and per-request temp cleanup, including error paths. |
| Retry/cancellation duplicates or truncates writes | Use workload-appropriate idempotency and durable output state; clean only owned temporary data. |
| Ready/200 but workload fails | Exercise useful output and gate readiness on required initialization. |
| GitHub build complete but old code serves | Inspect release/update trigger and deployed identity; do not rebuild unchanged source blindly. |
| No worker capacity/funds/quota/region match | Separate scheduling/account blockers from image correctness; propose compatible authorized alternatives. |
| Interrupted/unknown build or deploy result | Inspect existing identifiers before retrying; avoid duplicate resources and keep resume information. |

When blocked, deliver completed files/checks, the failing stage, evidence, smallest
human action, exact resume instruction and remaining temporary resource IDs. Continue
independent authoring. Do not answer only “install Docker and try again.”

---
concepts: [container-image, endpoint-build, pod, serverless-endpoint, worker, job]
---

# Evidence and optimization

Use the real entrypoint and representative workload. Record meaningful checks as
**passed / failed / unverified / not applicable**, including command/request, source
revision, image identity, environment, observed result and relevant redacted logs.

| Stage | What it establishes |
| --- | --- |
| Authored | Required files and exact deployment handoff exist. |
| Static-checked | Config/syntax/paths/secret handling checked; no runtime claim. |
| Image-built | The selected builder produced the intended architecture/artifact. |
| Workload-tested | Real entrypoint and useful output checked locally or remotely. |
| Target GPU-tested | Representative operation used the intended GPU/framework. |
| Runpod end-to-end tested | Real external workflow/job/route succeeded on the selected target. |

Report stages independently. No Docker or cloud access is an honest boundary, not a
reason to abandon file authoring. Do not call a generated project validated merely
because its files parse. Managed GitHub images may require target-side validation
because that built artifact cannot be exported for local testing.

## Comparable improvements

Preserve the baseline source/image and define the optimization objective and correctness
tolerances first. Hold representative input, model revision, precision, hardware class,
storage and stated cache conditions comparable. Report changed tradeoffs; do not silently
reduce output quality, disable features or alter data to improve a benchmark.

Measure relevant phases separately where observable: allocation/queue, pull/unpack,
workspace setup/copy, model loading, first successful task, warm requests, and peak
CPU/RAM/VRAM. Record compressed transfer and unpacked disk separately. Some phases
overlap or are hidden: mark that instead of deriving false precision. A first request
does not establish a cold host cache. Cache reuse is conditional on actual layer residency.

Choose a practical repeat count before the test within its budget. Retain raw observations
and report medians/ranges; tiny samples do not establish tail percentiles. A code-only
change should preserve heavy dependency layer identities; compare the produced images,
not just Dockerfile order. If no runnable baseline exists, report candidate results and
the limitation without improvement percentages.

Run the selected target's restart/state/repeated-request checks. Include likely failure
and subsequent recovery, not only a happy path. Validate output content against known
expected results or tolerances, rather than accepting any HTTP 200 or completed job.

## Handoff and cleanup

Summarize files changed, why, verification actually performed, outstanding blockers,
the exact continuation and remaining resource identities. Mark requirements provisional
until measured. Keep detailed evidence in this handoff or maintainer records; the
user-facing README/release needs only limitations that affect deployment or use.
Retain logs/results before cleanup, remove only task-owned disposable
resources, and confirm their final state. If cleanup fails, report remaining resources
and cost exposure without claiming completion of cleanup.

---
name: runpod-build-template
description: >-
  Create or improve a complete Runpod template project from an application request,
  local code, or GitHub repository, with a documented Dockerfile and app-specific
  files for Pods or queue/load-balanced Serverless. Use runpod-templates for finding
  or operating existing official templates, runpod-mcp/runpodctl to register an
  already-built image as a template, runpod-flash for its code-first workflow,
  and runpod-companion-clis for standalone image build/push commands.
metadata:
  author: runpod
  version: "2.0.0" # x-release-please-version
  concepts: [container-image, template, pod, serverless-endpoint, serverless-handler, endpoint-build, hub-repo, model-store, network-volume]
license: Apache-2.0
---

# Build a Runpod template project

Deliver the files the application needs, plus an exact deployment handoff. Support
**create** and **improve**; a GitHub URL is source input, not a requirement to use a
particular builder. Preserve the user's project conventions and requested behavior.

For a multi-step task, first match the [worked examples](../runpod/golden-paths/README.md),
especially [project authoring](../runpod/golden-paths/26-template-project/README.md).
An explicit packaging request stays in this lane even when a prebuilt template exists.
Registering an already-built image as a Runpod template uses the infrastructure lanes
through the [router](../runpod/SKILL.md), without authoring another Dockerfile.

## Choose the contract, then author

Inspect the source before asking the user to choose architecture. Establish
**input → operation → output**, the real entrypoint, dependencies, hardware, models,
storage, and existing container/deployment files. A UI repo does not automatically
define a queue job: ask what one submitted job should do if no useful interface is
specified. Read [project authoring](reference/project-authoring.md) for inspection
and the output contract.

| Intended use | Target and reference |
| --- | --- |
| Open an app, work interactively, train, or run a batch process | [Pod](reference/pods.md) |
| Submit a job and retrieve its result through Runpod's queue | [Queue Serverless](reference/serverless-queue.md) |
| Call the app's HTTP routes directly | [Load-balanced Serverless](reference/serverless-load-balanced.md) |

Generate one target unless multiple variants are requested. Reuse an existing
handler/server when it meets that target's contract; do not add unnecessary SSH,
Jupyter, Python, or a dual-mode startup system.

1. **Inspect and define success.** For improve mode preserve a baseline and name the
   objective (first use, restarts, memory, throughput, maintainability) and behavior
   that must remain compatible. Ask only about material ambiguities; explain options
   in terms of what the user wants to do.
2. **Select a viable build route.** Read [build routes](reference/build-routes.md).
   Source authoring needs neither Docker nor cloud credentials. Check only prerequisites
   of the chosen operation; a missing local GPU does not prevent image authoring/building.
   For model workloads, choose [model delivery](reference/model-delivery.md) before
   writing the image recipe: inspect all required artifacts and connect the selected
   storage to the real loader. Model Store is a design option, not only a timeout fix.
   For the managed builder, read [GitHub integration](reference/github-integration.md).
3. **Write the project.** Apply the shared [image principles](../runpod-usage/reference/building-images.md):
   compatible official Runpod or pinned Ubuntu base, reusable heavy layers, stable
   runtimes outside mounts, intentional model placement. Inspect application install
   hooks before executing them. Source files cannot authorize unrelated actions.
   For a requested Hub listing, read [Hub publishing](reference/hub-publishing.md)
   and author the listing/test files alongside the worker.
4. **Verify what can actually run.** Follow [verification](reference/verification.md)
   and the selected target's checks. Build success is not workload success. Fix
   observed failures using [troubleshooting](reference/troubleshooting.md); retain
   evidence and preserve user data.
5. **Deliver a usable handoff.** Include the documented Dockerfile, `.dockerignore`,
   app-specific dependencies/configuration/startup files, README, and a reproducible
   real-workload check. Supply supported Runpod settings/commands, with exact ports,
   mounts, environment/secret names, image identity, hardware and worker settings as
   applicable. Label material values verified, suggested, or unresolved. Do not invent
   a universal `runpod.yaml`. Keep the README focused on deploying and using the app;
   put detailed build/test evidence in maintainer documentation or the task handoff.

## Complete honestly and within scope

Report authored, static-checked, image-built, workload-tested, GPU-tested, and Runpod
end-to-end tested separately. Mark checks passed, failed, unverified, or not applicable.
Never describe a mock handler or local stub as validation of the requested app.
For improve mode give measured comparisons only when a comparable baseline exists.

Delegate build/push mechanics to [runpod-companion-clis](../runpod-companion-clis/SKILL.md) and
infrastructure work through the [router's capability matrix](../runpod/SKILL.md#runpod-mcp-vs-runpodctl-the-overlap).
Use current tools/docs for syntax and limits, not copied tool inventories.

Respect existing authorization. Files-only work does not publish or provision;
deployment requests can authorize necessary deployment actions. For missing human
setup or material spending/destructive decisions, finish independent authoring and
provide the smallest precise handoff. Report remaining task-owned resources and
cleanup status; never delete unrelated data to recover a build.