docker build -t ima2-gen .
docker run -d -p 3333:3333 -e IMA2_LAN_TOKEN=change-me -v ima2-data:/data ima2-gen

See docs/DOCKER.md for compose usage, required environment, and limitations.

ima2 setup offers four authentication choices:

1. GPT OAuth — log in with a ChatGPT account (images)
2. Grok OAuth — log in with an xAI/Grok account (images and video)
3. Both — GPT OAuth and Grok OAuth
4. Web setup — configure everything in the web UI

Video generation needs Grok OAuth (option 2 or 3). If you already use GPT OAuth, run ima2 grok login to add video; it defaults to the manual-paste flow.

To update, stop the server with Ctrl+C (or ima2 stop from another terminal), then run:

npm install -g ima2-gen@latest

Ctrl+C shuts down cleanly: it closes the database, stops child processes and releases file locks. If an install fails, check the reported npm permissions or stop the specific ima2 process yourself; the installer does not perform broad process cleanup.

Using npx instead? See docs/NPX_QUICKSTART.md for the npx ima2-gen serve workflow.

• provider: "oauth" signs in with your ChatGPT session and calls ChatGPT's Codex backend from the ima2 server process, with no separate proxy. A GPT-6 model plans the prompt and gpt-image-2 renders it; Direct mode skips the planner. Transparent backgrounds and image edits run on the same lane.
• provider: "api" calls the OpenAI Responses API with the hosted image_generation tool.
• provider: "grok" calls https://api.x.ai directly with the xAI OAuth session stored in ~/.progrok/auth.json, running mandatory xAI Web Search plus a planner pass (default: grok-4.3, configurable in settings or via --planner-model) before the xAI Images API call. grok-4.5 and grok-4.6 are also selectable. Log in once with ima2 grok login or the Settings Switch Account button; the session refreshes itself two minutes before expiry.
• provider: "grok-api" calls the xAI Images API directly with XAI_API_KEY (no OAuth session involved).
• provider: "nai" calls the NovelAI image API with a persistent API token (saved in Settings > API Keys or NOVELAI_API_KEY; no fixed token prefix is required). Four models: nai-diffusion-5-full, nai-diffusion-5-curated, nai-diffusion-4-5-full, nai-diffusion-4-5-curated. Responses arrive as a ZIP archive that ima2 decodes to PNG. Text-to-image only — reference images, edits, and masks are refused rather than silently dropped. Browser and CLI surfaces expose negative prompt, sampler/schedule, steps/guidance/CFG rescale, seed, presets, Auto SMEA, Decrisper, Variety+, and V5 alpha.
• provider: "agy" spawns the Antigravity CLI (agy -p) to generate images via Google Gemini's default_api:generate_image tool (models: nano-banana-2 and nano-banana-pro). Output is fixed at 1024×1024 JPEG, max 3 reference images. No web search, quality, or size controls.
• provider: "gemini-api" calls the Google Generative Language API directly. Supports two models: nano-banana-2 (Gemini 3.1 Flash Image) and nano-banana-pro (Gemini 3 Pro Image). Auth is via GEMINI_API_KEY env var, web UI key management, or a Vertex AI service account JSON (VERTEX_SERVICE_ACCOUNT_JSON). When both an API key and Vertex credentials are configured, Vertex takes priority. Supports variable aspect ratios (1:1 through 21:9) and four resolution tiers (512px, 1K, 2K, 4K); these controls are only honored on the direct API path — the Vertex AI endpoint ignores aspect/size because it does not accept the response_format field. Per-model cost differs: nano-banana-2 (Flash): 512=$0.001, 1K=$0.003, 2K=$0.004, 4K=$0.006; nano-banana-pro: 1K=$0.007, 2K=$0.007, 4K=$0.013. No web search or mask controls.
• API-key generation supports classic generate, edit, mask-guided edit, multimode, and node generation.
• Grok generation supports Classic, Node, and Agent flows. If a Classic reference, Node parent image, or Agent current image is present, ima2 switches the final Grok call to xAI image edit so image-to-image context is preserved.

