RunPod Serverless Backend for SwarmUI

A production ready SwarmUI backend extension that enables serverless GPU inference through RunPod's on demand infrastructure. It manages worker lifecycle automatically, provides cost effective scaling, and integrates with SwarmUI's generation pipeline the same way a local backend does.

It is designed to work with the custom RunPod SwarmUI worker. Install that first and confirm it is running on RunPod before you continue. If you would rather build your own worker, make sure your handler functions are named and behave the same way, and that SwarmUI is reachable on the worker.

• On-demand worker management. Wakes and shuts down GPU workers automatically to minimize cost.
• Seamless integration. Works like any native SwarmUI backend, with full parameter support.
• Flexible API key management. User level keys, with a backend level key as fallback.
• Model discovery. Automatic remote model enumeration and registration.
• API endpoints. SwarmUI routes for status monitoring and manual refresh.
• Permission system. Granular access control through SwarmUI's permission framework.
• Configurable timeouts. Adjustable startup, generation and polling intervals.
• Error handling. Handles worker errors and timeouts gracefully.

Install from Server > Extensions: find RunPod Serverless in the list, press Install, and restart SwarmUI when prompted. To install by hand, clone the repository into SwarmUI/src/Extensions/, stop Swarm, and use the update or dev scripts to rebuild with the new extension. Confirm it appears under Server > Extensions afterwards.

Open Server > Backends, turn on Show Advanced, and select RunPod Serverless from the type dropdown.

For a shared backend, set RunPodApiKey in the backend settings so all users share one key; that is also what AutoRefresh needs. For a multi-user install, leave it empty and have each user add their own RunPod key under User Settings > API Keys. The backend falls back from backend-level to user-level automatically.

Once configured, the backend works like any other: select a model, set your parameters, and press Generate. Behind that, the backend wakes the RunPod worker, waits for ready state, sends the generation request, returns the images, and shuts the worker down.

1. User submits generation request
2. Backend wakes RunPod worker      (POST /run, keepalive started)
3. Poll for worker ready state      (every PollIntervalMs, until StartupTimeoutSec)
4. Worker ready, get public URL and session ID
5. Forward generation request       (T2IParamInput serialized to the worker's /API/GenerateText2Image)
6. Receive and process response     (base64 images extracted and converted)
7. Shutdown worker                  (worker scales to zero)
8. Return images to user

Two REST routes come with it. POST /API/RunPod/RefreshModels refreshes the model list from every running RunPod backend, and GET /API/RunPod/GetStatus returns status for all of them: id, title, status, endpoint id, model count, auto refresh and max concurrent. Both require the use_runpod_serverless permission.

Cold start is typically 60 to 90 seconds, covering container start, SwarmUI init and model discovery. A warm generation, where the worker is still running from a previous job, starts near instantly with no cold start penalty.

Keepalive is sized to the job: 180 seconds for a single generation covering cold start, generation and a buffer, longer for batches, and 300 seconds for a model refresh, which is enough for model listing across all types.

MaxConcurrent controls parallelism. 1 is serial and cheapest, 5 is moderate, and 10 is the default for high throughput. Each concurrent request wakes a separate worker instance, so higher is not free.

Backend keys are stored in the backend configuration, encrypted at rest by SwarmUI, and visible only to administrators. User keys are stored in the user profile, isolated per user, and not visible to other users.

One permission gates the extension: use_runpod_serverless, granted to Admin and PowerUser by default and withheld from User.

Outbound connections go to api.runpod.ai for the RunPod API and to individual worker instances at [worker-id].runpod.io. No inbound connections are required, because RunPod workers never connect back.

Supports every model type available in the remote SwarmUI instance: Stable Diffusion 1.5, 2.x and XL, Flux, LoRA models, ControlNet models, and any other SwarmUI-compatible architecture.

The worker needs at minimum 1 vCPU, 4GB RAM and a GPU with enough VRAM for the models you intend to load, and must expose the SwarmUI API on the standard port.