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

> Explore Apache Maka's model connection states. Understand host lifecycle and UI status transitions like starting, ready, unsupported, and enabled for robust application management.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: deep-dive
- Published: 2026-09-04

---

**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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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.

```ts
// 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:

```tsx
// 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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/packages/desktop/src/renderer/ports.ts) (line 42). State transition logic and RPC gating appear throughout [`host-kernel.ts`](https://github.com/apache/maka/blob/main/host-kernel.ts) in methods handling bootstrap, recovery, and shutdown sequences.