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
  1. 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.
  2. 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.
  3. 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.

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:

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:

  1. Homebrew installs the other tools. Skip this if you already have it (brew --version prints a version).
    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
    When it finishes, it prints two or three "Next steps" commands that add Homebrew to your PATH. Run them.
  2. uv installs Python tools, and ffmpeg handles video files:
    brew install uv ffmpeg
  3. mflux runs the image models:
    uv tool install --upgrade mflux
  4. 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.

  1. Create an account at huggingface.co/join.
  2. Open Settings → Access Tokens → Create new token.
  3. 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.
  4. Press Create token and copy it (it starts with hf_).
  5. 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

  1. Open ☰ → Local models. It checks this Mac and shows what's ready.
  2. 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.
  3. 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:

ServiceWhat it gives youGet a key
fal.aiA large catalogue of image, video and upscaling models. Shows prices before you run.fal.ai/dashboard/keys
ReplicateA very wide catalogue, including community models.replicate.com/account/api-tokens
RunwareMany 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 AIGoogle's Nano Banana image models.aistudio.google.com/apikey
OpenAIGPT 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
xAIGrok 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.

  1. 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.
  2. Choose models: your picks, and the full list on demand.
  3. 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.

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

Prompt lists

For prompts you want to keep, reuse and manage one by one, use prompt lists.

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.

TagWhat 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:

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.

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.

Upscale & edit

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.

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.

ModelDownloadGood forLicence
Z-Image Turbo~31 GBFast, all-round defaultApache 2.0
Flux2 Klein 4B~15 GBSmall and quick; edits with reference imagesApache 2.0
Flux2 Klein 9B~32 GBMore detail; reference imagesNon-commercial (gated)
FLUX.3 Klein~25 GBNewest Black Forest Labs model; reference imagesNon-commercial (gated)
Qwen-Image 2.1 Turbo~30 GBText in images: signs, posters; reference imagesNon-commercial
Krea 2~33 GBPhotorealistic, aesthetic imagesKrea licence (gated)
Iris 3B~6 GBSmall and fast; good on 16 GB MacsApache 2.0
Ideogram 4~26 GBTypography and designIdeogram licence (gated)
LTX-2.5~70 GBVideo with soundLTX-2 Community (gated)
SeedVR2~7 GBUpscalingApache 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

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

What is sent elsewhere

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

SettingWhat it does
PORTServer port (default 50109; portless sets this itself).
HOSTAddress 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_TOKENKeys from the environment. They override the Keychain and are never stored.
KEY_STORE=fileStore keys in keys.json instead of the Keychain (not recommended).
FAL_CONCURRENCY, REPLICATE_CONCURRENCY, RUNWARE_CONCURRENCY, GOOGLE_CONCURRENCY, OPENAI_CONCURRENCY, XAI_CONCURRENCYHow many cloud jobs run at once per service (default 3).
LTX_BIN, LTX_MODELWhere 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.