runpod-deploy

runpod-deploy is a config-driven RunPod orchestration package for reusable GPU project deployments. It owns the RunPod mechanics; consumer repos own their job configs and project commands.

Quickstart

pip install runpod-deploy

# Smoke-test with the bundled hello example (no RunPod account needed):
runpod-deploy run --config examples/hello/hello.yaml --offline-dry-run

# Or against the cheapest end-to-end pipeline:
runpod-deploy validate --config examples/smoke/a4000_smoke.yaml
runpod-deploy run --config examples/smoke/a4000_smoke.yaml --offline-dry-run
runpod-deploy logs --config examples/smoke/a4000_smoke.yaml          # live-tail the active pod's run log
runpod-deploy cleanup --state-file ~/.runpod-smoke-current            # release the active pod's volume disk
runpod-deploy ls-stale                                                # audit every EXITED pod + estimated $/day
runpod-deploy cleanup --all-stopped --yes                             # bulk-release every paused pod

--offline-dry-run prints the provision/stage/launch/pull/stop command shape without calling runpodctl, SSH, or rsync. For a real end-to-end deploy on a cheap GPU, see examples/smoke/README.md — it walks through the per-host setup (SSH key registration, rsync version) once.

For new consumers, docs/source/quickstart.md is the 5-minute onboarding walkthrough, and docs/source/lifecycle.md explains what happens at each phase of a runpod-deploy run.

Optional: shell tab completion. Install via the [completion] extra and register with your shell:

pip install runpod-deploy[completion]
eval "$(register-python-argcomplete runpod-deploy)"   # bash/zsh

Add the eval line to your ~/.bashrc or ~/.zshrc for persistence.

Contributors: see CONTRIBUTING.md for the editable install (uv pip install -e ".[dev]"), pre-commit setup, and the fork → branch → PR → CI flow.

Examples

Consumer-owned configs

The recommended pattern is for the consumer repo to own its runpod-deploy job YAML alongside the project. The YAML lives at consumer-repo/configs/runpod/*.yaml, and local.project_root is set relative to that file's directory:

my-project/
├── pyproject.toml
├── src/...
└── configs/
    └── runpod/
        └── headline.yaml          # local.project_root: ../..

# configs/runpod/headline.yaml
local:
  project_root: ../..   # one level for runpod/, one for configs/

../.. resolves to my-project/, which is what gets rsynced to the pod. A common off-by-one — ../../.. from the same location — resolves to your $HOME directory and would stage the entire home tree to the pod; runpod-deploy validate (and any run) fails-fast in this case.

The example configs under examples/ are not consumer-owned — they live inside this repo, so they use longer paths (../../../prompt-injection-v3) to reach back to a sibling consumer repo. Don't copy that pattern when authoring configs inside your own consumer repo.

Model

Version 1 supports one job per YAML file:

• RunPod pod settings: image, datacenter, GPU order, storage mode, cost cap.
• Local staging: rsync pushes from the consumer repo to the pod.
• Remote setup and preflight commands.
• Detached remote run script, success marker, and failure markers.
• Artifact pulls and a reproducibility manifest.

The core is intentionally project-neutral. If a project needs special behavior, put it in its config or shell commands. Python hooks are reserved for a future schema version after at least two projects need the same extension point.

Docs

Full site (searchable, with API reference): https://brandon-behring.github.io/runpod-deploy/

Direct links to the GitHub-rendered markdown:

• Quickstart — 5-minute onboarding
• Lifecycle — what happens at each phase of a run
• Config reference
• RunPod gotchas
• Extending guide
• V3 migration guide
• Coding standards