Reference
Configuration
Effective values follow a three-layer order: environment variables override
~/.ima2/config.json, which overrides built-in defaults.
Environment variables
| Variable | Default | Description |
|---|---|---|
IMA2_PORT / PORT | 3333 | Web server port. |
IMA2_HOST | 127.0.0.1 | Web server bind host. |
IMA2_OAUTH_PROXY_PORT / OAUTH_PORT | 10531 | Port of the external GPT OAuth endpoint used with IMA2_NO_OAUTH_PROXY=1. |
IMA2_SERVER | — | CLI target override. |
IMA2_CONFIG_DIR | ~/.ima2 | Config and SQLite location. |
IMA2_ADVERTISE_FILE | ~/.ima2/server.json | Runtime discovery file. |
IMA2_GENERATED_DIR | ~/.ima2/generated | Generated image directory. |
IMA2_IMAGE_MODEL_DEFAULT | gpt-6-luna | Server fallback image model. |
IMA2_PROMPT_BUILDER_BACKEND | auto | Prompt Builder text backend; Auto selects the first ready supported backend. |
IMA2_PROMPT_BUILDER_MODEL | auto with Auto backend | Backend-scoped Builder model. Changing backend resets this to that backend's default. |
IMA2_REASONING_EFFORT | medium | Default reasoning effort for the default (OAuth) path; one of none, low, medium, high, xhigh. |
IMA2_NO_OAUTH_PROXY | — | Set 1 to send GPT OAuth calls to an OpenAI-compatible endpoint on 127.0.0.1:IMA2_OAUTH_PROXY_PORT instead of ChatGPT directly. |
IMA2_LOG_LEVEL | info | serve defaults to info, dev to debug; accepts debug, info, warn, error, silent. |
IMA2_INFLIGHT_TERMINAL_TTL_MS | 300000 | Recent terminal job retention for debug views. |
OPENAI_API_KEY | — | API key for the API-provider Responses path and auxiliary features. |
IMA2_API_IMAGE_MODEL_DEFAULT | gpt-5.6-luna | Default image model for the API path. |
IMA2_API_REASONING_EFFORT | low | Default reasoning effort for the API path. |
IMA2_API_IMAGE_SIZE | 1024x1024 | Default size for the API path. |
IMA2_API_ALLOW_WEB_SEARCH | true | Toggle web search for the API path. |
IMA2_GROK_PLANNER_MODEL | grok-4.3 | xAI search/planner model. Grok 4.5 and 4.6 are selectable. |
IMA2_GROK_PLANNER_TIMEOUT_MS | 900000 | Timeout for each Grok search/planner step. |
IMA2_GROK_SEARCH_TIMEOUT_MS | 300000 | Timeout for the mandatory xAI web-search step. |
IMA2_GROK_VIDEO_PLAN_TOTAL_TIMEOUT_MS | 1500000 | Ceiling for the whole video search + planner phase. |
IMA2_GROK_IMAGE_MODEL_DEFAULT | grok-imagine-image-2.0 | Default xAI image model for Grok image calls. |
IMA2_GROK_VIDEO_MODEL_DEFAULT | grok-imagine-video-1.5 | Default xAI video model for Grok generation. |
IMA2_GROK_GENERATION_TIMEOUT_MS | 300000 | Timeout for final Grok image generation/edit calls. |
IMA2_GROK_STATUS_TIMEOUT_MS | 3000 | Timeout for /api/grok/status model probes. |
GEMINI_API_KEY | — | API key for the gemini-api provider direct path. |
VERTEX_SERVICE_ACCOUNT_JSON | — | Google Cloud service-account JSON (inline) for Vertex AI auth on the gemini-api provider. When both GEMINI_API_KEY and this are set, Vertex takes priority unless the last-saved geminiAuthMode overrides it. |
IMA2_OAUTH_MASKED_EDIT_ENABLED | false | Opt-in masked-edit flag on the OAuth path (#31, groundwork only). |
The config file
ima2 config reads and writes ~/.ima2/config.json (the file layer). It
rejects unknown keys, refuses auth keys (provider, apiKey), and warns
when an env var is overriding the same key. Change auth with ima2 setup or
ima2 login instead.
Common writable keys
promptBuilder.backend promptBuilder.model
imageModels.default imageModels.reasoningEffort
apiProvider.defaultImageModel apiProvider.defaultReasoningEffort
grokProvider.plannerModel grokProvider.plannerTimeoutMs
grokProvider.defaultImageModel grokProvider.defaultVideoModel
log.level features.cardNews
server.port server.host server.bodyLimit
oauth.proxyPort limits.maxRefCount limits.maxParallel
history.defaultPageSize history.maxPageCap storage.generatedDirRun ima2 config keys for the authoritative list, or ima2 config ls --effective to see merged values.
Logging modes
ima2 serve stays intentionally quiet: startup URLs, warnings, and errors are
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 phases, OAuth
stream diagnostics, or inflight transitions.