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

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, 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, 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 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. 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, 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:

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:

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:

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.
• The host kernel in 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.

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, 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. 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. 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 and the useRuntimeLog hook.

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