Authentication and models

Mogick stores non-sensitive model settings in config.json and credentials such as API keys and OAuth tokens in auth.json. This page covers authentication and both single- and multi-provider model configuration.

Starting with version 26.9.24, the interactive TUI provides /connect to connect a custom model. To manage model service settings yourself, use the manual configuration examples on this page; use /models to select a model that is already available.

Authentication

Mogick supports OAuth device-code authentication (recommended) and manual API key authentication.

OAuth device-code authentication

Run the interactive wizard and follow the terminal prompts to complete browser authorization:

mogick setup

The terminal displays an authorization URL and a one-time device code. Open the URL, enter the code, sign in, and approve access. Mogick then writes the credentials automatically.

Credentials are stored in <config-dir>/auth.json. When the access token expires, Mogick uses the refresh token automatically. If the model service returns INVALID_OAUTH_TOKEN, Mogick forces a refresh and retries the current request once. Setup also adds the official provider and fills missing default/lightweight model settings while preserving existing providers and explicit model choices.

For authorization failures, browser issues, or expired tokens, see Troubleshoot setup and authentication.

Sign out and switch accounts

Run mogick logout from the shell, or enter /logout in the TUI when signed in with OAuth. This clears OAuth credentials in the effective global authentication file and preserves API keys and model configuration. It does not clear project-level authentication overrides.

After successful sign-out handling, /logout exits the TUI. Run mogick setup to authorize another account, then start Mogick and check /models. /exit only closes the TUI; it does not sign out.

API key authentication

To connect directly to an OpenAI-compatible service, configure these two files:

<config-dir>/auth.json — holds credentials:

{
  "api_key": "<your-api-key>"
}

<config-dir>/config.json — stores the model service address and model name:

{
  "llm": {
    "provider": "openai-compatible",
    "base_url": "https://api.example.com/v1",
    "model": "your-model-id",
    "models": [
      { "id": "your-model-id", "name": "My Model" }
    ]
  }
}

At runtime, a valid OAuth access token takes precedence over the top-level api_key. Never put an API key in config.json, command-line arguments, or screenshots.

The examples below assume llm.providers is absent or empty. If setup has already created a provider array, edit that array using the multi-provider example instead of adding ignored single-provider fields. Replace sample URLs, model IDs and API keys with your service's values; the default and light-model IDs must match entries in models.

Single-provider configuration

For a single model service, configure the llm object directly:

{
  "llm": {
    "provider": "openai-compatible",
    "base_url": "https://api.example.com/v1",
    "model": "model-1",
    "light_model": "model-2",
    "models": [
      { "id": "model-1", "name": "Model One" },
      { "id": "model-2", "name": "Model Two" }
    ]
  }
}

Field	Description
provider	Provider type: openai-compatible or llm-store; without it, /models may not load the model list
base_url	API base URL, usually ending in /v1
model	The model ID used by default
light_model	Model for lightweight tasks such as title generation and summarization; falls back to model
models	Models shown in TUI /models; id is the API model ID and name is the display name

An llm-store provider loads its model catalog dynamically and does not require models[].

Credentials are at the top level of auth.json:

{
  "api_key": "<your-api-key>"
}

For a complete example, see Configure a third-party model.

Multi-provider configuration

To connect multiple model services, use llm.providers[]. Each provider has its own ID, endpoint, and credentials.

config.json:

{
  "llm": {
    "default_model": "private/code-model",
    "providers": [
      {
        "id": "private",
        "type": "openai-compatible",
        "base_url": "https://api.example.com/v1",
        "enabled": true,
        "models": [
          { "id": "code-model", "name": "Private Code Model" }
        ]
      },
      {
        "id": "corp",
        "type": "llm-store",
        "base_url": "https://llm.example.net",
        "enabled": true
      }
    ]
  }
}

llm level fields:

Field	Description
default_model	Default model in provider-id/model-id format; if omitted, Mogick uses the first provider's default model

Fields for each provider in providers[]:

Field	Required	Description
id	Yes	Unique provider identifier; reference a model as provider-id/model-id
type	No	openai-compatible or llm-store; defaults to openai-compatible when omitted
base_url	Yes	Service address; /api/v1 is automatically appended when llm-store is running
enabled	No	Default: true; when false, the provider and its models do not appear
models	Required for openai-compatible	Static model list; initialization fails if no model is enabled. llm-store ignores this field.
app_id	No	llm-store's X-APP-ID request header
extra_headers	No	Non-sensitive additional request headers for this provider

In auth.json, store separate credentials by provider ID:

{
  "providers": {
    "private": {
      "api_key": "<private-api-key>"
    },
    "corp": {
      "access_token": "<corp-access-token>"
    }
  }
}

If a provider has no entry in auth.providers, the runtime falls back to the top-level OAuth token or api_key.

Do not mix single- and multi-provider structures. When llm.providers[] is non-empty, Mogick ignores single-provider fields such as llm.model and llm.base_url. A non-empty project-level llm.providers[] replaces the entire global array.

Configuration paths and precedence

Scope	config	auth
Global	<config-dir>/config.json	<config-dir>/auth.json
Project	<workspace>/.mogick/config.json	<workspace>/.mogick/auth.json

Project configuration takes precedence over global configuration. Never commit an auth.json file to version control.

Model catalog

OpenAI-compatible providers declare static models in models[]:

{
  "id": "vision-model",
  "name": "Vision Model",
  "description": "Text and image input",
  "input_modals": ["text", "image"],
  "output_modals": ["text"],
  "context_length": 128000,
  "enabled": true
}

An llm-store provider loads its catalog dynamically. Disabled providers and models with enabled: false do not appear in /models.

Switch models

Enter /models or Ctrl+P in the TUI to open the Models panel. The model title displays the source in the format provider-id/model-name.

The current session uses the new model immediately. In multi-provider mode, the selection updates llm.default_model; in single-provider mode, it updates llm.model. A model saved with a resumed session takes precedence.

mogick doctor --check-network

--check-network sends a real model request to verify the connection.

Related documents

• Configuration Reference — all fields and default values
• Configure third-party model access — Complete steps for third-party model access
• setup cannot be completed or authentication failed

Choose model-supported reasoning levels with /efforts. For image input and official image tools, see Files and images.

Path placeholders <config-dir> and <db-path> refer to the effective profile/channel paths; see Data directories.