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 | OAuth proxy port. |
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-5.4-mini | Server fallback image model. |
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 disable the auto-started OAuth proxy. |
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.4-mini | 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_PROXY_HOST | 127.0.0.1 | Bundled progrok bind host. |
IMA2_GROK_PROXY_PORT | 18645 | Bundled progrok port. |
IMA2_NO_GROK_PROXY | — | Set 1 to disable auto-starting bundled progrok. |
IMA2_GROK_PLANNER_MODEL | grok-4.3 | xAI search/planner model for provider: "grok". |
IMA2_GROK_PLANNER_TIMEOUT_MS | 60000 | Timeout for each Grok search/planner step. |
IMA2_GROK_IMAGE_MODEL_DEFAULT | grok-imagine-image | Default xAI image model for Grok image calls. |
IMA2_GROK_GENERATION_TIMEOUT_MS | 120000 | Timeout for final Grok image generation/edit calls. |
IMA2_GROK_STATUS_TIMEOUT_MS | 3000 | Timeout for /api/grok/status model probes. |
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
imageModels.default imageModels.reasoningEffort
apiProvider.defaultImageModel apiProvider.defaultReasoningEffort
grokProvider.plannerModel grokProvider.plannerTimeoutMs
grokProvider.defaultImageModel
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.