Grimoire
Installation
Run the setup wizard, configure ports, and bring up the local runtime.
Black Magik Installation Guide
The first time you launch Aseprite with Grimoire enabled, Black Magik runs a setup wizard. It checks for active setup ports, detects leftovers from earlier installs, opens the install docs in your browser, and then drives the full runtime setup from inside Aseprite.
What The Wizard Installs
| Step | What it sets up |
|---|---|
| UV + Python 3.13 | Installs UV if needed and provisions Python through it. |
| ComfyUI | Clones ComfyUI into the extension folder. |
| ComfyUI Manager | Installs the manager used for custom node maintenance. |
| Custom Nodes | Installs IPAdapter Plus, ComfyUI Essentials, OpenPose, DepthAnything V3, Inspyrenet Rembg, and PixelArt Detector. |
| Bundled Models | Downloads the IPAdapter SDXL and ControlNet model assets used by the built-in workflows. |
| Middleman Server | Sets up the Python service that bridges Aseprite, hosted APIs, and ComfyUI. |
| Preferences | Prompts for ports and generation-history limit after the files are ready. |
PyTorch is installed with --torch-backend=auto, so the setup picks the best backend it can detect for your machine.
What The Wizard Asks You
Previous installation cleanup
If Black Magik finds lingering black-magic files, it offers:
- Keep Existing (Faster): reuse the old install where possible
- Delete Existing (Cleaner): remove old files before reinstalling
- Cancel Installation: stop before any setup work starts
Preferred ports, history, and sampling
Near the end of setup, Grimoire asks for:
- ComfyUI Port: default
8288 - Middleman Port: default
8388 - Generation History Save Limit: default
20 - Show Workflow Queue: enabled by default
- Show Seed Number: disabled by default; warning that it may cause the UI scrollbar to jump
Recommended screen scaling
The installer also recommends Aseprite Screen Scaling = 200% because Grimoire’s dialog is more comfortable at that size. It can open Preferences for you, but you can keep your current setting if you prefer.
Platform Behavior
| Platform | What to expect |
|---|---|
| Windows | The installer runs in the background to avoid repeated console flashes. |
| macOS / Linux | The installer opens a visible terminal alongside the in-Aseprite progress dialog. |
| macOS / Linux after setup | Black Magik auto-starts its runtime services when Aseprite launches. |
| Windows after setup | Use the menu or Settings tab to start the services when needed. |
What You Still Need To Provide
Git
The installer checks for git and opens the download page if it is missing.
- Windows: https://git-scm.com/downloads/win
- macOS: https://git-scm.com/downloads/mac
- Linux: https://git-scm.com/downloads/linux
Aseprite
Install Aseprite first: https://www.aseprite.org/
GPU drivers
If you want local GPU acceleration, install the correct drivers before or after setup:
- NVIDIA CUDA: https://developer.nvidia.com/cuda-downloads
- AMD ROCm: https://pytorch.org/get-started/locally/
- Apple Silicon uses MPS automatically when available
If the correct GPU backend is not available during setup, PyTorch can fall back to CPU.
Logs And Failure Recovery
If installation fails, Black Magik keeps a session log at:
- Windows:
%APPDATA%\\Aseprite\\extensions\\black-magic\\setup.log - macOS:
~/Library/Application Support/Aseprite/extensions/black-magic/setup.log - Linux:
~/.config/aseprite/extensions/black-magic/setup.log
The failure dialog includes Report Bug, which opens a prefilled issue link with setup context. Start there before manually deleting folders.
You can rerun the full wizard later from:
- Edit > Black Magic > Installation > Restart Installation
That flow rechecks ports, detects old files again, and lets you keep or clean them before reinstalling. The same Installation submenu also includes Uninstall Cleanup, which cleans Black Magik runtime files and opens Aseprite’s extensions folder so you can remove the extension cleanly.
First Steps After Setup
1. Open Grimoire
Go to Edit > Black Magic > Generate Image.
2. Start or verify the servers
Open Settings and use Start Servers or Server Status. You can also do this from Edit > Black Magic > Servers. If a configured port is already in use, Grimoire reports that the servers were not started instead of launching a conflicting runtime.
3. Decide between local and hosted generation
- Local tabs need imported models such as checkpoints, LoRAs, IPAdapter assets, and ControlNet models.
- API tab does not need local checkpoints, but it still uses the Black Magik runtime services.
4. Import a checkpoint if you want local generation
In Settings, choose checkpoints, select a .safetensors file, and click Import Model.