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 static SPA. The default scaffold builds it from Civitai's <civitai-*> web components with no UI framework; React, or any other framework, works as well.
• 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.19+ (on 20.x) or 22.12+, and npm (or pnpm / yarn, with a matching buildCommand and outputDir).
• A Civitai account, and closed-beta builder access (see the banner above). Your app does not have to be reviewed first.
• Basic TypeScript. The default scaffold is web components on @civitai/sdk, with no UI framework to learn; if you prefer React, civitai app init --template page-money scaffolds the React alternative on @civitai/blocks-react.

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.
• The @civitai/sdk client — initialize(), what app.onChange fires on, the host's UI, the REST API, consent and money calls.
• Using the <civitai-*> elements in a block — which import defines which of the web components the default scaffold uses, theming them, and <civitai-chat>.
• 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.
• First review checklist — run it before civitai app submit: audit every state, declutter, an honest money path, and how to submit without losing your store listing.
• 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.
• Reading a workflow file — read a published Workflows model's file as parsed ComfyUI graphs with useResourceFile(): why it works only on a full-page app, which file is served by default, who is served what, and a worked example, with links to the reference for the error codes and limits.
• Multi-step workflows — chain up to eight orchestrator steps in one generation (kind: 'workflow'), a later step reading an earlier one's result; repeat, merge, the limits and how the price works.
• Storing data (document store) — declare collections in the manifest, read and write documents, counters and marks, the scopes and limits, testing with createFakeStorage, and moving off useAppStorage / useSharedStorage.
• 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/sdk and @civitai/components READMEs carry the full client and element surface; for React, so do @civitai/blocks-react and @civitai/app-sdk.