# What Is the Runtime Host in Apache Maka? The Central Execution Engine Explained

> Discover the Runtime Host in Apache Maka, the central execution engine managing event logs and delegating computations for all thin-client interfaces. Learn how Maka ensures immutability and efficient processing.

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

---

**The Runtime Host in Apache Maka is the single execution authority that powers all thin-client front-ends, maintaining an immutable append-only event log while delegating actual computation away from Desktop, TUI, CLI, and Eval interfaces.**

The **Runtime Host** serves as the architectural backbone of Apache Maka, acting as the central engine that strictly separates presentation layers from computational logic. Unlike traditional applications where each client interface runs its own independent process, Maka’s architecture delegates all execution to this shared authority according to the source code in `apache/maka`. This design enables consistent state management, crash recovery, and historical replay across all user interfaces.

## Centralized Execution Authority

The Runtime Host functions as the sole computational engine for the entire Maka ecosystem. Rather than distributing logic across multiple client processes, all **thin-client** front-ends—including Desktop, TUI, CLI, and Eval—connect to a single Runtime Host instance that owns every execution turn.

As implemented in [`packages/runtime-host/src/client/connection.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/client/connection.ts), the connection layer defines how these lightweight clients forward requests to the shared host. The host then becomes the **single source of truth** for all subsequent operations, ensuring that state mutations occur in exactly one place regardless of which interface initiated the action.

## Immutable Event Logging and State Management

A defining characteristic of the Runtime Host is its maintenance of an **append-only log** (referred to as the "runtime") that records every event occurring during execution. This log serves as the system’s immutable history, enabling features like state reconstruction, audit trails, and crash recovery.

According to the source in [`packages/runtime-host/src/server/host-kernel.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/host-kernel.ts), the **host kernel** implements the core execution loop that drives this logging mechanism. Each operation generates a `RuntimeEvent` that is permanently appended to the log, creating a linear, verifiable history of all agent activities that can be projected to UI layers or replayed after failures.

## Architectural Components

The Runtime Host’s functionality is distributed across several critical source files that handle execution, connectivity, and state projection.

### Host Kernel Implementation

The file [`packages/runtime-host/src/server/host-kernel.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/host-kernel.ts) contains the core kernel that drives the Runtime Host’s execution loop. This component manages the agent’s computational lifecycle, coordinates turn-based execution, and ensures that every state transition is captured in the append-only log before acknowledgment is returned to clients.

### Client Connection Layer

Thin clients communicate with the host through the abstraction defined in [`packages/runtime-host/src/client/connection.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/client/connection.ts). This module standardizes how external interfaces authenticate with the Runtime Host, forward execution requests, and receive state updates. By centralizing connection logic here, Maka ensures that all clients—from interactive Desktop applications to automated CLI scripts—interact with the execution engine through a unified protocol.

### Live UI Projection

UI components access the Runtime Host’s state through [`packages/ui/src/live-turn-projection.ts`](https://github.com/apache/maka/blob/main/packages/ui/src/live-turn-projection.ts), which demonstrates how interfaces project live state from the host’s immutable log. Rather than maintaining local state, UI layers subscribe to the log and render current application state by interpreting the sequence of recorded events, enabling real-time synchronization across multiple connected clients.

## Working with the Runtime Host

Developers interact with the Runtime Host through high-level APIs that abstract the underlying client-host communication while maintaining the architectural benefits of centralized execution.

### Starting a Desktop Session

The Desktop client automatically manages the Runtime Host lifecycle, launching the host process if not already running and establishing the connection that becomes the single authority for all subsequent runs:

```typescript
import { startDesktop } from '@maka/desktop';

// The Desktop client will launch the Runtime Host if it isn't already running.
// The host then becomes the single authority for all subsequent runs.
await startDesktop();

```

### Executing CLI Commands

Command-line operations delegate to the same shared Runtime Host, which executes the task and records the corresponding `RuntimeEvent` in the append-only log:

```typescript
import { run } from '@maka/cli';

// The CLI forwards the request to the Runtime Host, which executes it
// and records the corresponding RuntimeEvent in the log.
await run(['my-task', '--option']);

```

### Accessing the Event Log from UI Components

React components can subscribe directly to the Runtime Host’s immutable log through the `useRuntimeLog` hook, enabling rendering of historical or current execution state:

```tsx
import { useRuntimeLog } from '@maka/ui';

function LogViewer() {
  const log = useRuntimeLog();           // pulls the append-only log from the Runtime Host
  return (
    <ul>
      {log.map(event => (
        <li key={event.id}>{event.summary}</li>
      ))}
    </ul>
  );
}

```

## Summary

- The Runtime Host acts as the **single execution authority** for all Apache Maka client interfaces, eliminating distributed state management issues.
- It maintains an **append-only event log** (the "runtime") that records every turn, enabling crash recovery, historical replay, and audit capabilities.
- **Thin-client** architectures in Desktop, TUI, CLI, and Eval interfaces delegate all computation to the host via the connection layer defined in [`packages/runtime-host/src/client/connection.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/client/connection.ts).
- The **host kernel** in [`packages/runtime-host/src/server/host-kernel.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/host-kernel.ts) drives the core execution loop and ensures immutable logging.
- UI layers project state from the host’s log rather than maintaining independent state, as demonstrated in [`packages/ui/src/live-turn-projection.ts`](https://github.com/apache/maka/blob/main/packages/ui/src/live-turn-projection.ts).

## Frequently Asked Questions

### What is the difference between the Runtime Host and the Desktop client in Apache Maka?

The Runtime Host is the centralized execution engine that runs the agent and maintains the immutable event log, while the Desktop client is a **thin-client** interface that merely renders state and forwards user input. According to the source in [`website/src/copy/en.ts`](https://github.com/apache/maka/blob/main/website/src/copy/en.ts), the Desktop client launches the Runtime Host if not already running, but all actual computation occurs within the host process, not the client.

### How does the Runtime Host enable crash recovery?

The Runtime Host records every execution event in an **append-only log** before acknowledging completion to any client. Because this log is immutable and comprehensive, the system can reconstruct exact application state by replaying the event sequence from the beginning or from a known checkpoint, effectively eliminating data loss from unexpected terminations.

### Can multiple clients connect to the same Runtime Host simultaneously?

Yes, the architecture supports multiple concurrent connections through the client connection layer implemented in [`packages/runtime-host/src/client/connection.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/client/connection.ts). Since the Runtime Host owns all state mutations and exposes them via the shared log, multiple interfaces (such as Desktop and CLI) can observe and interact with the same execution context in real-time without state synchronization conflicts.

### Where is the Runtime Host log stored in the file system?

While the provided source code does not specify exact storage paths, the Runtime Host’s **append-only log** is managed by the host kernel in [`packages/runtime-host/src/server/host-kernel.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/host-kernel.ts). The log persists as a durable, append-only data structure accessible to all connected clients through the APIs demonstrated in [`packages/ui/src/live-turn-projection.ts`](https://github.com/apache/maka/blob/main/packages/ui/src/live-turn-projection.ts) and the `useRuntimeLog` hook.