Model Connection States in Apache Maka: Host Lifecycle and UI Status Explained

Apache Maka tracks model connections through two distinct state machines: the Host Lifecycle State (starting, recovering, ready, draining) governs runtime availability, while the Desktop UI Connection State (unsupported, not_configured, disabled, enabled) controls individual connection usability.

Managing model connection states in Maka requires understanding how the runtime orchestrates host health alongside per-connection availability. The architecture separates infrastructure-level concerns from user-facing connection controls, creating a robust dual-state system defined in the TypeScript source code.

Host Lifecycle States (Runtime Level)

The host lifecycle determines whether the Maka runtime can accept and manage connections at all. These states are defined by the HostLifecycleState type in packages/runtime-host/src/server/host-kernel.ts (lines 28–31, 303–304, and throughout the kernel implementation).

Starting State

When the host enters the starting state, it is bootstrapping essential services and has not yet admitted any connections. During this phase, the system initializes resources but rejects connection attempts until initialization completes.

Recovering State

The recovering state indicates the host has detected a failure and is attempting to restore previous state from persistence. Connections remain unavailable during recovery to prevent operations against inconsistent data.

Ready State

Once the host reaches ready, the runtime is fully operational. In this state, the system accepts connection creation requests, allows queries, and permits active usage. Individual connections may still be unavailable based on their UI status, but the infrastructure supports operations.

Draining State

During shutdown, the host enters draining to initiate graceful degradation. New connections are rejected immediately, while existing connections are allowed to complete their operations. This state ensures clean resource cleanup without abrupt termination of active model inference sessions.

UI Connection States (Desktop Level)

While the host manages infrastructure health, individual connection availability is tracked separately in the desktop UI layer. These states are defined in packages/desktop/src/renderer/ports.ts (line 42) as a union type representing user-facing connection status.

Unsupported

A connection marked unsupported indicates the runtime does not support this specific connection type, often occurring with legacy providers or platform-specific limitations that cannot be satisfied by the current environment.

Not Configured

The not_configured state signals that the connection exists in the catalog but lacks required credentials or provider-specific settings. Users must complete configuration before the connection becomes usable.

Disabled

When set to disabled, the connection is deliberately turned off by the user through the interface. The credentials and configuration remain stored, but the system treats the connection as inactive and will not attempt to use it for model inference.

Enabled

An enabled connection is active and available for use by models, subject to host lifecycle state verification. This does not guarantee immediate connectivity—network issues or provider outages may still prevent actual usage—but indicates user intent to utilize the connection.

How States Interact in Practice

The connection lifecycle follows a strict hierarchy: host states gate all operations, while UI states determine individual connection eligibility. The host must be ready before any UI state evaluation matters.

// Checking whether a connection can be used
import { isRealConnection } from '@maka/core';
import type { LlmConnection } from '@maka/core/llm-connections';

function canSendMessage(conn: LlmConnection, hasSecret: boolean, hostState: string) {
  // First, ensure the host is ready (host-lifecycle state === 'ready')
  if (hostState !== 'ready') return false;

  // Then, evaluate UI-level state
  switch (conn.uiState) {
    case 'enabled':
      return isRealConnection(conn) && hasSecret;
    case 'disabled':
    case 'unsupported':
    case 'not_configured':
      return false;
  }
}

The UI layer maps these low-level states to visual indicators:

// React component rendering connection status
import { useConnectionDetail } from '@/renderer/settings/provider-connection-detail';

export function ConnectionStatusBadge({ slug }: { slug: string }) {
  const { state } = useConnectionDetail(slug);
  const colour = {
    enabled: 'green',
    disabled: 'gray',
    unsupported: 'red',
    not_configured: 'orange',
  }[state];

  return <span style={{ color: colour }}>{state}</span>;
}

Key Source Files and Implementation Details

Understanding the model connection states in Maka requires examining specific source locations where these enumerations and validation logic reside:

• packages/runtime-host/src/server/host-kernel.ts – Defines HostLifecycleState with values starting, recovering, ready, and draining (lines 28–31, 303–304, 359–362, 400, 546–570, 593–648, 848–915, and 982–1107). This file implements the state machine transitions and gates RPC calls based on current host status.

• packages/desktop/src/renderer/ports.ts – Contains the union type defining UI connection states at line 42, determining how the renderer process interprets connection availability for the user interface.

• packages/core/src/connection-readiness.ts – Evaluates whether a connection is ready based on provider configuration, secret availability, and model compatibility criteria.

• packages/runtime-host/src/client/connection.ts – Provides the client-side wrapper that exposes a connection's state property to UI components, bridging the gap between kernel-level states and frontend displays.

Summary

• Host Lifecycle States (starting, recovering, ready, draining) in host-kernel.ts control whether the Maka runtime can process connections at the infrastructure level.
• UI Connection States (unsupported, not_configured, disabled, enabled) in ports.ts manage individual connection availability and user intent.
• Operational readiness requires both the host state to be ready and the individual connection state to be enabled, with additional verification for secrets and provider support.
• Graceful shutdown uses the draining state to allow existing sessions to complete while preventing new connections.
• State evaluation follows a hierarchical pattern: check host lifecycle first, then evaluate UI-specific connection status.

Frequently Asked Questions

What are the possible host lifecycle states in Maka?

Apache Maka defines four host lifecycle states in packages/runtime-host/src/server/host-kernel.ts: starting for bootstrap, recovering for failure restoration, ready for full operation, and draining for graceful shutdown. These states determine whether the runtime infrastructure can accept and manage model connections.

How does Maka represent connection availability in the UI?

The desktop UI tracks connection availability through four states defined in packages/desktop/src/renderer/ports.ts: unsupported for incompatible providers, not_configured for missing credentials, disabled for user-deactivated connections, and enabled for active, usable connections. These states work independently of the host lifecycle but depend on it for actual functionality.

When can a model connection actually be used?

A model connection becomes usable only when the host lifecycle state is ready and the UI connection state is enabled. Additionally, the system verifies that the connection has required secrets and passes validation checks in packages/core/src/connection-readiness.ts. If the host is starting, recovering, or draining, all connections remain unavailable regardless of individual UI state.

Where are these state machines defined in the codebase?

The HostLifecycleState enum resides in packages/runtime-host/src/server/host-kernel.ts (lines 28–31), while the UI connection state union type is located in packages/desktop/src/renderer/ports.ts (line 42). State transition logic and RPC gating appear throughout host-kernel.ts in methods handling bootstrap, recovery, and shutdown sequences.

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