ima2-gen: A Local-First Runtime for Reproducible Image and Video Generation

The Problem ima2-gen Targets: Provider Sprawl in Visual Workflows

Anyone generating images or video across several providers ends up with the same mess. Credentials live in different places, prompts get retyped, and there is no record of which model produced which file. ima2-gen addresses that by acting as a local runtime with a provider registry in front of it. The README describes it as a local-first visual generation runtime and studio for people and coding agents, with reproducible image and video workflows across multiple providers. The registry covers OpenAI OAuth and API, Grok OAuth and API, Antigravity CLI, Gemini API, AtlasCloud, MiniMax, NovelAI, and registered ComfyUI workflows. Runway and Higgsfield sit outside that registry as separate MCP-backed integrations, which is a meaningful distinction: they are not first-class lanes. The audience is twofold. Individuals who want one workspace and one history instead of five browser tabs. And coding agents, which the project treats as a first-class consumer through its CLI surface and MCP topic tag. If you only ever use one provider and never script anything, the registry adds a layer you do not need.

Lanes, Defaults, and the Fail-Closed Rule

The central abstraction is the lane. Each provider integration is addressed as a lane and model pair, written as lane/model, for example oauth/gpt-5.6-luna for images and grok/grok-imagine-video-1.5 for video. The README is explicit about the failure mode this prevents: ima2 gen and generate-mode ima2 video fail closed with NO_DEFAULT_MODEL until a CLI target is configured, unless the call passes --model <lane>/<model> or an explicit --provider <lane>. The stated reason is that an upgrade should not silently switch providers or billing lanes. That is a deliberate trade-off. You trade convenience for predictability, and the first-run experience is a hard error rather than a guess. The same logic shows up in port binding. If 3333 is occupied, the server binds the next available port and writes the actual URL to ~/.ima2/server.json, so the documented port is a starting point rather than a guarantee. The README tells you to use ima2 open or the URL printed in the terminal instead of assuming the port. Both behaviours point the same direction: the tool prefers an explicit, inspectable state over a convenient assumption.

Getting It Running: npm, Docker, and the Install Scripts

The shortest path is three commands. npm install -g ima2-gen, then ima2 setup, then ima2 serve, after which the studio is reachable at http://localhost:3333. The runtime contract table in the README lists Node engine >=22, npm toolchain npm@11.18.0, release Node 24.17.0, CLI entry bin/ima2.js, OpenAI SDK ^7.4.0, and Express ^5.1.0. The installer derives its Node.js floor from package metadata and runs an offline installation check before launching the server. Docker is supported with a documented command: docker build -t ima2-gen . followed by docker run -d -p 3333:3333 -e IMA2_LAN_TOKEN=change-me -v ima2-data:/data ima2-gen. Note that this example sets a LAN token, which implies the container can be exposed beyond localhost; docs/DOCKER.md is cited for compose usage, required environment, and limitations. There are also platform install scripts for macOS, Windows PowerShell, and Linux or WSL, each of which checks the package-derived Node.js floor, installs Node LTS if needed, installs once, and runs the offline check before launching the server. The README states plainly that these scripts do not stop unrelated processes or clear global locks. Setup offers four authentication choices: GPT OAuth (free, images only), Grok OAuth (images plus video), both, or web setup. Video generation requires Grok OAuth, and ima2 grok login can be run separately to add it later, defaulting to the manual-paste flow.

CLI Defaults, Model Discovery, and the Vectorize Command

The CLI is where the reproducibility claim becomes concrete. ima2 models inspects the live lane catalog, so the set of usable lanes reflects what your accounts can actually reach rather than a static list. You then pin defaults once with ima2 defaults set image oauth/gpt-5.6-luna and ima2 defaults set video grok/grok-imagine-video-1.5. Generation follows: ima2 gen "a clean product photo of a red guitar pedal", or ima2 video "a cat playing piano" --duration 5 --resolution 720p, or ima2 video "animate this scene" --ref photo.png --duration 10. There is also ima2 vectorize, which traces flat raster art into SVG paths, available from the CLI, from AssetGen/Assets, or from Canvas Export. The README draws a careful line here: Canvas labels its older self-contained wrapper as SVG (embedded raster) so it cannot be mistaken for a trace. That naming discipline matters more than it sounds. A wrapped raster inside an SVG container behaves very differently from traced paths when you scale or edit it, and conflating the two is a common source of downstream surprises. The existence of a separate command for vectorization, rather than a checkbox on an export dialog, suggests the project expects it to be scripted.

