ZumiForge
Make images and videos from text prompts, using free models that run on your Mac, or paid cloud models from fal.ai, Replicate, Runware, Google, OpenAI and xAI, all from one page.
Getting started
ZumiForge is a Mac app. It lives in your menu bar, runs a small server on your Mac that does the work (running local models and talking to cloud services), and opens ZumiForge in Chrome, where you use it. Nothing is hosted online; your images, prompts and keys stay on your Mac.
What you need
- A Mac with Apple silicon (M1 or newer) and macOS 13 or later.
- Enhance and AI variations rewrite prompts with Gemini, using your Google AI key (a fraction of a cent per prompt). Without a key they fall back to Chrome's built-in AI when ZumiForge is open in Chrome.
- For local models: 32 GB of memory is comfortable; 16 GB works for the smaller models. Each model is a 6–70 GB download, so allow plenty of disk space.
- For cloud models only: an account with fal.ai, Replicate, Runware, Google AI Studio, OpenAI or xAI. No model downloads.
You don't need Node.js or any developer tools: the app carries its own copy of everything its server needs.
1. Install ZumiForge
Open the Terminal app (press ⌘ Space, type "Terminal", press Return), paste this and press Return:
curl -fsSL https://zumilabs.com/tools/zumiforge/install.sh | sh
- It downloads ZumiForge, checks it against its published checksum, installs it in Applications and opens it. Its icon (two photos with a Z) appears in the menu bar at the top of the screen.
- The first time, it asks where to save your images and videos. It suggests
~/Pictures/ZumiForge; choose another folder if you like. You can change it later from the menu bar icon. - ZumiForge then opens in Chrome. In ZumiForge's ☰ menu, choose Install ZumiForge as an app (or use the install icon at the right of Chrome's address bar). It then has its own window and Dock icon, and the menu bar icon opens that window.
Why Terminal? ZumiForge isn't signed with an Apple Developer ID yet. Installed from Terminal, macOS doesn't treat it as downloaded from the internet, so it opens without warnings. You can also download ZumiForge-mac.zip, unzip it and drag ZumiForge into Applications; the first time you open it, macOS blocks it, and you allow it in System Settings → Privacy & Security → Open Anyway.
2. The menu bar icon
ZumiForge has no Dock icon of its own; it lives in the menu bar. Its menu shows whether the server is running and where images are saved, and has:
- Open ZumiForge: the installed ZumiForge app if you installed it from Chrome, otherwise a Chrome tab. Opening ZumiForge from Applications or Spotlight does the same.
- Show images in Finder and Change image folder…
- Start at login, so ZumiForge is always ready (it starts quietly, without opening a window).
- Restart the server and Open the log, if something isn't working.
- Quit ZumiForge, which also stops any local model that's running.
To update, run the install command again; your history, settings and keys are kept.
3. Tools for local models (skip for cloud only)
Local models run through mflux, a separate free tool. In Terminal, one command at a time:
- Homebrew installs the other tools. Skip this if you already have it (
brew --versionprints a version).
When it finishes, it prints two or three "Next steps" commands that add Homebrew to your PATH. Run them./bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" - uv installs Python tools, and ffmpeg handles video files:
brew install uv ffmpeg - mflux runs the image models:
uv tool install --upgrade mflux - Then choose Restart the server from the ZumiForge menu bar icon, so it finds mflux.
☰ → Local models in ZumiForge checks each of these and shows what's missing.
4. Hugging Face token (for local models)
Local models are downloaded from Hugging Face, a free site that hosts AI models. You need a free account and an access token.
- Create an account at huggingface.co/join.
- Open Settings → Access Tokens → Create new token.
- Choose Fine-grained, give it a name such as "zumiforge", and tick only "Read access to contents of all public gated repos you can access". Don't choose Full Access: ZumiForge only needs to download.
- Press Create token and copy it (it starts with
hf_). - In ZumiForge, open ☰ → API keys, paste it into Hugging Face and press Save. It's stored in your Mac's Keychain.
Some models are gated: their makers ask you to accept a licence first. ☰ → Local models marks these "needs access" with a link. Open the link while signed in to Hugging Face, press Agree and access repository, then press Check again in ZumiForge. Approval is usually instant.
5. Your first image
- Open ☰ → Local models. It checks this Mac and shows what's ready.
- Next to Z-Image Turbo, press Download & test. It downloads about 31 GB, then makes a test picture of an apple. Progress shows on the card in the gallery. The download happens once.
- Type a prompt in the big box, such as a lighthouse on a cliff at sunset, oil painting, make sure Z-Image Turbo is ticked and press Queue.
Start with Detail: Preview or Draft under Output while you experiment, then use Standard or High, or Upscale, for keepers.
6. Cloud models (optional)
Cloud models run on someone else's computers, so they need no downloads and work on any Mac, but each image or video costs money (usually a few cents per image). You need an account and an API key from the service:
| Service | What it gives you | Get a key |
|---|---|---|
| fal.ai | A large catalogue of image, video and upscaling models. Shows prices before you run. | fal.ai/dashboard/keys |
| Replicate | A very wide catalogue, including community models. | replicate.com/account/api-tokens |
| Runware | Many of the same models as fal, with public prices. Cheapest for small open models (FLUX.1 Schnell, Z-Image Turbo); about the same as fal for most others. | runware.ai/dashboard → API Keys |
| Google AI | Google's Nano Banana image models. | aistudio.google.com/apikey |
| OpenAI | GPT Image 2.6 (Flare and Sunburst). OpenAI may ask you to verify your organisation before image models work. OpenAI closed its Sora video API in September 2026, so there are no OpenAI video models. | platform.openai.com/api-keys |
| xAI | Grok Imagine: images, and video with sound (1–15 seconds). | console.x.ai |
Paste keys in ☰ → API keys. You can add more cloud models with ➕ Add model at the bottom of the fal, Replicate or Runware column.
Running from the source folder (developers)
If you're working on ZumiForge itself, you can run its server straight from the project folder instead of the app. That needs Node.js 20 or newer (brew install node). From the folder:
./setup.sh # checks the tools and offers to install what's missing
./startServer.sh # starts the server; leave this window open
Then open http://localhost:50109. Everything (images in outputs/, history in jobs.json, lists and templates) is kept in the folder. Press Ctrl C to stop it. Optionally, npm install -g portless gives it the address https://mflux.localhost. Quit the ZumiForge app first: both use port 50109.
Using ZumiForge
Choosing models
The form has three steps under an Images / Video switch. Pick what to make first: the model list and the output options follow it, each mode remembers its own model picks, and the server refuses a job sent to the wrong kind of model.
- Describe it: the prompt, a style preset, Enhance (it suggests a richer prompt and you choose whether to use it), Templates, Things to avoid (a negative prompt, used by some models) and reference images. In Video mode the reference becomes the first frame.
- Choose models: your picks, and the full list on demand.
- Output: the shape (or a custom ratio such as 5:4), the detail level with its pixel size (Preview, Draft, Standard, High), or for video the length, quality and sound; plus how many per model. More settings has steps, guidance and LoRA.
The bar at the bottom shows what you'll get and a rough cost from fal's and Runware's list prices. Queue stays disabled until you've picked a model.
The picker shows just the models you've ticked, as chips (✕ unticks one). Press ▾ Show all models to open the full list, and type in its filter box to narrow it, for example kling, video or runware flux. It starts closed each time, unless no model is ticked.
The full list has five columns: On this device (free, private), Direct (Google, OpenAI and xAI, each with your own key), Via fal.ai, Via Replicate and Via Runware. The same model is often in several columns, so you can compare prices. Tick as many as you like: each prompt is sent to every ticked model, which makes comparing models easy. Ticked rows are highlighted.
- 🖼 means the model takes reference images. 🎬 means it makes video.
- Prices next to fal models are fal's list prices (per image, per megapixel, or per second of video).
- The Queue button shows what you're about to make, for example Queue 12 images + 6 videos (3 prompts × 3 models × 2).
- 🧩 Manage renames or hides models and shows details for each one: what it does, what it accepts and what it costs.
Several prompts at once
Put a line containing only --- between prompts to queue them all in one go. The box shows a badge such as 3 prompts. This is handy for pasting a batch written elsewhere (for example by an AI assistant):
Filename: opening
A wide shot of a city at dawn, mist between the towers
---
Filename: market
A busy street market at noon, colourful awnings
---
A quiet harbour at night, boats reflected in still water
Filename: nameon its own line sets the start of the saved file name.Image 1:-style labels at the start of a prompt are removed automatically.- Book mode: a prompt written as
Text: …followed byIMAGE: …uses only the IMAGE part as the prompt, and shows the Text part on the card when Preview: Book Mode is selected. - Qty makes several images of each prompt with different seeds. AI Variations rewrites each copy differently with Gemini (your Google AI key), or Chrome's built-in AI when no key is set.
Prompt lists
For prompts you want to keep, reuse and manage one by one, use prompt lists.
- ➕ Add to Prompt List (bottom-right of the prompt box) saves what's in the box to your current list instead of queuing it. Several prompts separated by
---become separate items. - 📋 Manage Prompts opens your lists. You can:
- create, rename and delete lists;
- search, and tick prompts to queue, copy or remove them together;
- edit a prompt (double-click it, or ✎), duplicate it, move it up, or queue just that one with ▶;
- ⬇ Import a long script by pasting it, or from a
.txt/.mdfile, into the current list or a new one; - Copy as text to get the whole list back as
----separated text.
- Each prompt shows when it was last queued. Lists are saved on the server in
prompt_lists.json.
Templates
Templates keep characters, places and styles consistent across many images. You describe something once, give it a short label, then use a tag in any prompt.
| Tag | What happens |
|---|---|
{{character:marcus}} | Becomes "Character A" in the prompt, and "Character A: marcus's description" is added at the end. The next character tag becomes "Character B", and so on. This helps models keep several people apart. |
{{location:city}} | Replaced by the location's description. |
{{prop:flag}} | Replaced by the prop's description. |
{{lighting:golden-hour}} | Replaced by the lighting description. Also good for reusable style blocks. |
{{outfit:uniform}} | Replaced by the outfit's description. |
Instead of a label you can write:
random, e.g.{{location:random}}: a random location for each image.n, e.g.{{character:n}}: with Qty above 1, the first image uses the 1st character, the second the 2nd, and so on (it wraps around).- A number, e.g.
{{prop:2}}: the 2nd prop in the list.
Labels aren't case-sensitive. If a label doesn't exist, the tag is left in the prompt unchanged, so check the prompt on the card if a result looks off.
Example
With a character marcus ("middle-aged man, greying temples, navy overcoat") and a location city ("rain-soaked streets, neon signs"), the prompt
{{character:marcus}} waiting at a bus stop in {{location:city}}, {{lighting:golden-hour}}
is sent to the model as
Scene: Character A waiting at a bus stop in rain-soaked streets, neon signs, warm golden hour sunlight, long shadows
Character A: middle-aged man, greying temples, navy overcoat
Editing templates
Open 📝 Templates. Each category has a tab with one row per template: a label and a description. Press + Add for a new one, click a tag such as {{character:marcus}} to copy it, and search across all categories. For bulk changes, Edit as text shows the category as text (the label on the first line, then the description, with --- between items), and ⬇ Import accepts a whole file using CHARACTERS, LOCATIONS, PROPS, LIGHTING and OUTFITS headings, or JSON.
Reference images
Reference images let a model work from a picture: to keep a face or product consistent, restyle a photo, or start a video from a still.
- Add one with + Add image under the models, by dropping or pasting an image anywhere in the form, or with 🖼 Ref on any finished card. Up to 8 at a time.
- Only models marked 🖼 use them. The others fade out, and you're asked before queuing if any ticked model would ignore them.
- Locally, Flux2 Klein, FLUX.3 Klein and Qwen-Image 2.1 Turbo use their edit modes. Many fal models switch automatically to their "edit" version.
- For video models, the first reference image becomes the video's first frame.
Video
Tick a 🎬 model and a Video row appears: Length (seconds), Quality (480p, 720p or 1080p) and Sound. The shape follows the Res setting. Each model gets the nearest settings it supports; for example, Luma only makes 5- or 10-second clips.
- LTX-2.5 makes video with sound on your Mac, for free. A 3-second 768×512 clip takes under a minute on a recent Mac. It needs the separate
ltx-2-mlxinstall (see Local models). - Cloud video takes a few minutes and costs more than images, usually charged per second.
Upscale & edit
- Upscale on a finished image makes a bigger, sharper copy. Pick the target size and an upscaler: SeedVR2 (on this device, free), or cloud upscalers such as Topaz or Crystal.
- ✏️ Edit changes an image with a prompt such as "make it snowy", using FLUX Kontext on your Mac. If you don't have access to Kontext, it falls back to a simpler local method.
- 🖼 Ref uses the image as a reference for your next prompt.
The queue
Jobs run in parallel queues, one for each place they run: This Mac runs one job at a time, while fal, Replicate, Runware, Google, OpenAI and xAI each run up to 3 at once. The bar above the gallery shows what's running and waiting.
- ✕ Remove on a waiting card takes it out of the queue. ■ Stop on a running card stops it; cloud jobs are cancelled with the provider.
- Clear queue removes every job that hasn't started yet.
- 🗑 on a finished card removes it from the gallery. The file stays in the
outputsfolder.
Finding your images
The gallery shows your newest 50 results, with pages for older ones. The search box finds words in prompts, file names and model names. The filters narrow it to images or videos, one model, or finished / running / failed jobs. Everything is saved in the outputs folder inside ZumiForge.
Local models
☰ → Local models checks your setup and shows each model's status, with a one-click download and test. All of them are free to run; some licences don't allow commercial use.
| Model | Download | Good for | Licence |
|---|---|---|---|
| Z-Image Turbo | ~31 GB | Fast, all-round default | Apache 2.0 |
| Flux2 Klein 4B | ~15 GB | Small and quick; edits with reference images | Apache 2.0 |
| Flux2 Klein 9B | ~32 GB | More detail; reference images | Non-commercial (gated) |
| FLUX.3 Klein | ~25 GB | Newest Black Forest Labs model; reference images | Non-commercial (gated) |
| Qwen-Image 2.1 Turbo | ~30 GB | Text in images: signs, posters; reference images | Non-commercial |
| Krea 2 | ~33 GB | Photorealistic, aesthetic images | Krea licence (gated) |
| Iris 3B | ~6 GB | Small and fast; good on 16 GB Macs | Apache 2.0 |
| Ideogram 4 | ~26 GB | Typography and design | Ideogram licence (gated) |
| LTX-2.5 | ~70 GB | Video with sound | LTX-2 Community (gated) |
| SeedVR2 | ~7 GB | Upscaling | Apache 2.0 |
Installing LTX-2.5 (local video)
LTX runs through a separate tool, ltx-2-mlx. Install it next to the ZumiForge folder:
cd ~/code
git clone https://github.com/dgrauet/ltx-2-mlx.git
cd ltx-2-mlx
uv sync --all-extras
Then accept the licence at huggingface.co/dgrauet/ltx-2.5-mlx-q8 and restart ZumiForge. ZumiForge looks for ltx-2-mlx in the same folder as the ZumiForge folder (so with ZumiForge in ~/code/zumiforge, it looks in ~/code/ltx-2-mlx). If you put it somewhere else, start the server with LTX_BIN=/path/to/ltx-2-mlx/.venv/bin/ltx-2-mlx. The first video downloads about 70 GB.
Disk space
Models are stored in ~/.cache/huggingface/hub, one models--… folder each. Delete a folder to free its space; it downloads again if you use that model later.
Costs
- Local models are free; you only pay for electricity.
- fal.ai shows list prices next to each model, and each finished card shows what that job cost (worked out from the list price and the size of the result).
- Runware publishes every model's price list, shown next to each model without a key. Each finished card shows exactly what Runware charged. Models priced in tokens (GPT Image, Nano Banana) show their price only after the run.
- Balances: the fal and Runware columns show what's left on your account, refreshed after each job (click the amount to refresh). fal only shows it to keys with billing access: its usual API key preset can't, so add a second fal key with the BILLING or READONLY preset under ☰ → API keys → fal.ai billing key. Replicate doesn't report balances; check replicate.com.
- Replicate doesn't publish prices through its API. Cards show the GPU seconds Replicate billed; prices are on each model's page.
- Google bills per image; see Google AI Studio.
- OpenAI and xAI bill per image or per second of video on your own account; see their pricing pages.
Ticking several cloud models and using several prompts multiplies quickly. Check the totals on the Queue button before pressing it, and set spending limits in each provider's dashboard.
Privacy
ZumiForge runs on your Mac. It has no accounts, no analytics and no tracking, and the ZumiForge developers can't see anything you do.
What stays on your Mac
- Local models: prompts, reference images and results never leave your Mac. Only the one-time model downloads talk to Hugging Face.
- Your files: images and videos are in the folder you chose (menu bar icon → Show images in Finder). Reference images you add, the job history with every prompt, your prompt lists, templates and a few settings files are in
~/Library/Application Support/ZumiForge. Anyone who can open your user account can read them. (Running from the source folder, all of these are in that folder.) - API keys are stored in the macOS Keychain (encrypted, unlocked when you log in), or come from environment variables you set. They are never sent to your browser (it only sees the last 4 characters), never written into jobs and never logged.
What is sent elsewhere
- Cloud models (fal.ai, Replicate, Runware, Google, OpenAI, xAI) receive your prompt, any reference images and the settings for that job, under each company's own privacy policy and terms. Read them if your prompts or images are sensitive.
- Hugging Face sees which models you download, under your account.
- ZumiForge looks up model lists, input details and prices from fal.ai, Replicate, Runware and PyPI (to check for mflux updates). These lookups contain no prompts or images.
- AI Variations and ✨ Enhance use the AI built into Chrome, which runs on your Mac.
Who can use the server
The server only accepts connections from this Mac, not from other devices on your network. It refuses requests from other websites, so a web page you visit can't use your keys or read your images. To deliberately share it on your network, start it with HOST=0.0.0.0. Anyone on that network could then use it, and your paid keys.
Deleting your data
Delete images and videos from your image folder, and jobs with 🗑. To clear all history, quit ZumiForge and delete ~/Library/Application Support/ZumiForge. Remove keys in ☰ → API keys, or in the Keychain Access app (search "ZumiForge").
FAQ & troubleshooting
The page won't load / "This site can't be reached"
ZumiForge isn't running. Open ZumiForge from Applications; its menu bar icon says whether the server is running, and Open the log shows why not. Then reload the page. (Running from the source folder: run ./startServer.sh in that folder.)
A local model says "Hugging Face access needed" or fails with 403
The model is gated. Open the link on the card (or in ☰ → Local models), sign in to Hugging Face, accept the licence, then queue the job again. Also check your token in ☰ → API keys: it needs "Read access to contents of all public gated repos you can access".
The first image takes ages
The first time you use a local model it downloads 6–70 GB; the card shows download progress. After that, it starts in seconds.
A new model I just added isn't used / the job runs the wrong model
Choose Restart the server from the ZumiForge menu bar icon, then reload the page. (Running from the source folder: stop the server with Ctrl C and start it again with ./startServer.sh.)
"command not found: mflux-…" or local models fail immediately
mflux isn't installed, or Terminal can't find it. Run uv tool install --upgrade mflux, then uv tool update-shell, open a new Terminal window and restart the server. ☰ → Local models shows whether the server can find mflux.
Ideogram 4 shows "blocked by safety filter" for a harmless prompt
Ideogram 4's built-in filter sometimes blocks innocent prompts depending on the random seed. Queue it again for a new seed, or use another model.
Images look garbled at small sizes
Some models (Iris, Ideogram) need at least 1024 px; ZumiForge scales them up automatically. For others, choose a higher Detail level under Output.
My Mac runs out of memory or gets very slow
Large models at large sizes need a lot of memory. Use a smaller size, a smaller model (Iris 3B, Flux2 Klein 4B), or close other big apps. Only one local job runs at a time.
A cloud job fails with 401 or 403
The API key is wrong, expired or out of credit. Check it in ☰ → API keys and in the provider's dashboard.
Videos play without sound
Check the Sound box in the Video row before queuing; some models make silent video anyway. Use the volume control on the video.
Where are my files?
In the outputs folder inside ZumiForge. File names start with the Filename: you gave, or the model's name when several models were ticked.
How do I update ZumiForge and mflux?
Run the install command again (curl -fsSL https://zumilabs.com/tools/zumiforge/install.sh | sh); your images, history, lists, templates and keys stay. Update mflux with uv tool upgrade mflux, then choose Restart the server from the menu bar icon.
Can I use it from my phone or another computer?
No, for safety: the server only answers this Mac. (Running from the source folder, HOST=0.0.0.0 ./startServer.sh opens it to your network, where anyone on that network could use it and your paid keys.)
Settings reference
| Setting | What it does |
|---|---|
PORT | Server port (default 50109; portless sets this itself). |
HOST | Address to listen on. Default: this Mac only. 0.0.0.0 shares it on your network. |
GOOGLE_API_KEY, OPENAI_API_KEY, XAI_API_KEY, FAL_KEY, REPLICATE_API_TOKEN, RUNWARE_API_KEY, FAL_BILLING_KEY, HUGGING_FACE_HUB_TOKEN | Keys from the environment. They override the Keychain and are never stored. |
KEY_STORE=file | Store keys in keys.json instead of the Keychain (not recommended). |
FAL_CONCURRENCY, REPLICATE_CONCURRENCY, RUNWARE_CONCURRENCY, GOOGLE_CONCURRENCY, OPENAI_CONCURRENCY, XAI_CONCURRENCY | How many cloud jobs run at once per service (default 3). |
LTX_BIN, LTX_MODEL | Where ltx-2-mlx is installed, and which LTX weights to use (default dgrauet/ltx-2.5-mlx-q8). |
These apply when you run the server from the source folder, for example FAL_CONCURRENCY=5 ./startServer.sh. The Mac app sets the port and folders itself.