If no provider is specified, the app keeps the current GPT OAuth/default behavior. GPT OAuth defaults to gpt-6-luna and API-key generation to gpt-5.6-luna; the API-key path also defaults to low reasoning and 1024x1024 unless the request passes validated options. Grok image generation defaults to grok-imagine-image-2.0.

One caveat on the OAuth Grok lane: xAI documents only /v1/me as accepting an OAuth token, so image and video calls to api.x.ai with that token ride an undocumented path. It works today — progrok relied on the same path — but it carries no compatibility promise. If xAI closes it, provider: "grok-api" with XAI_API_KEY is the documented route and stays unaffected.

Grok image generation exposes a Fast/Best model picker (grok-imagine-image / grok-imagine-image-quality; new sessions start on grok-imagine-image-2.0) and a size picker (aspect ratio + 1k/2k resolution). The Settings page prefers the Grok Build weekly credits percentage and reset time from GET /v1/billing?format=credits; if that source is unavailable, it falls back to the legacy monthly billing window and $used/$limit. A Switch Account button starts a device-code OAuth flow (POST /api/auth/switch) for re-authenticating without leaving the app.

Grok video generation defaults to canonical grok-imagine-video-1.5; grok-imagine-video remains available for base-model-only Ref2V, V2V edit, and extension paths, and the legacy grok-imagine-video-1.5-preview string is accepted as an alias. Three modes are auto-detected from reference count: text-to-video (0 refs), image-to-video (1 ref), and reference-to-video (2-14 refs; up to 15s on grok-imagine-video-1.5, 10s on grok-imagine-video). 1080p is available for grok-imagine-video-1.5 prompt-only text-to-video and single image/frame image-to-video; prompt-only 1.5 uses the internal white-canvas I2V shim before the upstream request. Video controls include duration (1-15s), resolution (480p, 720p, 1080p when supported), and aspect ratio (1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, auto).

These require a running ima2 serve. The CLI covers every server route. The most common ones are below — the full CLI reference lists everything (generation, history, sessions, prompt library, annotations, Card News, observability, config).

The server advertises its actual port at ~/.ima2/server.json. If 3333 is busy, the backend falls back to 3334+ and CLI commands follow the advertised URL. Override discovery with --server <url> or IMA2_SERVER=http://localhost:3333.

ima2 models --kind image
ima2 gen "poster" --model oauth/gpt-6-luna --reasoning-effort high
ima2 gen "1girl, blue hair" --model nai/nai-diffusion-5-full --nai-negative-prompt "lowres, watermark"
ima2 vectorize logo.png -o logo.svg --json
ima2 prompt build --message "Make this prompt production-ready" --backend auto --model auto
ima2 edit input.png --prompt "make it rainy" --web-search
ima2 multimode "two cats playing" -n 2
ima2 video "a cat playing piano" --model grok/grok-imagine-video-1.5 --duration 5 --resolution 720p
ima2 video "animate this" --model grok/grok-imagine-video-1.5 --ref photo.png --aspect-ratio 16:9
ima2 inflight ls --terminal
ima2 config set imageModels.reasoningEffort high

Full reference: docs/CLI.md.

IMA2_GROK_PROXY_HOST, IMA2_GROK_PROXY_PORT, IMA2_NO_GROK_PROXY, and IMA2_GROK_RESTART_* were removed in 3.16 together with the local Grok proxy; they are no longer read, and setting them is harmless.

ima2 serve keeps terminal output intentionally quiet: startup URLs, warnings, and errors stay visible, while request/node/OAuth structured logs are hidden by default.

Use ima2 serve --dev, npm run dev, or IMA2_LOG_LEVEL=debug ima2 serve when you need request IDs, node generation phases, OAuth stream diagnostics, or inflight state transitions. Explicit IMA2_LOG_LEVEL and ~/.ima2/config.json values still override the built-in defaults.

Start ima2 serve, then check ~/.ima2/server.json. You can also run ima2 ping --server http://localhost:3333.

Re-run ima2 setup (option 1), confirm ima2 status, then restart ima2 serve.

