App

API reference for urun.App and function registration.

Public API at a Glance

For patterns and narrative explanation, see the App concept page.

App

from urun import App

App(name: str)

Create an app container. The name identifies your app in logs, the console, and deployment.

Use App as the entry point for all urun programs.

@app.function()

@app.function(
    *,
    gpus: str | int | None = None,
    cpus: str | int | None = None,
    memory: int | None = None,
    deps: Dependencies | None = None,
    credentials: Credentials | None = None,
    env: dict[str, str] | None = None,
    lease: int | None = None,
    max_session_s: int | None = None,
    session_connect_timeout: int | None = None,
    session_disconnect_grace: int | None = None,
    session_idle_timeout: int | None = None,
    replicas: int | None = None,
    warm: int | None = None,
    max_concurrency: int | None = None,
    sessions_per_pod: int | None = None,
    sessions_per_user: int | None = None,
    tier: str | None = None,
    snapshot: bool | None = None,
    expandable_segments: bool = False,
    gpu_pack: Any = None,   # str label | fn instance | App.ref("app").fn
    gpu_pack_sm_partition: dict | None = None,
    gpu_pack_limits: dict | None = None,
    session_kind: str = "realtime",
) -> Callable

Register a function to run on remote GPUs. This is the primary decorator for defining GPU workloads. The kwargs are the function's config, fixed at deploy time — they are never overridable from a session invocation. Invalid values fail loudly at decoration time (app import), never silently at deploy.

Use @app.function for live streaming sessions and one-shot GPU tasks. For streaming, use ctx.stream() inside the function body to create session-scoped streams and build pipelines.

@app.function(gpus="h100:1", lease=3600)
def restyle(ctx):
    ...

# Streaming pipeline example
@app.function(gpus="b200:2", deps=DEPS, credentials=CREDS)
async def stream_video(ctx: urun.Context):
    control = ctx.doc("control")
    video = ctx.stream("video", codec="h264", bitrate=8_000_000, fps=24, rank=1)

    def denoise(*, stop_event, config):
        while not stop_event.is_set():
            yield model.step(control.desired.prompt.value)   # live inline read

    pipeline = (
        ctx.source(denoise, device="cuda", rank=0)
        | ctx.pipe(vae_decode, device="cuda", rank=1)
        | ctx.unbatch(rank=1)
        | ctx.pace(fps=24, rank=1)
        | video
    )
    await pipeline.run()

There is no topology kwarg. You declare a shape (gpus="b200:4"); uRun launches one rank per GPU and the model owns its own parallelism (ctx.rank / ctx.world_size inside the function). Reactive control is inline doc.desired.* reads plus doc.bind for structural change — the old pipeline.bind(doc, mapping) field-mapping is retired.

App.ref() — cross-app calls

App.ref(name: str) -> AppRef

A by-name reference to another app registered by the same org. Attribute dispatch is the API: calling a function attribute on the returned ref mints a real session on that app's function and returns the session primitive (session.doc(...) / session.stream(...) — the Python equivalent of the TS client). Awaiting the call gives the one-shot result.

from urun import App, CalleeUnavailable

ref = App.ref("qwen-image-edit")
try:
    session = ref.edit(prompt=prompt, frame=frame_ptr)       # its own session
    edited = await ref.edit(prompt=prompt, frame=frame_ptr)  # one-shot
except CalleeUnavailable:
    ...  # the callee may be scaled-to-zero, mid-rollout, or never deployed

Returns a distinct proxy type (AppRef), not an App — function names resolve via attribute lookup, and an unknown function fails loudly at call time with the org-scoped lookup error. The same-app form is the plain attribute: session = app.other_fn(...). Refs — never strings — cross app boundaries (they are also the cross-app form accepted by gpu_pack=). There is no ctx.call.

fn.copy()

fn.copy(**overrides) -> UrunFunction

Create an independent copy of a registered function, optionally overriding config. Changes to the copy do not affect the original.

Use .copy() when you need multiple variants of the same function with different compute configurations.

@urun.app()

@urun.app(name: str) -> Callable[[type], type]

Class-based app decorator. Turns a class into an app container where methods become registered functions.

Use @urun.app when you have multiple related functions that benefit from class-based organization.

@urun.app("my-studio")
class MyStudio:
    @urun.function(gpus="h100:1")
    def generate(self, ctx, prompt: str = ""):
        ...

@urun.function()

@urun.function(gpus=..., deps=..., credentials=..., ...) -> Callable

Class-based function decorator. Used inside @urun.app classes to register methods as remote GPU functions. Accepts the same parameters as @app.function(), including the same retired-kwarg errors.

Use @urun.function inside class-based apps. For standalone apps, use @app.function().

Runtime configuration boundary

This is the single canonical statement of what is fixed vs what can change, referenced from every "argument purity" callout in the docs.

Fixed at deploy time (config): gpus, cpus, memory, replicas, warm, max_concurrency, sessions_per_pod, sessions_per_user, deps, credentials, env, lease, max_session_s, session_connect_timeout, session_disconnect_grace, session_idle_timeout, tier, snapshot, expandable_segments, gpu_pack, gpu_pack_sm_partition, gpu_pack_limits, session_kind — everything the decorator declares. These are captured by @app.function and registered with the control plane at urun deploy.

A browser/session invocation cannot change a function's shape. Calling app.fn(args) (TS) or session = app.fn(...) / App.ref("app").fn(...) delivers args 1:1 to the Python function's own parameters and verbatim — reserved-looking names like gpus are passed through untouched, never reinterpreted as resource overrides.

The GPU shape is declared once on @app.function and fixed at deploy time. Nothing changes the shape of an already-running session: once a session is allocated, its GPU shape is fixed for the life of that session.