# https://github.com/invoke-ai/InvokeAI Project Manual

Generated at: 2026-07-24 22:57:49 UTC

## Table of Contents

- [Overview, Installation & System Requirements](#page-1)
- [System Architecture: Backend, Frontend & API](#page-2)
- [Supported Models & Generation Pipelines](#page-3)
- [Core Features: Unified Canvas, Workflows, Gallery & Multi-User](#page-4)

<a id='page-1'></a>

## Overview, Installation & System Requirements

### Related Pages

Related topics: [System Architecture: Backend, Frontend & API](#page-2)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/invoke-ai/InvokeAI/blob/main/README.md)
- [docs/src/content/docs/start-here/installation.mdx](https://github.com/invoke-ai/InvokeAI/blob/main/docs/src/content/docs/start-here/installation.mdx)
- [docs/src/content/docs/start-here/system-requirements.mdx](https://github.com/invoke-ai/InvokeAI/blob/main/docs/src/content/docs/start-here/system-requirements.mdx)
- [docs/src/content/docs/start-here/manual.mdx](https://github.com/invoke-ai/InvokeAI/blob/main/docs/src/content/docs/start-here/manual.mdx)
- [docker/Dockerfile](https://github.com/invoke-ai/InvokeAI/blob/main/docker/Dockerfile)
- [docker/docker-compose.yml](https://github.com/invoke-ai/InvokeAI/blob/main/docker/docker-compose.yml)
</details>

# Overview, Installation & System Requirements

## What Is InvokeAI

InvokeAI is an open-source creative engine for Stable Diffusion and compatible generative models. It bundles a local web UI, a node-based workflow editor ("Workflows"), a REST API, and a Python CLI around a unified backend that loads diffusion checkpoints (SD 1.5, SDXL, FLUX.1/FLUX.2, Z-Image Turbo, Qwen-Image, and others) on either NVIDIA (CUDA), Apple Silicon (MPS), or AMD (ROCm) hardware. The project positions itself as a single installer that works across consumer GPUs while exposing the same generation, inpainting, ControlNet, and model-management capabilities to both graphical and scripted users.

Source: [README.md:1-40]()

## Installation Methods

The repository documents three installation paths; users normally pick one based on their operating system and tolerance for command-line work.

### Invoke Launcher (recommended for most users)

A desktop wrapper that creates and manages an isolated Python virtual environment, downloads models, and starts the server. It is the default entry point referenced in the release notes (`Invoke's Launcher`) and is the install method most often cited in community bug reports.

Source: [docs/src/content/docs/start-here/installation.mdx:1-60]()

### Manual Install (Python / pip)

For Linux power users, Docker hosts, and CI environments. The manual flow clones the repo, creates a `venv`, runs `pip install -e .` (or a pinned requirements file), then launches `invokeai-web` or `invokeai --web`. This path exposes more knobs — custom `invokeai.yaml`, custom model roots, ROCm wheels — and is the path required when adding support for new GPU generations before the launcher ships updated wheels.

Source: [docs/src/content/docs/start-here/manual.mdx:1-80]()

### Docker

A reproducible container with the backend, frontend, and optional `cloudflareflared` tunnel preconfigured. `docker/Dockerfile` builds on a Python base image, installs the InvokeAI package plus system libraries, and copies in a startup script; `docker/docker-compose.yml` wires the volume mounts for models, outputs, and configuration so that data survives container rebuilds.

Source: [docker/Dockerfile:1-60](), [docker/docker-compose.yml:1-40]()

| Method | Best For | GUI | Headless/Server |
|---|---|---|---|
| Invoke Launcher | First-time users, desktop | Yes | No |
| Manual (pip) | Linux, custom GPU stacks | Optional | Yes |
| Docker | Servers, repeatable deploys | Optional | Yes |

## System Requirements

The official documentation groups requirements into GPU, CPU/RAM, disk, and operating-system tiers.

- **GPU (NVIDIA).** CUDA-compatible card with at least 6 GB VRAM for SD 1.5, 10–12 GB for SDXL, and 16–24 GB recommended for FLUX and Z-Image Turbo. Driver/CUDA versions are pinned per release in the launcher; community reports show NVIDIA RTX 50-series "Blackwell" GPUs (e.g., RTX 5090) currently crash the launcher with a breakpoint exception (`0x80000003`) until a PyTorch wheel catches up.
- **GPU (AMD).** ROCm-supported cards. RDNA/GFX11-family devices such as `gfx1151` on ROCm 6.4+ are not yet officially recognized by the default PyTorch build, so manual installs and ROCm-version overrides are required (`#8655`).
- **GPU (Apple).** MPS on M-series Macs is supported but slower; Apple Silicon users typically need 16 GB unified memory for SDXL.
- **CPU/RAM.** A modern x86_64 CPU and 16 GB system RAM are the practical floor; 32 GB is recommended when generating at higher resolutions or running the API alongside the UI.
- **Disk.** Tens of gigabytes for the install plus the model cache (each SDXL checkpoint is ~6 GB, FLUX checkpoints 12–24 GB). An SSD is strongly advised because model load is I/O-bound.
- **Operating system.** Windows 10/11, recent macOS, and Linux distributions with glibc 2.31+ (e.g., Ubuntu 20.04 / 22.04, Fedora, Arch). The launcher and node editor are the parts most affected by OS-level dependencies; on Linux, ABI mismatches between bundled `libtiff`/`libjpeg` and the system libraries can prevent the inpainting helper `PatchMatch` from loading (`#9287`).

Source: [docs/src/content/docs/start-here/system-requirements.mdx:1-90]()

## Network, Offline Use, and Common Pitfalls

InvokeAI downloads model checkpoints and (optionally) Hugging Face metadata on first use, so a working internet connection is assumed during setup. Models that ship with their own tokenizer or remote-config files — Z-Image Turbo is a notable example — will fail to initialize when the host is fully offline because the assets are fetched lazily at session start. This is the root cause of the "Z-Image Turbo Generation Does Not Work Without Internet Access" report (`#9031`); the workaround is either to pre-download the required files into the model cache or to point `invokeai.yaml` at a mirror.

Other issues observed around installation include:

- **Inpainting regression on SDXL** (`#9268`) — the mask is ignored for some SDXL checkpoints in 6.13.0; reverting to 6.12.x or switching the base model temporarily resolves it.
- **PatchMatch / `libtiff` ABI mismatch** (`#9287`) — caused by the container image bundling a newer libjpeg than the system expects; rebuilding the launcher venv after `apt upgrade libtiff` typically fixes it.
- **Workflow editor UI hangs** (`#9285`) — dragging selected text inside a Move node can deadlock the canvas; reported on Windows with the bundled Electron shell.
- **Multi-user mode** introduced in v6.12.0 changes the install footprint slightly because it expects per-user `invokeai.yaml` overrides under the configured root.

Source: [README.md:40-120](), [docs/src/content/docs/start-here/installation.mdx:60-160]()

## Post-Install Checklist

After the server starts (`http://localhost:9090` by default), verify:

1. The launcher or Docker log shows "Model manager ready" without `PatchMatch` or CUDA errors.
2. The Model Manager UI lists at least one base model imported from `models/` (or downloaded via the UI).
3. A small `512×512` SD 1.5 generation completes end-to-end before loading larger SDXL/FLUX checkpoints.
4. `invokeai.yaml` and any `api_keys.yaml` are readable only by the invoking user — relevant because v6.13.7 shipped as a security patch that closes a path to read those files across user boundaries.

Source: [docs/src/content/docs/start-here/installation.mdx:160-220](), [README.md:120-180]()

---

<a id='page-2'></a>

## System Architecture: Backend, Frontend & API

### Related Pages

Related topics: [Overview, Installation & System Requirements](#page-1), [Supported Models & Generation Pipelines](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [invokeai/app/api_app.py](https://github.com/invoke-ai/InvokeAI/blob/main/invokeai/app/api_app.py)
- [invokeai/app/api/routers/images.py](https://github.com/invoke-ai/InvokeAI/blob/main/invokeai/app/api/routers/images.py)
- [invokeai/app/api/sockets.py](https://github.com/invoke-ai/InvokeAI/blob/main/invokeai/app/api/sockets.py)
- [invokeai/app/services/invocation_services.py](https://github.com/invoke-ai/InvokeAI/blob/main/invokeai/app/services/invocation_services.py)
- [invokeai/app/services/session_processor/session_processor_default.py](https://github.com/invoke-ai/InvokeAI/blob/main/invokeai/app/services/session_processor/session_processor_default.py)
- [invokeai/app/services/shared/sqlite_migrator/sqlite_migrator_impl.py](https://github.com/invoke-ai/InvokeAI/blob/main/invokeai/app/services/shared/sqlite_migrator/sqlite_migrator_impl.py)
- [invokeai/frontend/web/src/app/components/App.tsx](https://github.com/invoke-ai/InvokeAI/blob/main/invokeai/frontend/web/src/app/components/App.tsx)
- [invokeai/frontend/web/src/services/api.ts](https://github.com/invoke-ai/InvokeAI/blob/main/invokeai/frontend/web/src/services/api.ts)
</details>

# System Architecture: Backend, Frontend & API

InvokeAI is structured as a three-tier application: a Python backend that performs model inference and orchestrates generation sessions, a FastAPI-based HTTP/WebSocket API layer that exposes those capabilities, and a React/TypeScript frontend that consumes the API. This page documents how these tiers are wired together and where key architectural decisions live.

## High-Level System Layout

The entry point for the server side is `invokeai/app/api_app.py`, which constructs the FastAPI application, attaches the router tree under `invokeai/app/api/routers/`, and starts the WebSocket endpoint defined in `invokeai/app/api/sockets.py`. The same process owns the `InvocationServices` container, which is built in `invokeai/app/services/invocation_services.py` and exposes the subsystems (model loading, queueing, image storage, configuration) that the API handlers depend on. `Source: [invokeai/app/api_app.py:1-120]()`

```
┌─────────────────────────┐      REST + WebSocket       ┌─────────────────────────┐
│  React/TS Frontend      │ <-------------------------> │  FastAPI API (api_app)  │
│  (frontend/web/src)     │                             │  Routers + Sockets      │
└─────────────────────────┘                             └────────────┬────────────┘
                                                                       │
                                                              InvocationServices
                                                                       │
                                              ┌────────────────────────┼────────────────────────┐
                                              │                        │                        │
                                  SessionProcessor (queue)     Model Manager / Images       SQLite Migrator
```

## Backend Services and Session Processing

The backend's core is the session processor, located at `invokeai/app/services/session_processor/session_processor_default.py`. It pulls graph invocations off an internal queue, executes them against the loaded models, and emits progress events back to subscribed WebSocket clients. The processor is event-driven: each `invocation` lifecycle stage publishes events that the socket layer in `invokeai/app/api/sockets.py` forwards to the browser. `Source: [invokeai/app/services/session_processor/session_processor_default.py:1-160]()`

`InvocationServices` is a dependency-injection container assembled in `invokeai/app/services/invocation_services.py`. Routers receive it through FastAPI's `Depends` mechanism rather than importing globals, which keeps the system testable and is what enables the experimental Multi-User Mode introduced in v6.12.0. `Source: [invokeai/app/services/invocation_services.py:40-210]()`

Persistence is handled by a SQLite migrator at `invokeai/app/services/shared/sqlite_migrator/sqlite_migrator_impl.py`, which sequences schema upgrades on startup so that installs upgraded from older releases do not break. Recent upgrades tracked images, boards, and the new workflow graph store. `Source: [invokeai/app/services/shared/sqlite_migrator/sqlite_migrator_impl.py:30-180]()`

## HTTP API and WebSocket Layer

REST endpoints are split across files under `invokeai/app/api/routers/`. The image surface (`invokeai/app/api/routers/images.py`) covers upload, download, delete, metadata, and board membership, returning Pydantic models that the frontend serializes directly. Each route declares its request and response schemas explicitly, which is the contract the frontend TypeScript types in `invokeai/frontend/web/src/services/api.ts` mirror. `Source: [invokeai/app/api/routers/images.py:1-140]()`

Real-time progress — diffusion steps, intermediate previews, queue position — flows over WebSockets from `invokeai/app/api/sockets.py`. The socket maintains a per-session subscription list and re-broadcasts events emitted by the session processor. This dual channel (REST for control, WebSockets for telemetry) is what allows the UI to show live progress for long-running generations such as Z-Image Turbo and FLUX.2 without polling. `Source: [invokeai/app/api/sockets.py:1-110]()`

> Note: Issue #9031 reported that Z-Image Turbo could not generate without internet access, indicating that some generation paths currently rely on remote resources being reachable. Community reports like this shape follow-up work on offline-capable model loading. `Source: [https://github.com/invoke-ai/InvokeAI/issues/9031]()`

## Frontend Application

The web client lives under `invokeai/frontend/web/` and is bootstrapped by `App.tsx`, which sets up the Redux store, routing, and the socket subscription that mirrors the server's event stream into UI state. Components subscribe to selectors that pull from the queue and session slices, so when the WebSocket pushes a new intermediate image the canvas updates without a round-trip through REST. `Source: [invokeai/frontend/web/src/app/components/App.tsx:1-90]()`

`invokeai/frontend/web/src/services/api.ts` wraps the generated OpenAPI client and is the single place where endpoint paths are constructed. Centralizing HTTP access there means router renames in the backend only require updating the TypeScript client rather than chasing down individual fetch calls. `Source: [invokeai/frontend/web/src/services/api.ts:1-80]()`

## Cross-Cutting Concerns

| Concern | Mechanism | Location |
|---|---|---|
| Auth / multi-user | FastAPI dependency on `InvocationServices` per request | `invokeai/app/services/invocation_services.py` |
| Schema evolution | Versioned SQLite migrations on startup | `invokeai/app/services/shared/sqlite_migrator/sqlite_migrator_impl.py` |
| Live progress | WebSocket fan-out from session processor | `invokeai/app/api/sockets.py` |
| Image CRUD | Pydantic-typed REST routes | `invokeai/app/api/routers/images.py` |
| Frontend state | Redux + socket subscription in `App.tsx` | `invokeai/frontend/web/src/app/components/App.tsx` |

Security is enforced at the same boundaries. The v6.13.7 release notes describe a patch that closed a path allowing unauthenticated reads of `invokeai.yaml` and `api_keys.yaml`; the architectural lesson is that configuration endpoints sit behind the same dependency-injected services layer and must therefore inherit the auth dependency applied in `invocation_services.py`. `Source: [https://github.com/invoke-ai/InvokeAI/releases/tag/v6.13.7]()`

Hardware compatibility is also exposed through this stack: ROCm support for `gfx1151` (issue #8655) and the Blackwell (RTX 50-series) launcher crash (issue #9164) are both backend concerns that surface through the same API surface once fixed, so the routers in `invokeai/app/api/routers/` rarely need to change. `Source: [https://github.com/invoke-ai/InvokeAI/issues/8655]()`

Taken together, the architecture's defining property is the inversion between a long-lived `InvocationServices` container and a thin transport layer (REST + WebSockets). The frontend never touches model code directly; it only consumes typed contracts from `api.ts` and event streams from `sockets.py`, while the backend's session processor owns the actual diffusion lifecycle.

---

<a id='page-3'></a>

## Supported Models & Generation Pipelines

### Related Pages

Related topics: [System Architecture: Backend, Frontend & API](#page-2), [Core Features: Unified Canvas, Workflows, Gallery & Multi-User](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [invokeai/app/invocations/flux_denoise.py](https://github.com/invoke-ai/InvokeAI/blob/main/invokeai/app/invocations/flux_denoise.py)
- [invokeai/app/invocations/flux2_denoise.py](https://github.com/invoke-ai/InvokeAI/blob/main/invokeai/app/invocations/flux2_denoise.py)
- [invokeai/app/invocations/z_image_denoise.py](https://github.com/invoke-ai/InvokeAI/blob/main/invokeai/app/invocations/z_image_denoise.py)
- [invokeai/app/invocations/qwen_image_denoise.py](https://github.com/invoke-ai/InvokeAI/blob/main/invokeai/app/invocations/qwen_image_denoise.py)
- [invokeai/app/invocations/anima_denoise.py](https://github.com/invoke-ai/InvokeAI/blob/main/invokeai/app/invocations/anima_denoise.py)
- [invokeai/app/invocations/cogview4_denoise.py](https://github.com/invoke-ai/InvokeAI/blob/main/invokeai/app/invocations/cogview4_denoise.py)
</details>

# Supported Models & Generation Pipelines

InvokeAI is built around a modular **invocation graph**. Each supported diffusion model family is exposed as one or more `BaseInvocation` subclasses that produce images by running a denoising loop against the appropriate architecture. A new model can therefore be onboarded by adding a single new `*_denoise.py` module rather than by rewriting the engine. The model-management layer, scheduler, and node editor all consume these invocations uniformly.

## Architecture: One Denoise Module per Family

Every modern text-to-image pipeline lives under `invokeai/app/invocations/` as a self-contained `*_denoise.py` file. The pattern is consistent across model families: the file declares a `BaseInvocation` subclass with pydantic input/output models, references the appropriate model-config record types (e.g., `FluxModelConfig`, `ZImageModelConfig`), and delegates the actual sampling loop to the shared backend. This keeps the orchestration logic in one place while letting each model expose only the parameters it actually needs (guidance, distilled vs. full, mmrope-style positional encodings, etc.).

| Model Family | Denoise Invocation | Notes |
|---|---|---|
| FLUX / FLUX.1 | `flux_denoise.py` | Long-standing community request (#6712). |
| FLUX.2 | `flux2_denoise.py` | Enhanced support added in v6.12.0. |
| Z-Image (Turbo) | `z_image_denoise.py` | Alibaba distilled model; issue #8670. |
| Qwen Image | `qwen_image_denoise.py` | New in v6.13.0 release line. |
| Anima | `anima_denoise.py` | Latest family added. |
| CogView4 | `cogview4_denoise.py` | Distinct Chinese-language-conditioned model. |

Source: [invokeai/app/invocations/flux_denoise.py:1-1](), [invokeai/app/invocations/flux2_denoise.py:1-1](), [invokeai/app/invocations/z_image_denoise.py:1-1](), [invokeai/app/invocations/qwen_image_denoise.py:1-1](), [invokeai/app/invocations/anima_denoise.py:1-1](), [invokeai/app/invocations/cogview4_denoise.py:1-1]().

## Per-Family Pipelines and Parameters

### FLUX and FLUX.2
The original `FluxDenoiseInvocation` exposes guidance-distilled and full-guidance modes, plus the standard conditioning inputs (positive/negative prompts, width/height, seed). `Flux2DenoiseInvocation` reuses this structure but adds parameters specific to the FLUX.2 architecture released in v6.12.0. Community request #6712 (54 comments) tracks the long-running demand for first-class FLUX.1 support and is now closed by these modules.

Source: [invokeai/app/invocations/flux_denoise.py:1-1](), [invokeai/app/invocations/flux2_denoise.py:1-1]().

### Z-Image (Turbo)
`ZImageDenoiseInvocation` targets the distilled Z-Image Turbo variant. Because Turbo is a distilled checkpoint, the invocation typically exposes fewer steps by default and is optimised for fast generation. Community issue #8670 tracks the original enhancement request and #9031 reports a regression where Z-Image Turbo fails to generate without internet access (model loading depends on resolving auxiliary metadata online).

Source: [invokeai/app/invocations/z_image_denoise.py:1-1]().

### Qwen Image
`QwenImageDenoiseInvocation` was introduced during the v6.13.0 release cycle (rc1, rc2, rc3, and final v6.13.0). It is the first family to land through the new model onboarding flow that supports Qwen-style autoregressive-aware conditioning. The v6.13.0 release notes explicitly call out Qwen Image as a "new locally-hosted model."

Source: [invokeai/app/invocations/qwen_image_denoise.py:1-1]().

### Anima
The newest family shipped in the current release line. `AnimaDenoiseInvocation` follows the same template as the others; the community has not yet produced significant issue traffic for it.

Source: [invokeai/app/invocations/anima_denoise.py:1-1]().

### CogView4
`CogView4DenoiseInvocation` is the Chinese-language-conditioned pipeline. It is registered alongside the English-trained families and shares the same scheduler, but uses a separate text encoder configuration.

Source: [invokeai/app/invocations/cogview4_denoise.py:1-1]().

## Known Limitations and Community-Reported Issues

Several recurring community discussions map directly onto the invocation layer:

- **SDXL inpainting regression (v6.13.0)** — issue #9268 reports that the inpainting mask is ignored when an SDXL main model is loaded, indicating the inpaint path does not always inherit the same conditioning plumbing as `*_denoise.py`.
- **Z-Image Turbo offline failure** — issue #9031 reports generation failing on systems without internet access, suggesting the Z-Image denoise path still resolves remote metadata at load time.
- **Launcher crash on RTX 50-series (Blackwell)** — issue #9164 (a 0x80000003 breakpoint) prevents model loading entirely on the newest NVIDIA GPUs; this affects every pipeline, not a single family.
- **PatchMatch library mismatch** — issue #9287 affects the inpaint helper used by older SDXL flows, not the denoise invocations directly.

## Choosing a Pipeline

For most users the practical guidance is:

1. Pick a model family based on the desired aesthetic — FLUX/FLUX.2 for high quality, Z-Image Turbo for speed, Qwen Image and Anima for newer experimental outputs, CogView4 for Chinese-language prompts.
2. The model is registered once via the Model Manager; the corresponding `*_denoise.py` invocation is then available as a node in the graph editor without further wiring.
3. Conditioning (positive/negative prompts, ControlNet, IP-Adapter) is fed in via shared base classes, so the same workflow nodes work across families.

This separation between *invocation* (what the node graph does) and *model config* (which checkpoint is loaded) is what lets InvokeAI ship a new family like Qwen Image or Anima in a point release without touching the engine core.

Source: [invokeai/app/invocations/flux_denoise.py:1-1](), [invokeai/app/invocations/flux2_denoise.py:1-1](), [invokeai/app/invocations/z_image_denoise.py:1-1](), [invokeai/app/invocations/qwen_image_denoise.py:1-1](), [invokeai/app/invocations/anima_denoise.py:1-1](), [invokeai/app/invocations/cogview4_denoise.py:1-1]().

---

<a id='page-4'></a>

## Core Features: Unified Canvas, Workflows, Gallery & Multi-User

### Related Pages

Related topics: [System Architecture: Backend, Frontend & API](#page-2), [Supported Models & Generation Pipelines](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [invokeai/frontend/web/src/features/controlLayers/konva/CanvasManager.ts](https://github.com/invoke-ai/InvokeAI/blob/main/invokeai/frontend/web/src/features/controlLayers/konva/CanvasManager.ts)
- [invokeai/frontend/web/src/features/controlLayers/components/InvokeCanvasComponent.tsx](https://github.com/invoke-ai/InvokeAI/blob/main/invokeai/frontend/web/src/features/controlLayers/components/InvokeCanvasComponent.tsx)
- [invokeai/frontend/web/src/features/controlLayers/components/RasterLayer/RasterLayer.tsx](https://github.com/invoke-ai/InvokeAI/blob/main/invokeai/frontend/web/src/features/controlLayers/components/RasterLayer/RasterLayer.tsx)
- [invokeai/frontend/web/src/features/controlLayers/components/ControlLayer/ControlLayer.tsx](https://github.com/invoke-ai/InvokeAI/blob/main/invokeai/frontend/web/src/features/controlLayers/components/ControlLayer/ControlLayer.tsx)
- [invokeai/frontend/web/src/features/controlLayers/components/RegionalGuidance/RegionalGuidance.tsx](https://github.com/invoke-ai/InvokeAI/blob/main/invokeai/frontend/web/src/features/controlLayers/components/RegionalGuidance/RegionalGuidance.tsx)
- [invokeai/frontend/web/src/features/controlLayers/components/InpaintMask/InpaintMask.tsx](https://github.com/invoke-ai/InvokeAI/blob/main/invokeai/frontend/web/src/features/controlLayers/components/InpaintMask/InpaintMask.tsx)
- [invokeai/frontend/web/src/features/workflow/](https://github.com/invoke-ai/InvokeAI/tree/main/invokeai/frontend/web/src/features/workflow)
- [invokeai/frontend/web/src/features/gallery/components/ImageGallery.tsx](https://github.com/invoke-ai/InvokeAI/blob/main/invokeai/frontend/web/src/features/gallery/components/ImageGallery.tsx)
- [invokeai/app/services/users/users_base.py](https://github.com/invoke-ai/InvokeAI/blob/main/invokeai/app/services/users/users_base.py)

</details>

# Core Features: Unified Canvas, Workflows, Gallery & Multi-User

This page describes four foundational capability areas of InvokeAI: the Unified Canvas, the Workflow editor, the Gallery, and the Multi-User backend introduced in v6.12.0. Together they form the daily-use surface of the application and define how users author, run, persist, and share generations.

## Unified Canvas (Control Layers)

The Unified Canvas is the central editing surface where users compose raster layers, ControlNet guidance, regional prompts, and inpaint masks before invoking generation. It is built on Konva and lives under `invokeai/frontend/web/src/features/controlLayers/`.

The canvas exposes four layer categories, each with its own React component:

- **RasterLayer** — base image and user-uploaded images used as the canvas background and blending input.
- **ControlLayer** — ControlNet conditioning images (Canny, Depth, IP-Adapter, etc.).
- **RegionalGuidance** — user-painted regions paired with their own prompts, producing regionally-different generations.
- **InpaintMask** — mask defining which areas the model should regenerate.

These layers are rendered through a single `CanvasManager`, which coordinates the Konva stage, event handling, and serialization of the layer tree for both rendering and queue submission. `InvokeCanvasComponent` is the React entry point that mounts the manager into the application shell.

### Architecture and State

Canvas state is held in a staging-area slice that tracks the layer list, the active layer, selection, tool state, and per-layer transforms (position, scale, opacity). When the user invokes generation, the staging state is flattened into the queue-item parameters consumed by the backend.

```mermaid
flowchart LR
  A[RasterLayer] --> D[CanvasManager]
  B[ControlLayer] --> D
  C[RegionalGuidance] --> D
  E[InpaintMask] --> D
  D --> F[Queue Item Parameters]
  F --> G[(Backend Session)]
```

The same layer model is reused for img2img, inpainting, and ControlNet workflows, so users do not need to switch modes to combine them. Community reports show that inpainting-mask handling has been a recurring source of bugs across model families — masks being ignored with SDXL on RTX 4060 hardware (`#9268`) and canvas UI hangs when selecting text inside the Move node (`#9285`). PatchMatch-based inpainting is also affected by host-library ABI mismatches (`#9287`).

Source: [invokeai/frontend/web/src/features/controlLayers/konva/CanvasManager.ts]()

Source: [invokeai/frontend/web/src/features/controlLayers/components/InvokeCanvasComponent.tsx]()

Source: [invokeai/frontend/web/src/features/controlLayers/components/RasterLayer/RasterLayer.tsx]()

Source: [invokeai/frontend/web/src/features/controlLayers/components/ControlLayer/ControlLayer.tsx]()

Source: [invokeai/frontend/web/src/features/controlLayers/components/RegionalGuidance/RegionalGuidance.tsx]()

Source: [invokeai/frontend/web/src/features/controlLayers/components/InpaintMask/InpaintMask.tsx]()

## Workflows (Node Editor)

The Workflow editor under `invokeai/frontend/web/src/features/workflow/` is a node-based graph editor that mirrors the same conceptual model as the Canvas (raster, control, regional, inpaint) but expresses them as graph nodes. Nodes have typed inputs and outputs and can be saved, loaded, and shared as workflow JSON files.

Workflows are the canonical serialization format InvokeAI uses for batchable generation graphs. Saving a Workflow captures the graph topology, parameter values, model selections, and the seed. Workflows integrate bidirectionally with the Canvas: a saved workflow can be opened, its parameters edited on the Canvas, and the result saved back as a workflow.

## Gallery

The Gallery stores every image produced by InvokeAI, indexed by session, workflow, and metadata. It is implemented under `invokeai/frontend/web/src/features/gallery/`, with `ImageGallery.tsx` providing the grid view and per-image detail panel.

The Gallery is the entry point for downstream actions: sending an image back to the Canvas as a `RasterLayer`, using it as a ControlNet reference, opening its originating workflow, or exporting it. Images are persisted in the session directory and indexed through the backend image service so that the Gallery can be filtered, searched, and paginated.

Source: [invokeai/frontend/web/src/features/gallery/components/ImageGallery.tsx]()

## Multi-User Mode (v6.12.0+)

Starting with v6.12.0, InvokeAI can be configured to support multiple accounts on the same backend. Each account has its own session, image history, workflows, and uploads, while sharing the installed models and the GPU. The multi-user plumbing lives under `invokeai/app/services/users/`, where `users_base.py` defines the `UsersService` abstract interface that concrete stores implement.

Multi-user mode is gated by configuration and is still labelled experimental in the v6.12.0 release notes. In single-user mode (the default), the backend behaves exactly as in earlier versions and no user concept is required. Subsequent 6.13.x releases add further model support (Qwen Image, FLUX.2, Z-Image Turbo, GPT Image) on top of this user-scoped foundation — see the v6.13.0 release notes for details, and note that 6.13.7 is a security patch affecting `invokeai.yaml` and `api_keys.yaml` exposure.

Source: [invokeai/app/services/users/users_base.py]()

Source: [invokeai/frontend/web/src/features/workflow/]()

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Pitfall Log

Project: invoke-ai/InvokeAI

Summary: Found 30 structured pitfall item(s), including 7 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

## 1. Installation risk - Installation risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/invoke-ai/InvokeAI/issues/8655

## 2. Installation risk - Installation risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/invoke-ai/InvokeAI/issues/9164

## 3. Installation risk - Installation risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/invoke-ai/InvokeAI/issues/9285

## 4. Installation risk - Installation risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/invoke-ai/InvokeAI/issues/9287

## 5. Installation risk - Installation risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/invoke-ai/InvokeAI/issues/9031

## 6. Security or permission risk - Security or permission risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Developers should check this security_permissions risk before relying on the project: [bug]: PatchMatch fails to load due to libtiff/libjpeg ABI mismatch (jpeg12_* unresolved at runtime)
- User impact: Developers may expose sensitive permissions or credentials: [bug]: PatchMatch fails to load due to libtiff/libjpeg ABI mismatch (jpeg12_* unresolved at runtime)
- Evidence: failure_mode_cluster:github_issue | https://github.com/invoke-ai/InvokeAI/issues/9287

## 7. Security or permission risk - Security or permission risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/invoke-ai/InvokeAI/issues/9268

## 8. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: InvokeAI 6.13.0
- User impact: Upgrade or migration may change expected behavior: InvokeAI 6.13.0
- Evidence: failure_mode_cluster:github_release | https://github.com/invoke-ai/InvokeAI/releases/tag/v6.13.0

## 9. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: Version 6.13.0.rc2
- User impact: Upgrade or migration may change expected behavior: Version 6.13.0.rc2
- Evidence: failure_mode_cluster:github_release | https://github.com/invoke-ai/InvokeAI/releases/tag/v6.13.0.rc2

## 10. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: Version 6.13.0.rc3
- User impact: Upgrade or migration may change expected behavior: Version 6.13.0.rc3
- Evidence: failure_mode_cluster:github_release | https://github.com/invoke-ai/InvokeAI/releases/tag/v6.13.0.rc3

## 11. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: [bug]: Add support for ROCm version for gfx1151 (Rocm >= 6.4)
- User impact: Developers may fail before the first successful local run: [bug]: Add support for ROCm version for gfx1151 (Rocm >= 6.4)
- Evidence: failure_mode_cluster:github_issue | https://github.com/invoke-ai/InvokeAI/issues/8655

## 12. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: [bug]: Inpainting mask ignored with SDXL model
- User impact: Developers may fail before the first successful local run: [bug]: Inpainting mask ignored with SDXL model
- Evidence: failure_mode_cluster:github_issue | https://github.com/invoke-ai/InvokeAI/issues/9268

## 13. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: [bug]: Launcher crashes on startup with breakpoint exception (0x80000003) on systems with NVIDIA RTX 50-series (Blackwell) GPUs
- User impact: Developers may fail before the first successful local run: [bug]: Launcher crashes on startup with breakpoint exception (0x80000003) on systems with NVIDIA RTX 50-series (Blackwell) GPUs
- Evidence: failure_mode_cluster:github_issue | https://github.com/invoke-ai/InvokeAI/issues/9164

## 14. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: [bug]: Move node's selected text hangs/crash the web interface UI
- User impact: Developers may fail before the first successful local run: [bug]: Move node's selected text hangs/crash the web interface UI
- Evidence: failure_mode_cluster:github_issue | https://github.com/invoke-ai/InvokeAI/issues/9285

## 15. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: [bug]: Z-Image Turbo Generation Does Not Work Without Internet Access
- User impact: Developers may fail before the first successful local run: [bug]: Z-Image Turbo Generation Does Not Work Without Internet Access
- Evidence: failure_mode_cluster:github_issue | https://github.com/invoke-ai/InvokeAI/issues/9031

## 16. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: v6.10.0
- User impact: Upgrade or migration may change expected behavior: v6.10.0
- Evidence: failure_mode_cluster:github_release | https://github.com/invoke-ai/InvokeAI/releases/tag/v6.10.0

## 17. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: v6.10.0rc2
- User impact: Upgrade or migration may change expected behavior: v6.10.0rc2
- Evidence: failure_mode_cluster:github_release | https://github.com/invoke-ai/InvokeAI/releases/tag/v6.10.0rc2

## 18. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: v6.11.0
- User impact: Upgrade or migration may change expected behavior: v6.11.0
- Evidence: failure_mode_cluster:github_release | https://github.com/invoke-ai/InvokeAI/releases/tag/v6.11.0

## 19. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: v6.12.0
- User impact: Upgrade or migration may change expected behavior: v6.12.0
- Evidence: failure_mode_cluster:github_release | https://github.com/invoke-ai/InvokeAI/releases/tag/v6.12.0

## 20. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: v6.12.0rc1
- User impact: Upgrade or migration may change expected behavior: v6.12.0rc1
- Evidence: failure_mode_cluster:github_release | https://github.com/invoke-ai/InvokeAI/releases/tag/v6.12.0rc1

## 21. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: v6.13.0rc1
- User impact: Upgrade or migration may change expected behavior: v6.13.0rc1
- Evidence: failure_mode_cluster:github_release | https://github.com/invoke-ai/InvokeAI/releases/tag/v6.13.0.rc1

## 22. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/invoke-ai/InvokeAI/issues/9373

## 23. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: v6.11.1
- User impact: Upgrade or migration may change expected behavior: v6.11.1
- Evidence: failure_mode_cluster:github_release | https://github.com/invoke-ai/InvokeAI/releases/tag/v6.11.1

## 24. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://github.com/invoke-ai/InvokeAI

## 25. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/invoke-ai/InvokeAI

## 26. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://github.com/invoke-ai/InvokeAI

## 27. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://github.com/invoke-ai/InvokeAI

## 28. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/invoke-ai/InvokeAI/issues/9372

## 29. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/invoke-ai/InvokeAI

## 30. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/invoke-ai/InvokeAI

<!-- canonical_name: invoke-ai/InvokeAI; human_manual_source: deepwiki_human_wiki -->