Skip to content

02_Connecting a Model

Jump to bottom
Umut Sevdi edited this page Oct 27, 2026 · 9 revisions

Connecting a Model

Imza is model-agnostic: it talks to OpenAI-compatible endpoints and the Anthropic Messages API, including locally hosted models. Bring your own API key, your own subscription (where supported), or your own local server. Open the connections screen at any time with /connect. To connect external tool servers instead, see MCP servers.

Connections modal

API keys are kept in your OS keychain, not in config.json. On a machine with no keychain service, Imza keeps them in config.json for that run and warns you at startup. To choose that storage deliberately and silence the warning, set preferences.credentials to plaintext. See Credentials.

Adding an API-Key Provider

In the Add Provider section:

  1. Provider: Type to search the built-in catalog, press Enter to pick one. Choose Custom for any OpenAI-compatible endpoint; a Base URL field appears (e.g. http://localhost:1234/v1). A trailing /chat/completions path is stripped automatically.
  2. Label: Optional name to tell apart multiple connections to the same provider (e.g. my Ollama). Required when it is already connected; cannot contain /.
  3. API Key: Your key, masked in the list. Omit for endpoints that need no key.
  4. Test: Verifies the connection and fetches its model list. Once it shows ✓ <N> models, the button becomes Save.

Existing connections are listed at the top with status (✓ ready, ✗ failed, ⟳ fetching), masked key, and model count. Press DEL on a row to remove it (confirm with y); the last remaining connection cannot be removed.

Keyboard: ↑↓ navigate · Enter/DEL remove · Esc close · Ctrl+R refresh model lists.

Subscription Sign-In (ChatGPT Plans)

Pick the subscription entry in the provider picker and the API-key field is replaced by a sign-in pane. Imza requests a device code, shows it in the pane with the full verification URL (so a remote SSH session can open the link by hand; it is also a clickable hyperlink where the terminal supports it), opens the page in your browser, and polls until you approve or a fifteen-minute limit expires.

Credentials are stored on the connection and refreshed automatically before they expire. Use a different Label to sign in with multiple accounts.

OpenAI subscriptions

Choosing the Active Model

/model opens the model picker: every model from all your connections, filterable by text, with provider, model id, and context window size where known. Your current model is tagged · current at the top. Enter to switch. Embedding, speech, and image-generation models are hidden.

Reasoning Effort

/variant <effort> sets the reasoning effort sent with each request: off, low, default, high. The active effort shows in the status line next to the model name. Reasoning is translated into whatever your provider and model support; unsupported fields are omitted rather than sent.

Your model and variant choices persist to the providers and models sections of your configuration file. Override them for one run with imza --model|-M <model> / --variant|-V <variant>.

See Configuration for the keys and how reasoning effort is applied, and the command line reference.

Clone this wiki locally