Image Forge

Stack

React 18 + Vite + TypeScript, packaged with Electron for Windows. No backend, no state library, ~20k lines. Everything durable is a CSV or a localStorage key. 672 tests (vitest) run in CI on every push with typecheck and build.

npm install
npm run dev              # http://localhost:3000 (browser mode)
npm test && npm run typecheck && npm run build
node scripts/build-exe.js   # NSIS installer + portable exe

The rule that shapes the layout

src/lib/engines.mjs is the single source of truth for routing, prices, network calls and file naming, and it is DOM-free — no React, window or document. That is what lets the app and the MCP server (scripts/mcp-server.js) run the same code. Browser-only concerns live in src/lib/providers.ts.

How a picture is made

1. resolveRoute(row, settings) → { engine, apiModel, def }. The row’s model column wins; blank falls back to the engine picked in the toolbar (default for a fresh install: ovh).
2. A healthy key is chosen; free Gemini keys before paid.
3. generateBytes() makes the request, then overrides the claimed MIME type with the one the bytes declare (mimeFromBytes); the filename’s extension is corrected to match (nameForMime), never the stem.
4. On 429 the key is benched and the same row retries with the next key.
5. Paid rows never start without checkPaidRun() → a confirmation dialog.

withStyleBlock() places a style’s words per engine: last normally, first on SDXL/OVHcloud, whose CLIP text encoder reads ~77 tokens and drops the rest silently.

Engines

id	engine	cost	notes
ovh-sdxl	OVHcloud SDXL	free, no key	2/min, paced in-process; 1024² only; no seed
cloudflare-flux	Workers AI	free	no CORS → proxied (/cf-api); rejects seed
flux / turbo	Pollinations	free	needs a token
(local)	LocalAI & co.	free	ref_images supported
nano-banana*	Google	paid	JPEG only; 429 may mean “no prepay balance”
gpt-image-1, dall-e-3	OpenAI-compatible	paid

The link to BYOK Vid Creator

Two apps, not a merge. The desktop main process (electron/link.mjs) owns a folder under userData:

