A local-first atelier for generative images and video.
Create on your own GPU, shape every detail, and keep every result understandable.

Install · Features · Workflow · User guide · Documentation · Remote GPU · Contribute

From the first prompt to the final archive, The Wizard's Brush keeps creation, editing, queueing, comparison, and provenance in one coherent studio.

The Wizard's Brush is more than a prompt box wrapped around a model. It brings model-aware controls, durable queues, live previews, editing and finishing, searchable assets, reusable recipes, and portable exports into one private workspace. The interface starts simple and reveals its full control surface only when you want it.

Important

The application source is FOSS under Apache-2.0. Model weights, adapters, the NVIDIA driver, and CUDA runtime components have separate terms. Read the model and weight license inventory before use.

The whole creative loop

	Built for
Create and transform	Text-to-image, img2img, inpaint, outpaint, ControlNet, instruction editing, image-to-video, text-to-video, and finishing
Use the right controls	Each generator publishes its real capabilities, defaults, and limits; the interface adapts to the selected model
Keep work moving	Durable queues, live previews, restart recovery, cancellation, and independent local and remote lanes
Build a real library	Search, captions, tags, collections, favorites, ratings, comparison, soft delete, and portable export
Reproduce with confidence	Seeds, effective parameters, adapters, model identity, lineage, and finishing operations stay with each asset
Own the workspace	Localhost defaults, project-contained storage, optional API authentication, and metadata controls

Finishing uses tiled Real-ESRGAN upscaling and GFPGAN face restoration, with optional auto-detailing and RIFE frame interpolation. These are explicit, recorded steps rather than invisible changes to the generated file.

Quick start

Requirements

• Linux or WSL2 on x86-64.
• An NVIDIA CUDA GPU; 16 GB VRAM is the release-tested local baseline.
• Git, GNU Make, Bash, curl, tar/xz, sha256sum, and realpath.
• About 40 GB free for the starter profile. Optional local models can raise the cache requirement above 90 GB.

Python and Node are not host prerequisites. The installer downloads pinned copies under .runtime/ and keeps package caches inside the checkout.

Standalone release - recommended

Download the linux-x86_64.tar.xz asset and its adjacent checksum from the latest release, verify and extract them, then run:

sha256sum -c wizards-brush-*.tar.xz.sha256
tar -xJf wizards-brush-*.tar.xz
cd wizards-brush-*-linux-x86_64
cp .env.example .env
./install.sh --with-models
./start.sh

The standalone archive contains a prebuilt frontend, so it needs neither Git, Make, Node, nor the repository's tests and contributor files.

Source checkout

Use the source path when contributing, changing the frontend, or following the latest development branch:

git clone https://github.com/wizards-ecosystem/wizards-brush.git
cd wizards-brush
cp .env.example .env
make install     # tools, locked dependencies, frontend; no model weights
make models      # the enabled starter model + curated adapters
make start

Open http://127.0.0.1:8000, then visit Diagnosis before the first large render. A first load can take several minutes even after the model is cached.

Tip

After reviewing .env, make setup combines make install and make models. The starter model is ungated, so HF_TOKEN can remain empty unless you choose a gated or private repository.

See the complete getting-started guide for WSL, trusted-LAN access, backups, updates, troubleshooting, cleaning, and removal. For any listener beyond localhost, read network security before changing HOST.

From prompt to library

describe or supply media
          |
          v
 choose a process --> Simple controls --> durable local/remote queue
                                                |
                                                v
                                   preview --> result --> gallery
                                                            |
                         reuse settings <--> compare <--> export

The Simple form is the default and always includes a prompt. Full controls adds model choice, schedulers, guidance, adapters, masks, deterministic seeds, wildcards, X/Y grids, and explicit finishing steps when the selected generator can actually use them.

Local and remote compute

The local lane ships with an intentionally small public profile:

