Introduction

Civitai Apps let you build a small web app that renders inside civitai.com — a self-contained UI, embedded in a sandboxed iframe, that the host authenticates, sizes, and connects to Civitai capabilities (the viewer, Buzz, generation) on your behalf. You ship a static single-page app; you don't run a backend, manage OAuth, or operate any infrastructure.

Closed beta — access is limited

Civitai Apps is currently in closed beta and is not yet generally available. The platform is mod-gated: authoring and publishing apps is limited to approved builders, and it is not openly self-serve today. If you'd like to build an app, reach out to the Civitai team to request access. (There is not yet a public self-signup flow.)

"Approved builders" is about you, not about your app. Once you have that access nothing further is gated behind review: you can run your app locally and generate for real before you submit it, and before any moderator has seen it. Only the public URL waits for approval. Use npm run dev:live for that — the on-site dev tunnel has a further gate of its own before you have submitted. See Local dev loop.

What is a Civitai App?

The runtime unit is a block: a static web app, served from its own platform-owned subdomain (https://<slug>.civit.ai/), declared by a small block.manifest.json. The host page (civitai.com) draws a trust frame around your iframe, hands it a short-lived, scoped token plus the current page context over postMessage, and brokers whatever has to raise Civitai's own UI — so your app never holds a long-lived credential. What your block does with that token depends on which transport it uses: the postMessage bridge, or a direct call to /api/v1. See Transport models.

Naming: the product is Civitai Apps; the code, manifest, scopes, and messages still use the block / app_block vocabulary. You'll see both in these docs — an "app" is what a user installs; a "block" is the hosted iframe unit it ships.

The result is a tight contract:

• You own the UI — a normal Vite + React (or any framework) SPA.
• The platform owns hosting, the subdomain, the runtime image, token minting, and the review/deploy pipeline.
• The host mediates every privileged action (generation, Buzz, storage, navigation) so policy is enforced on Civitai's side of the iframe boundary.

Page apps and slot apps

A block can render in two places:

• Page apps — a full-page app opened from the Apps area on civitai.com (/apps/run/<slug>), rendered full-bleed under Civitai's chrome. These docs target page apps.
• Slot apps — a block embedded in a named region of another page (for example, a model-page sidebar). Slot apps exist in the platform but are deferred / disabled for third-party builders right now. Build a page app.

What you'll need

• Node ≥ 20 and pnpm.
• A Civitai account, and closed-beta builder access (see the banner above). Your app does not have to be reviewed first.
• Basic familiarity with React — the starter and SDK are React-first.

You do not need Docker, a domain, a git host, or an OAuth client — the platform provisions all of that when your app is approved.

Where to start

• Concepts — the mental model: block, install, slot, the iframe trust frame, and how the host and your app talk to each other.
• Quickstart — go from nothing to a block running in the local harness using the civitai CLI scaffold.
• Local dev loop — the two harness modes, and how to generate for real against the live backend before submitting your app. Start here if generation is refusing or you think you are blocked on review.
• Comfy on Civitai (customComfy) — drive ComfyUI, either by naming a server-registered recipe ({ kind, recipe, params }) or by shipping your own graph inline (mode: 'inline'); the gates on each arm and the budget rules.
• Running embedded & direct traffic — why your app runs embedded in the Civitai host, why you share the /apps/run/<slug> route, and how <BlockGate> degrades a direct visit gracefully.

Once you understand the shape, the @civitai/blocks-react and @civitai/app-sdk packages carry the full hook and contract surface.