How to Configure and Manage Multiple Model Connections in Apache Maka

Apache Maka manages every LLM or AI service as a persisted model connection in a JSON catalog, exposing them through the getAIModel runtime API and the SessionCatalogCoordinator management interface.

Apache Maka treats every LLM provider as a configurable model connection that lives in a persisted catalog and is accessed through a unified runtime API. Whether you are integrating OpenAI, Anthropic, or local model binaries, understanding how to configure and manage multiple model connections in Apache Maka is essential for building flexible AI workflows. This guide covers the storage architecture, runtime resolution, and programmatic management of connection catalogs based on the actual source implementation.

Understanding the Connection Catalog Architecture

Apache Maka persists all model configurations in a workspace-specific connection-catalog.json file, while keeping sensitive credentials isolated in an encrypted credential-vault.json. These files reside under the Electron user data directory at <Electron userData>/workspaces/default/, ensuring that connection metadata and secrets are stored separately. According to the security notes in README.md (lines 22-24), the credential vault is never exposed to the renderer process, maintaining strict isolation between the UI and sensitive tokens.

The ConnectionCatalog schema defines the structure of these entries, tracking each connection's slug, provider type, enabled status, and default selection flag. This persisted state allows Maka to maintain multiple simultaneous provider configurations across application restarts without re-authentication.

Adding and Configuring Model Connections

You can create new model connections through either the desktop interface or the CLI. In the UI, navigate to Settings → Models; alternatively, run maka settings models from the command line. The configuration flow requires three components:

• Provider selection – Choose from OpenAI, Anthropic, Claude Subscription, or local model binaries.
• Credential input – Supply an API key, complete an OAuth flow, or specify a path to a local executable.
• Activation – Enable the connection and optionally mark it as the default for new tasks.

When you save, the desktop application (via apps/desktop/src/renderer/settings/use-connection-detail.ts) writes the entry to connection-catalog.json while encrypting secrets into credential-vault.json. The connection becomes immediately available to the runtime without requiring an application restart.

Runtime Resolution and the Model Factory

The runtime resolves model connections through the Model Factory API located in packages/runtime/src/model-factory.ts. This module provides two primary functions for working with configured connections.

Resolving Connections with getAIModel

The getAIModel function accepts an optional connectionSlug parameter and returns a validated model instance. If you omit the slug, the function automatically falls back to the workspace's default connection.

// packages/runtime/src/model-factory.ts
import { getAIModel, buildProviderOptions } from '@maka/runtime/model-factory';

// Retrieve a specific connection by its slug
const model = await getAIModel({ connectionSlug: 'my-openai-key' });

// Or use the default connection
const defaultModel = await getAIModel();

Under the hood, getAIModel performs health validation (checking online status, credential validity, and provider health at line 166) before returning an object exposing the doStream, doChat, and doTool methods. These methods standardize interactions across different LLM providers through the adapter pattern implemented in packages/runtime/src/model-adapter.ts.

Building Provider-Specific Options

When initializing a connection, the runtime calls buildProviderOptions (line 166 in model-factory.ts) to construct provider-specific configuration objects. This ensures that each adapter receives correctly formatted authentication headers, endpoint URLs, and model parameters regardless of the underlying service.

Managing Connections Programmatically

For automated workflows or plugin development, Apache Maka exposes the Session Catalog Coordinator in packages/runtime-host/src/server/session-catalog-coordinator.ts. This class provides imperative control over the connection lifecycle.

import { SessionCatalogCoordinator } from '@maka/runtime-host/server/session-catalog-coordinator';

const coordinator = new SessionCatalogCoordinator();

// Add a new connection
await coordinator.addConnection({ 
  slug: 'my-anthropic', 
  enabled: true, 
  provider: 'anthropic',
  // additional provider-specific options
});

// Remove obsolete connections
await coordinator.removeConnection('old-connection');

// Change the default
await coordinator.setDefault('my-anthropic');

The coordinator surfaces granular error messages when operations fail. Lines 731-747 of the coordinator implementation handle specific failure modes such as "Session model connection is unavailable" or "Connection uses a sign-in that was removed", allowing your application to respond appropriately to configuration drift or revoked credentials.

Per-Task Connection Selection

Apache Maka supports connection switching at the task level through the llmConnectionSlug parameter. In the desktop UI, the composer interface provides a dropdown selector that populates this value, while the CLI accepts the --model <slug> flag. If the parameter is omitted, the runtime consults the default connection specified in the catalog.

This flexibility enables complex workflows where a single workspace might route code generation tasks to a local model while sending research queries to a cloud provider. The resolution logic validates the specified slug against the enabled connections in connection-catalog.json before instantiation.

Storage Security and Health Validation

When a connection becomes invalid—such as when an API key is revoked—Maka displays contextual warnings like "Missing API key" (referenced in conversation-copy.ts at line 652). The system distinguishes between configuration errors (missing catalog entries) and authentication errors (vault decryption failures), guiding users toward the appropriate resolution path.

The architecture maintains strict security boundaries: connection-catalog.json contains only public metadata and configuration flags, while credential-vault.json houses encrypted tokens. This separation allows version control of workspace settings without exposing secrets, and enables the renderer process to display connection lists without accessing actual credentials.

Summary

• Apache Maka persists model configurations in connection-catalog.json and encrypted credentials in credential-vault.json within the workspace directory.
• The getAIModel function in packages/runtime/src/model-factory.ts resolves connection slugs to validated model instances with standardized doChat, doStream, and doTool methods.
• SessionCatalogCoordinator provides programmatic CRUD operations and default management for connection catalogs.
• Connections can be selected per-task via the llmConnectionSlug parameter or the --model CLI flag, falling back to the workspace default when unspecified.
• Security isolation prevents the renderer process from accessing credential-vault.json, ensuring API keys and OAuth tokens remain encrypted at rest.

Frequently Asked Questions

How do I add a new model connection in Apache Maka?

Open the desktop application and navigate to Settings → Models, or run maka settings models in your terminal. Select your provider (OpenAI, Anthropic, etc.), enter the required credentials such as an API key or OAuth flow, and enable the connection. The configuration is immediately persisted to connection-catalog.json in your workspace directory.

What happens if my API key is revoked or becomes invalid?

When the runtime detects an authentication failure, it surfaces an error message such as "Missing API key" (as implemented in conversation-copy.ts). The SessionCatalogCoordinator validates connections before use and throws specific errors like "Connection uses a sign-in that was removed" when credentials are missing from the vault. You must update the credentials through the Settings UI or remove and recreate the connection.

Can I use different models for different tasks in the same workspace?

Yes. Each task or conversation turn can specify a llmConnectionSlug to target a specific provider. The UI provides a model selector dropdown in the composer, and CLI commands accept the --model <slug> argument. If no slug is provided, Maka automatically uses the current default connection configured in your catalog.

Where are model connection credentials stored securely?

Sensitive credentials are encrypted and stored in credential-vault.json within your workspace directory (<Electron userData>/workspaces/default/). Public metadata resides in connection-catalog.json. According to the project README (lines 22-24), the credential vault is strictly isolated from the renderer process, ensuring that API keys and tokens are never exposed to the UI layer or external scripts.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}