• Z-Image-Turbo enabled as the Apache-2.0 starter checkpoint.
• Z-Image base, FLUX.2 Klein 4B, SDXL, Chroma, and FLUX.1 slots available as explicit .env opt-ins.
• One resident pipeline at a time, with model-aware quantization, CPU offload, VRAM guards, and visible swap/load stages.

The optional Remote GPU lane supports large image, editing, and video models on a machine you own or are explicitly authorized to expose. It is not a hosted service. The generated remote_gpu_filled.py contains secrets, stays ignored, and reports a build fingerprint so stale workers are visible.

The generated worker is provider-neutral and can run from a shell or an interactive notebook on a compatible Linux GPU runtime. Read the Remote GPU guide before deploying it.

Your work stays yours

.runtime/              pinned tools, caches, temp, contained browser profile
.venv/                 project Python environment
frontend/node_modules/ locked frontend dependencies
models/                 downloaded checkpoints, tool weights, local LoRAs
output/                 SQLite, generated media, thumbnails, uploads, settings
wildcards/              editable prompt lists
.env                    local configuration and secrets

make doctor proves that every active writable path resolves inside the checkout. Back up output/, wildcards/, models/loras/, and the private .env; the rest can be recreated. See the user guide for queue, gallery, prompt, adapter, finishing, and export behavior.

Shape the studio

Every supported setting is explained in .env.example. Common groups are:

Settings	Purpose
LOCAL_IMAGE_MODEL*, LOCAL_QUANT, LOCAL_OFFLOAD	Local model slots and memory strategy
A100_IMAGE_MODEL*, QWEN_EDIT_MODEL, VIDEO_MODEL	Optional Remote GPU model catalogue
REMOTE_GPU_BASE_URL, REMOTE_GPU_SHARED_SECRET	Remote endpoint and authentication
HOST, PORT, API_TOKEN, CORS_ORIGINS	Browser/API exposure
EMBED_METADATA, EMBED_PROVENANCE	Replay metadata and AI-origin declaration
OUTPUT_DIR, HF_HOME, LORA_DIR, RUNTIME_DIR	Project-contained storage paths

Fresh installs bind to 127.0.0.1. To use a trusted LAN, set HOST=0.0.0.0 and a long API_TOKEN, restart, and enter the token in the browser's Settings page. Do not expose the bare development or application server to the internet. Startup refuses a non-loopback host without that token; the network guide covers TLS termination and the narrowly scoped WSL firewall helper.

Build, run, and verify

Command	Purpose
make install	Install locked tools/dependencies and build; skip model weights
make setup	Install everything, including enabled local models
make models / make models-status	Download or audit the configured model profile
make install-nunchaku	Install an explicitly URL- and SHA-pinned native wheel (advanced)
make start / make stop	Serve the built app on the configured host and port
make dev / make browser-dev	Run reload servers / open the contained browser profile
make doctor	Verify the project-contained runtime boundary
make check	Backend lint, types, tests plus frontend lint, format, tests, build
make release-check	Full local release gate including containment and dependency checks
make release-bundle	Build and verify the minimal checksummed Linux archive
make remote-gpu	Generate the ignored operator worker from .env
make clean-build / make clean-cache / make clean-runtime	Remove increasingly broad rebuildable state

Run make help for the complete list.

Open source, with clear boundaries

The application is licensed under the Apache License 2.0. The NOTICE records permissively reused material and the clean-room boundary around GPL/AGPL projects that were studied but never copied. Third-party notices cover bundled browser libraries and fonts, while release SBOMs inventory both locked dependency graphs. The exploration ledger preserves the reasoning behind upstream-derived ideas.

Before contributing, read CONTRIBUTING.md, GOVERNANCE.md, and the Code of Conduct. Ordinary problems follow SUPPORT.md; vulnerabilities follow SECURITY.md and must not be posted publicly.

The project is pre-1.0. Review CHANGELOG.md for release-facing changes, the distribution design for artifact contents, and the release checklist for the maintainer gate.