GPT OAuth requests leave from the ima2 serve process and go straight to chatgpt.com. On networks that require a proxy, enable your proxy client's TUN/TURN-style mode. If that is not possible, set both HTTPS_PROXY and NODE_USE_ENV_PROXY=1 in the terminal that starts the server; Node.js 22.21+ and 24+ read HTTPS_PROXY only with the second variable; older Node.js ignores both, so use TUN mode there. On Windows, also check for auto-start network interception tools, including DNS/fragmentation bypass tools such as SecretDNS, because they can break OAuth or image responses even when the browser appears connected.

Set OPENAI_API_KEY or configure an API key before using provider: "api". The default GPT OAuth path still works without an API key.

Run ima2 doctor image-probe --json > ima2-image-probe.json and attach the safe JSON when opening an issue. For GPT OAuth cases, also capture ima2 gen "고양이" --model oauth/gpt-6-luna --no-web-search --json and ima2 gen "고양이" --model oauth/gpt-6-luna --json while ima2 serve is running. Do not share ChatGPT cookies, OAuth token files, API keys, raw upstream responses, prompt history, or generated base64. See the FAQ support bundle.

The app compresses large JPEG/PNG references before upload. If a file still fails, convert it to JPEG or PNG at a lower resolution and try again. HEIC/HEIF files are not supported by the browser path.

Recent versions moved generated images from the installed package folder to ~/.ima2/generated. Run ima2 doctor and see Recover old images.

The GPT OAuth lane uses the GPT-6 models your ChatGPT plan exposes. Update ima2-gen, sign in again with ima2 gpt login, then check ima2 models --kind image. If one model keeps failing, switch to gpt-6-luna, the default.

If the requested server port is busy, ima2-gen falls back to the next available port and records it in ~/.ima2/server.json. If the port is unexpectedly 3457, your shell may also have inherited PORT=3457 from another local tool. Run unset PORT or start with IMA2_PORT=3333 ima2 serve.

desktop/ wraps the same local server and UI in a menubar/tray app for macOS, Windows, and Linux. It supervises server.js as a child process (attaching to an already-running server on the configured port instead of starting a second one) and adds a native settings window: port, open at login, start hidden, menubar-only (macOS), keep-server-on-close, log level, config directory.

cd desktop
npm install
npm run prepare:app     # builds server + CLI + UI at the repo root
npm start               # run unpackaged
npm run dist:mac        # dmg + zip (Apple Silicon / arm64)
npm run dist:win        # nsis + zip
npm run dist:linux      # AppImage + deb

Only the macOS app is distributed today, for Apple Silicon. .github/workflows/desktop.yml runs in three ways: a push to dev builds an unsigned macOS validation build, a manual dispatch builds signed and notarized installers without publishing anything, and a desktop-v* tag push builds, verifies, and publishes the desktop release. Trusted macOS builds require MAC_CSC_LINK, MAC_CSC_KEY_PASSWORD, APPLE_ID, APPLE_APP_SPECIFIC_PASSWORD, and APPLE_TEAM_ID; missing or invalid authentication fails the build instead of producing an unsigned success.

For a signed macOS verification build without publishing, run:

gh workflow run desktop.yml --ref <reviewed-branch> -f platform=mac

The workflow verifies Developer ID, team, architecture (arm64), hardened runtime, secure timestamp, nested signatures, Gatekeeper and stapled notarization tickets. It checks the apps recovered from the final ZIP and DMG against the original signed content, then exports ima2-macos-signature-proof reports and installer SHA-256 hashes. Failed verification blocks installer upload. Only a desktop-v* tag push creates and publishes a release.

Signing credential imports run on disposable GitHub-hosted macOS. The builder cleans successfully imported keychains; if import/setup fails before its cleanup registration, runner destruction is the final cleanup boundary. Local recovery should reuse an existing login-keychain identity in the same unlocked session, rather than importing credential packages into a persistent machine. This does not require changing automatic locking or key access rules.

Windows Authenticode remains separate and uses WIN_CSC_LINK / WIN_CSC_KEY_PASSWORD; Windows builds without them are unsigned.