link/presence.json         { app, version, port, inbox, outbox }
link/inbox/<id>.json       request from the other app
link/processing/<id>.json  claimed, being made
link/outbox/<id>/*         pictures, then done.json

Requests are validated in the main process only (id shape, ≤ 60 rows, plain filenames, size limit); invalid ones are moved to inbox/rejected/ with a .why.txt. The page polls /link/requests every 5 s behind an X-Forge-Link: 1 header — a custom header forces a CORS preflight the server never grants, so no other web page can drive it. Rows carry request_id; when all end, the page PUTs each picture and POSTs done. Keys never cross over. The vid creator side is tools/lib/forgeLink.mjs + npm run ask-forge.

Desktop specifics

• Window or browser (electron/appctl.mjs, src/lib/desktop.ts): the same server either way. Switching posts the page’s whole localStorage to /app/mode; the other side takes it once from /app/handover before React mounts. The window and a browser are separate storage even on one origin, so without this the switch would look like data loss.

• Update now: /app/update accepts only github.com/Stravelakis/image-forge/releases/download/…Setup….exe, downloads it and runs it with /S --updated --force-run. /app/* needs the X-Forge-App: 1 header, like the link.

• ESM main process; never require() (it crashed the proxies in 1.0.0).

• Fixed ports 47821–47825, never listen(0): storage is per origin.

• Data in %APPDATA%\image-forge (package name; no productName).

• Loads report stored | empty | rescued; a rescued load keeps a .rescue copy and holds autosave instead of writing defaults over real data.

Releasing

Branch → bump five version fields (tests/version.test.ts enforces) → CHANGELOG → tests/typecheck/build → build exe and install it → PR → merge → tag vX.Y.Z. release.yml publishes the exes; docs.yml rebuilds this site. Full map: HANDOFF.md.

What Image Forge is

A Windows app that makes pictures in bulk. You say what you need and how many, and it makes them, names them properly, and puts them in a folder.

It uses AI image services — some free, some paid — with your own keys. There is no account and no Image Forge server. Your keys stay on your computer and are sent only to the service you chose.

Install it

1. Go to the downloads page and get Image.Forge.Setup.x.y.z.exe.
2. Run it. Windows shows a blue “Windows protected your PC” box, because the app is not signed with a paid certificate yet. Click More info, then Run anyway. You only do this once.
3. It installs like any program: Start menu, desktop shortcut, and an entry in Settings → Apps to uninstall it from.

Your first pictures

The app opens on the Start screen.

1. Type what you need, for example “12 potion bottle icons, cute, glowing”.
2. Check How many (it reads a number at the start of your sentence).
3. Pick a Look and a Shape if you like.
4. Press Make.

With nothing set up it uses OVHcloud, which is free and needs no key. It makes two pictures a minute and they are always square. The pictures appear under the box as they finish; click one to see it full size.

Faster or better pictures

Open Settings → Image engines:

• Cloudflare — free, about 690 pictures a day, no card. Needs a free account id and token.
• Your own machine — free and unlimited if you run an image model locally.
• Google (Nano Banana) — costs money per picture, but can write readable words in a picture and follows complicated instructions best.

A paid engine never runs without asking. You see how many pictures, the price each, the total and which credit pays — with a button to switch to a free engine instead.

More varied sets

The Start screen varies a set by framing. For genuinely different pictures in one set, add a text engine: Settings → Text engines → Your accounts. One free Mistral key covers writing, code and vision.

Keeping your settings safe

The top of Settings says when your settings were last saved and checked, and how many keys are stored (it never shows them). Press Back up to a file once your keys are in, and keep the file private — it holds the keys.

Working with BYOK Vid Creator

If both apps are installed, the video app can ask Image Forge for pictures, such as mouth-shape sheets for its characters. Free requests run by themselves; anything that costs money still asks you first.

Be aware: free engines often draw one picture when asked for a grid of nine, so check sheets by eye. A Google model follows grid instructions far better.

When something is wrong

• “Windows protected your PC” — expected; see Install.
• “Every key is resting” — the engine hit its limit; it retries by itself.
• Google says “prepayment credits are depleted” — the account has no picture balance. The key check in Settings explains which fix you need.
• Settings say “NOT saved” — press Back up to a file before closing.

The full troubleshooting page, with the cause of each problem, is in the repository.

Window or browser, and updates

Image Forge can open in its own window or in the browser you already use — Settings → Advanced → Where Image Forge opens. Your settings and keys come along. When a new version is out, Update now installs it for you and reopens the app; nothing of yours is touched.

What is it?

Image Forge is a picture-making machine on your computer.

You tell it what you want — “twelve cute potion bottles” — and it asks a robot artist on the internet to draw them. Then it puts all the drawings in a folder with sensible names.

Does it cost money?

Not if you don’t want it to. Some robot artists are free. One of them doesn’t even need you to sign up.

Some robot artists cost a little money for each picture. Image Forge will always ask you first before using one of those, and tell you how much.

Is it safe?

To use some robot artists you need a secret password called a key. Image Forge keeps your keys on your own computer. It never sends them anywhere except to the robot artist you picked.

How do I use it?

1. Install it, like any other program.
2. Windows might show a blue warning. Click More info, then Run anyway.
3. Type what you want in the big box.
4. Say how many.
5. Press the big button.
6. Wait. The pictures pop up one by one.

It has a friend

There is another app called BYOK Vid Creator that makes videos with talking cartoon characters. If you have both, the video app can ask Image Forge to draw pictures for it. They help each other.

Something went wrong?

Usually it just needs a minute — free robot artists are a bit slow. If a picture looks wrong, you can ask for it again. And if you are stuck, the people who made it would like to hear about it on GitHub.

New toys

You can open the picture factory in its own window or in your web browser — you choose. And when there is a newer factory, one button swaps it in for you. Your pictures stay right where they are.