# How to Configure and Manage Multiple Model Connections in Apache Maka

> Learn to configure and manage multiple model connections in Apache Maka using the JSON catalog and management interface. Integrate AI services efficiently.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: how-to-guide
- Published: 2026-08-27

---

**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`](https://github.com/apache/maka/blob/main/connection-catalog.json) file, while keeping sensitive credentials isolated in an encrypted [`credential-vault.json`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/apps/desktop/src/renderer/settings/use-connection-detail.ts)) writes the entry to [`connection-catalog.json`](https://github.com/apache/maka/blob/main/connection-catalog.json) while encrypting secrets into [`credential-vault.json`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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.

```typescript
// 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`](https://github.com/apache/maka/blob/main/packages/runtime/src/model-adapter.ts).

### Building Provider-Specific Options

When initializing a connection, the runtime calls `buildProviderOptions` (line 166 in [`model-factory.ts`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/session-catalog-coordinator.ts). This class provides imperative control over the connection lifecycle.

```typescript
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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/connection-catalog.json) contains only public metadata and configuration flags, while [`credential-vault.json`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/connection-catalog.json) and encrypted credentials in [`credential-vault.json`](https://github.com/apache/maka/blob/main/credential-vault.json) within the workspace directory.
- The **`getAIModel`** function in [`packages/runtime/src/model-factory.ts`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/credential-vault.json) within your workspace directory (`<Electron userData>/workspaces/default/`). Public metadata resides in [`connection-catalog.json`](https://github.com/apache/maka/blob/main/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.