feat!: apps SDK, decorator-native GPU compute with live dev sessions and a new rp CLI

.dockerignore

@@ -0,0 +1,16 @@
+# keep the runtime image build context to what pip install needs:
+# package source, metadata, and the files setup.py/MANIFEST.in read
+.git
+.github
+.venv
+build
+benchmark_results
+docs
+examples
+job_files
+scripts
+tests
+uv.lock
+**/__pycache__
+**/*.pyc
+*.egg-info

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## Unreleased
+
+### Features
+
+* Apps expose `NetworkVolume` and `GlobalVolume` resources with explicit path-keyed mounts, lazy create-if-missing provisioning, and execution-bound filesystem access. Global volumes use GraphQL for lookup and creation.
+
 ## [1.12.0](https://github.com/runpod/runpod-python/compare/v1.11.0...v1.12.0) (2026-08-10)
 
 

README.md

@@ -1,70 +1,109 @@
 <div align="center">
-<h1>Runpod | Python Library </h1>
 
-[![PyPI Package](https://badge.fury.io/py/runpod.svg)](https://badge.fury.io/py/runpod)
-&nbsp;
-[![Downloads](https://static.pepy.tech/personalized-badge/runpod?period=total&units=international_system&left_color=grey&right_color=blue&left_text=Downloads)](https://pepy.tech/project/runpod)
+<h1>Runpod Python</h1>
 
-[![CI | End-to-End Runpod Python Tests](https://github.com/runpod/runpod-python/actions/workflows/CI-e2e.yml/badge.svg)](https://github.com/runpod/runpod-python/actions/workflows/CI-e2e.yml)
+**Define GPU functions in Python. Run them in the cloud with one decorator.**
 
+[![PyPI Package](https://badge.fury.io/py/runpod.svg)](https://badge.fury.io/py/runpod)
+[![Downloads](https://static.pepy.tech/personalized-badge/runpod?period=total&units=international_system&left_color=grey&right_color=blue&left_text=downloads)](https://pepy.tech/project/runpod)
 [![CI | Unit Tests](https://github.com/runpod/runpod-python/actions/workflows/CI-pytests.yml/badge.svg)](https://github.com/runpod/runpod-python/actions/workflows/CI-pytests.yml)
-&nbsp;
-[![CI | CodeQL](https://github.com/runpod/runpod-python/actions/workflows/CI-codeql.yml/badge.svg)](https://github.com/runpod/runpod-python/actions/workflows/CI-codeql.yml)
+[![License](https://img.shields.io/badge/License-MIT-blue)](LICENSE)
+
+[Documentation](https://docs.runpod.io) • [Examples](examples/apps) • [Discord](https://discord.gg/pJ3P2DbUUq)
 
 </div>
 
-Welcome to the official Python library for Runpod API &amp; SDK.
+## Installation
 
-## Table of Contents
+```bash
+pip install runpod    # or: uv add runpod
+rp login              # authenticate once
+```
 
-- [Table of Contents](#table-of-contents)
-- [💻 | Installation](#--installation)
-- [⚡ | Serverless Worker (SDK)](#--serverless-worker-sdk)
-  - [Quick Start](#quick-start)
-  - [Local Test Worker](#local-test-worker)
-- [📚 | REST API v2 Wrapper](#--rest-api-v2-wrapper)
-  - [Endpoints](#endpoints)
-  - [GPU Cloud (Pods)](#gpu-cloud-pods)
-- [📁 | Directory](#--directory)
-- [🤝 | Community and Contributing](#--community-and-contributing)
+Requires Python 3.10+. Installing the package also installs the `rp` CLI.
 
-## 💻 | Installation
+## Example
 
-### Install from PyPI (Stable Release)
+```python
+import runpod
+from runpod import App, Model, NetworkVolume, Secret
 
-```bash
-# Install with pip
-pip install runpod
+app = App("inference")
 
-# Install with uv (faster alternative)
-uv add runpod
-```
+models = NetworkVolume("models", size=100)
+llama = Model("meta-llama/Llama-3.1-8B-Instruct")
+
+
+# an autoscaling job queue on cloud H100s: weights pre-cached,
+# dependencies vendored at deploy time, scale-to-zero when idle
+@app.queue(
+    gpu="H100",
+    workers=(0, 3),
+    dependencies=["vllm"],
+    mounts={"/runpod-volume": models},
+    model=llama,
+    env={"HF_TOKEN": Secret("hf-token")},
+)
+def chat(prompt: str):
+    import vllm
+
+    llm = vllm.LLM(model=str(llama.path))   # weights already on disk
+    return llm.generate(prompt)
 
-### Install from GitHub (Latest Changes)
 
-To get the latest changes that haven't been released to PyPI yet:
+# one ephemeral pod per call: provisions, runs to completion, terminates
+@app.task(gpu="H100", gpu_count=2, mounts={"/models": models})
+def finetune(steps: int = 1000):
+    ...
+    return {"loss": final_loss}
+
+
+@runpod.local_entrypoint
+def main():
+    print(chat.remote("why is the sky blue?"))   # blocks for the result
+    job = finetune.spawn(steps=500)              # fire and forget -> Job
+```
 
 ```bash
-# Install latest development version from main branch with pip
-pip install git+https://github.com/runpod/runpod-python.git
+rp flash dev main.py    # live dev session: edit, re-run, logs stream back
+rp flash deploy         # deploy production endpoints
+```
+
+Functions keep their Python identity: `chat.remote(...)` runs in the cloud, `await chat.remote.aio(...)` is the async form, `chat.local(...)` runs in-process. See [`examples/apps`](examples/apps) for runnable examples and [docs.runpod.io](https://docs.runpod.io) for the full guide.
+
+Queue `.remote()` calls request a synchronous result and poll the same job if the server's wait window expires. Fast results need no client-side polling. Dev sessions use a short sync window to keep worker logs responsive. Use `.spawn()` for an asynchronous job handle. A transport failure before receiving a job ID raises an error without resubmitting the work.
+
+## Storage
 
-# Install with uv
-uv add git+https://github.com/runpod/runpod-python.git
+`NetworkVolume(name_or_id, size=50, datacenter=None, create=True)` references
+datacenter-local storage. Apps resolve names and choose a datacenter compatible
+with every resource sharing the volume. `GlobalVolume(name_or_id, create=True)`
+references global storage without a datacenter constraint. Both inherit from
+the abstract `Volume` base, resolve by name or ID, and create missing storage
+when provisioning remote compute. Set `create=False` to require existing storage.
+Global-volume lookup and creation use GraphQL; network volumes use REST.
 
-# Install a specific branch
-pip install git+https://github.com/runpod/runpod-python.git@branch-name
+Declare attachments with `mounts={"/path": volume}`. Tasks support one network
+and one global volume at distinct, non-overlapping paths. Queue and API resources
+support one volume at `/runpod-volume`; global storage requires a GPU endpoint.
 
-# Install a specific tag/release
-pip install git+https://github.com/runpod/runpod-python.git@v1.0.0
+Inside worker code, `volume.path` returns the configured mount path. The runtime
+binds declared references and resolved IDs before importing user code. Access
+raises if the volume is unmounted or has multiple bindings. Evaluate `.path`
+inside remote functions, not during local module discovery. Calling `.local()`
+does not mount remote storage on the client machine.
 
-# Install in editable mode for development
+## Contributing
+
+Pull requests and issues are welcome — see the [contributing guide](CONTRIBUTING.md) to get started.
+
+```bash
 git clone https://github.com/runpod/runpod-python.git
 cd runpod-python
-pip install -e .
+make setup
+make test
 ```
 
-*Python 3.10 or higher is required to use the latest version of this package.*
-
 ## ⚡ | Serverless Worker (SDK)
 
 This python package can also be used to create a serverless worker that can be deployed to Runpod as a custom endpoint API.
@@ -347,12 +386,8 @@ runpod.terminate_pod(pod["id"])
 └── tests              # Package tests
 ```
 
-## 🤝 | Community and Contributing
-
-We welcome both pull requests and issues on [GitHub](https://github.com/runpod/runpod-python). Bug fixes and new features are encouraged, but please read our [contributing guide](CONTRIBUTING.md) first.
-
 <div align="center">
 
-<a target="_blank" href="https://discord.gg/pJ3P2DbUUq">![Discord Banner 2](https://discordapp.com/api/guilds/912829806415085598/widget.png?style=banner2)</a>
+<a target="_blank" href="https://discord.gg/pJ3P2DbUUq">![Discord](https://discordapp.com/api/guilds/912829806415085598/widget.png?style=banner2)</a>
 
 </div>

docs/cli/references/command_line_interface.md

@@ -4,42 +4,58 @@ Note: This CLI is not the same as runpodctl and provides a different set of feat
 
 ```bash
 # Auth
-runpod config
-
-runpod ssh list-keys
-runpod ssh add-key
-
-runpod pod list
-runpod pod create
-runpod pod connect
-
-runpod exec python file.py
+rp login
+
+# Flash apps
+rp flash init my-app
+rp flash dev main.py
+rp flash deploy
+rp flash app list
+rp flash env list --app my-app
+rp flash undeploy --app my-app
+
+# SSH
+rp ssh add          # add a key to your account
+rp ssh list         # list account keys
+rp ssh POD_ID       # open a terminal on a pod
+
+# Pods
+rp pod list
+rp pod create
+rp pod connect POD_ID
 ```
 
 ## Overview
 
 ```bash
-runpod --help
+rp --help
 ```
 
-### Configure
+### Authenticate
 
 ```bash
-$ runpod config
-Profile [default]:
-Runpod API Key [None]: YOUR_RUNPOD_API_KEY
+rp login                        # browser approval
+rp login --api-key YOUR_KEY     # store a key directly
+rp login --profile staging      # save browser credentials in a named profile
 ```
 
-### Launch Pod
+Credentials are stored in `~/.runpod/config.toml`.
+Use `--profile NAME` with either login method to update only that profile; the default is `default`.
+
+### Flash apps
 
 ```bash
-runpod launch --help
-runpod launch pod --template-file template.yaml
+rp flash init my-app              # scaffold a project
+rp flash dev main.py              # run a live development session
+rp flash deploy                   # deploy the current project
+rp flash app list                 # list deployed apps
+rp flash env list --app my-app    # list an app's environments
+rp flash undeploy --app my-app    # delete an environment's endpoints
 ```
 
-### Launch Endpoint
+App discovery imports modules synchronously. Keep blocking work inside an
+entrypoint or a resource function; interrupt discovery if an import blocks.
 
-```bash
-runpod launch endpoint --help
-runpod launch endpoint --template-file template.yaml
-```
+On Ctrl-C, a dev session waits for its running local entrypoint to finish before
+deleting endpoints. Blocking entrypoint code can delay shutdown. Cleanup failures
+exit with an error and report the endpoint IDs that still need deletion.

docs/cli/start_here.md

@@ -1,23 +1,23 @@
-# [BETA] | Runpod Python CLI Reference
+# Runpod CLI Reference
 
 Note: This CLI is not the same as runpodctl and provides a different set of features.
 
 ## Getting Started
 
-![runpod --help](demos/help.gif)
+![rp --help](demos/help.gif)
 
-### Configure
+### Authenticate
 
-![runpod config](demos/config.gif)
+Store your Runpod API key by running `rp login` (browser approval) or `rp login --api-key YOUR_KEY`. Credentials are stored in `~/.runpod/config.toml`.
 
-Store your Runpod API key by running `runpod config`. Optionally you can also call the command with your API key `runpod config YOUR_API_KEY` or include the `--profile` to save multiple keys (stored under "default" profile is not specified) Credentials are stored in `~/.runpod/config.toml`.
+Pass `--profile staging` with either login method to update a named credential profile without changing the others. The default profile is `default`.
 
-![runpod ssh add-key](demos/ssh.gif)
+### SSH
 
-Add a SSH key to you account by running `runpod ssh add-key`. To specify and existing key pass in `--key` or `--key-file` to use a file. Keys are stored in `~/.runpod/ssh/`.  If no key is specified a new one will be generated and stored.
+Add an SSH key to your account by running `rp ssh add`. To use an existing key pass `--key` or `--key-file`. Keys are stored in `~/.runpod/ssh/`. If no key is specified a new one is generated and stored.
 
-## Runpod Project
+Once a key is added, open a terminal on any pod with `rp ssh <pod_id>` (or the equivalent `rp pod connect <pod_id>`).
 
-A "project" is the start of a serverless worker. To get started call `runpod project new`, you will be asked a few questions about the project you are creating, a project folder will be created. You can now navigate into your repo and run `runpod project start`.
+## Apps
 
-Once you are finished developing you can run `runpod project deploy` to deploy your project and create an endpoint.
+An app is a collection of Python functions that run on Runpod. Scaffold one with `rp flash init`, iterate on it live with `rp flash dev main.py`, and ship it with `rp flash deploy`. See the [README](../../README.md) for the full workflow.

examples/apps/README.md

@@ -0,0 +1,25 @@
+# app examples
+
+each file is a self-contained app showing one way to use the sdk.
+run any of them live with `rp flash dev`:
+
+```bash
+rp flash dev examples/apps/hello_world.py
+```
+
+| example | shows |
+|---|---|
+| `hello_world` | one queue function, one `.remote()` call |
+| `streaming` | generator functions, `.stream()` chunks, `job.stream()` |
+| `gpu_inference` | gpu selection, dependencies, a cuda benchmark |
+| `web_service` | `@app.api` class with routes and per-worker state |
+| `train_and_eval` | gpu tasks sharing checkpoints through a volume |
+
+edit a file while the session is running, then press enter to re-run —
+workers pick up the new code automatically. the exhaustive
+feature-by-feature suite lives in [`tests/e2e/examples`](../../tests/e2e/examples).
+
+`await task.spawn.aio(...)` returns a task job that owns its pod.
+`await job.wait(timeout=...)` terminates that pod when waiting finishes, including
+timeout, task failure, or cancellation. use `await job.cancel()` to abandon a
+spawned task explicitly. a failed termination retains `job.pod_id` for cleanup.

examples/apps/gpu_inference.py

@@ -0,0 +1,43 @@
+"""Run a function on a GPU.
+
+Ask for hardware by name — "4090", "H100", "B200" all work, as do
+pool ids like GpuGroup.ADA_24 and exact device names. Dependencies
+listed on the decorator are ready before your function runs, so the
+worker needs no custom image.
+
+    rp flash dev examples/apps/gpu_inference.py
+"""
+
+import runpod
+
+app = runpod.App("gpu-demo")
+
+
+@app.queue(gpu="4090", dependencies=["numpy"])
+def matmul_benchmark(size: int = 4096):
+    import time
+
+    import torch
+
+    device = torch.cuda.get_device_name(0)
+    print(f"running on {device}")
+
+    a = torch.randn(size, size, device="cuda")
+    b = torch.randn(size, size, device="cuda")
+
+    torch.cuda.synchronize()
+    start = time.time()
+    for _ in range(10):
+        _ = a @ b
+    torch.cuda.synchronize()
+    elapsed = time.time() - start
+
+    tflops = 10 * 2 * size**3 / elapsed / 1e12
+    print(f"{size}x{size} matmul: {tflops:.1f} TFLOPS")
+    return {"device": device, "tflops": round(tflops, 1)}
+
+
+@runpod.local_entrypoint
+def main():
+    result = matmul_benchmark.remote()
+    print("benchmark:", result)