Where the Studio Adds Structure: Node Branches, Batches, and Storyboard Mode

Beyond single generations, the README lists several workspace modes. Classic mode handles generate, edit, reuse the current image, paste references, and continue from history. Node mode branches a good image into multiple directions without losing the original, which is the standard node-editor pattern applied to image iteration. Multimode batches launch several Classic outputs from one prompt with slot-by-slot progress, so you can continue from the best result rather than re-rolling blind. Storyboard mode is the more unusual one: toggling it in the composer maintains character and scene continuity across sequential frames, and the README says it works with both image and video generation, with image keyframes composed for video production and video clips inheriting character and environment lock rules. Whether that continuity mechanism produces consistent characters in practice is not something the supplied material demonstrates, and I would treat the lock rules as a prompt-level convention until proven otherwise. Video generation streams status over SSE through planning, submitted, progress percentage, and done, and frame copy buttons for First, Mid, and Last let you extract keyframes from a generated clip.

Canvas Mode and the Transparency Claim Worth Checking

Canvas Mode provides zoom, pan, annotate with hover highlighting, erase, background cleanup, transparent previews, and export of either alpha or matte-backed versions. The notable feature is the one-click GPT transparency button, which sends the current image through the i2i edit lane and, in the README's words, reports honestly whether the result carries real pixel alpha, verified on the server, never trusted from provider metadata. That is a specific and defensible design decision. Providers frequently return files that claim transparency in metadata while shipping an opaque background, and checking the pixels server-side is the only reliable way to know. The README also states the feature is server-verified real alpha, which implies the check happens on the runtime rather than in the browser. If transparency is part of your pipeline, this is the behaviour to test first, because it determines whether you can skip a manual masking step. If transparency is irrelevant to your work, Canvas Mode is a convenience layer over the same generation lanes, and the rest of the studio does not depend on it.

The Provider Dependency and Other Limits

The clearest limitation is stated in the README itself: video generation requires Grok OAuth. The registry lists many image-capable providers, but video routes through Grok's models, so an account or region that cannot complete Grok OAuth removes video entirely. Runway and Higgsfield are mentioned as separate MCP-backed integrations rather than registry lanes, which means they do not behave like the other providers and should not be assumed to share the same defaults, history, or Canvas behaviour. The Node floor of >=22 is another real constraint; the install scripts will install Node LTS for you, but a locked-down environment that pins an older runtime will not run this without intervention. The README also notes that the installer does not perform broad process cleanup, so a failed install leaves you to inspect npm permissions or stop the specific ima2 process yourself. There is no statement in the supplied material about offline generation, local model inference, or what happens to your prompts once they reach a provider. Local-first here means the runtime and studio are local, not that generation is. That distinction is worth holding onto, because the phrase can be read more broadly than the architecture supports.

How It Compares to ComfyUI

ComfyUI appears in this project's own registry as registered ComfyUI workflows, so it is partly a peer and partly an integration target. The difference in approach is where the graph lives. ComfyUI is a node graph that you build and that executes locally, with model weights on your disk and a graph you own end to end. ima2-gen is a provider router with a node mode attached: the branching exists for iterating on outputs, not for defining the inference pipeline, and the actual generation happens on remote APIs. If you want to control sampling, schedulers, and model files, ComfyUI is the closer fit, and ima2-gen's registration of ComfyUI workflows suggests the project anticipates that overlap. If you want one interface across several commercial providers, with history and defaults you can script, ima2-gen is aimed at that. The two are not mutually exclusive, but choosing between them is really a question of whether you want to own the graph or own the routing.

Editorial conclusion

Adopt ima2-gen if you need a local server that keeps provider credentials and generation history on your own machine, and you are comfortable with Node 22 or newer. Do not adopt it if you need video generation without a Grok OAuth account, or if you want a hosted service with no local process to manage. Before committing, run ima2 models to confirm which lanes your accounts can actually reach, then set defaults explicitly with ima2 defaults set image <lane>/<model> and ima2 defaults set video <lane>/<model>, because every generate call fails closed with NO_DEFAULT_MODEL until those targets exist.

Official sources

1. License: MIT
2. lidge-jun/ima2-gen on GitHub
3. Project website
4. README
5. Releases