# Apache Maka Runtime Host: Architecture, Responsibilities, and Implementation

> Discover the Apache Maka Runtime Host's architecture and responsibilities. Learn how it ensures durability, consistency, and recovery for AI workloads in Maka.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: architecture
- Published: 2026-08-30

---

**The Runtime Host is the long-lived process that owns a single State Root and serves as the exclusive authority for durability, consistency, and recovery of AI workloads in Apache Maka.**

The Runtime Host forms the architectural cornerstone of the Apache Maka project, acting as the central authority that mediates all durable state mutations and execution lifecycles. Unlike architectures where clients instantiate their own runtime environments, Apache Maka enforces a strict separation: clients (Desktop, TUI, CLI, bots, or evaluation code) submit work to the Host, which maintains the exclusive write lease on the State Root. This design ensures that exactly one process controls the durable stores at any given time, eliminating race conditions while enabling seamless recovery across disconnections and restarts.

## Core Architectural Responsibilities

The Runtime Host consolidates several critical concerns into a single, well-defined boundary that governs how AI workloads execute and persist.

### Exclusive State Root Ownership

At the heart of the Runtime Host’s architecture is its **exclusive write lease** on the State Root. According to the Apache Maka source code in [`packages/storage/src/state-root-composition.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/state-root-composition.ts), the Host guarantees that only one process can mutate the durable state at any time. This "one writer per State Root" rule prevents competing processes from corrupting the canonical state, making the Host the single source of truth for workspace recovery.

### Host Kernel and Process Lifecycle

The **Host Kernel**, implemented in [`packages/runtime-host/src/server/host-kernel.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/host-kernel.ts), manages the process lifecycle, authentication, listener setup, and "residency" bookkeeping that keeps the Host alive while work is in progress. When the kernel starts, it acquires the State Root lease and opens listeners for client connections.

```typescript
// packages/runtime-host/src/server/host-kernel.ts
import { HostKernel } from './host-kernel';

// Start the Host Kernel – it acquires the State Root lease and opens listeners.
await HostKernel.start({
  stateRootId: 'my-workspace-root',
  compositionId: 'interactive',
});

```

The kernel remains active as long as work is in progress, ensuring that transient client disconnections do not interrupt durable operations.

### Static Domain Module Composition

At startup, the Runtime Host instantiates a **fixed Host Composition** that never changes during the Host’s lifetime. Defined in [`packages/runtime-host/src/server/host-composition.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/host-composition.ts), this composition builds a static set of **Domain Modules** (such as Session and Scheduled-Task modules), each owning a distinct business capability. The [`packages/runtime-host/src/server/execution-composition.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/execution-composition.ts) file defines the static coordinator that assembles these modules for execution, ensuring predictable behavior and simplifying reasoning about system state.

### Top-Level Execution Coordination

The Host coordinates all top-level execution through the **Hosted Execution Authority**, implemented in [`packages/runtime-host/src/server/hosted-execution-authority.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/hosted-execution-authority.ts). This authority admits exactly one *root execution* for a Session at a time, preventing concurrent top-level Turns and ensuring deterministic execution order.

```typescript
// packages/runtime-host/src/server/hosted-execution-authority.ts
import { admitRootExecution } from './hosted-execution-authority';

// A client asks the Host to run a new Turn.
const { snapshot, completion, settled } = await admitRootExecution({
  sessionId: 'session-42',
  turnId: 'turn-7',
});

```

The authority tracks the execution’s snapshot, completion signals, and cleanup, providing the structural guarantees necessary for durable AI workloads.

### Session Continuity and Run Composition

The Runtime Host maintains **Session Continuity** through [`packages/runtime-host/src/server/session-continuity-coordinator.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/session-continuity-coordinator.ts), which publishes size-limited live updates to every connected client and reconstructs canonical snapshots from durable stores after disconnections or restarts. The **Run Composer**, referenced in [`packages/core/src/run-composition.ts`](https://github.com/apache/maka/blob/main/packages/core/src/run-composition.ts), freezes the model-visible prompt before any provider call, persisting a Run Composition so that the model always sees a stable, durable context regardless of client churn.

## Client-Host Interaction Model

Apache Maka’s architecture strictly separates client concerns from runtime authority. Clients never create their own Runtime; instead, they communicate with the Host through well-defined coordination points that preserve the Host’s exclusive control.

### Client Capability Binding

The **Client Capability Coordinator** ([`packages/runtime-host/src/server/client-capability-coordinator.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/client-capability-coordinator.ts)) handles the publishing, binding, and reverse-call lifecycle of client capabilities. This allows a client-published tool or service (such as a desktop file opener) to be invoked from the Host without transferring ownership of the Session or Run.

```typescript
// packages/runtime-host/src/server/client-capability-coordinator.ts
import { invokeCapability } from './client-capability-coordinator';

// Host calls back into the client to use a client‑side capability (e.g., open a file).
await invokeCapability({
  capabilityId: 'desktop.openFile',
  args: { path: '/tmp/report.txt' },
});

```

This bounded reverse-call mechanism enables rich client-side integrations while maintaining the Host’s authority over execution state.

### Workspace Resolution

Before any execution begins, the Host resolves workspace targets via the **Workspace Resolver** in [`packages/runtime-host/src/server/workspace-resolver.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/workspace-resolver.ts). This component converts a `WorkspaceTarget` (specified as either a project ID or host path) into a canonical absolute directory on the Host, ensuring consistent path semantics across different client types.

## Key Implementation Files

The Runtime Host’s responsibilities are distributed across several TypeScript modules in the `packages/runtime-host` and related directories:

- **[`packages/runtime-host/src/server/host-kernel.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/host-kernel.ts)**: Manages process lifecycle, State Root lease acquisition, authentication, and listener shutdown.
- **[`packages/runtime-host/src/server/host-composition.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/host-composition.ts)**: Builds the immutable composition of Domain Modules at startup.
- **[`packages/runtime-host/src/server/execution-composition.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/execution-composition.ts)**: Defines the static coordinator that assembles modules for execution.
- **[`packages/runtime-host/src/server/hosted-execution-authority.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/hosted-execution-authority.ts)**: Implements the contract for admitting and tracking the root execution of a Session.
- **[`packages/runtime-host/src/server/session-continuity-coordinator.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/session-continuity-coordinator.ts)**: Provides live snapshots and stream updates to clients during active Sessions.
- **[`packages/runtime-host/src/server/client-capability-coordinator.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/client-capability-coordinator.ts)**: Handles reverse calls into client capabilities without ceding execution ownership.
- **[`packages/runtime-host/src/server/workspace-resolver.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/workspace-resolver.ts)**: Resolves `WorkspaceTarget` objects into canonical host paths.
- **[`packages/core/src/run-composition.ts`](https://github.com/apache/maka/blob/main/packages/core/src/run-composition.ts)**: Stores the immutable prompt and tool basis for a Run before provider dispatch.
- **[`packages/storage/src/state-root-composition.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/state-root-composition.ts)**: Persists the binding between a State Root and its Composition identity.

## Summary

The Runtime Host in Apache Maka serves as the durable, authoritative foundation for AI workload execution:

- It maintains an **exclusive write lease** on the State Root, ensuring single-writer consistency and preventing state corruption.
- It runs the **Host Kernel** to manage process lifecycle and client connections, acquiring the State Root lease at startup via `HostKernel.start()`.
- It instantiates an **immutable Host Composition** of Domain Modules that provide business capabilities without runtime reconfiguration.
- It coordinates execution through the **Hosted Execution Authority**, admitting only one root execution per Session via `admitRootExecution()` to prevent concurrency conflicts.
- It preserves **Session Continuity** and **Run Composition** across client disconnections, using durable stores as the single source of truth.
- It enables **Client Capability** binding and **Workspace Resolution** without transferring execution ownership to clients.

## Frequently Asked Questions

### What is the difference between the Runtime Host and a Maka client?

The **Runtime Host** is a long-lived server process that owns the State Root and maintains exclusive write access to durable stores. A **Maka client** (such as a Desktop app, TUI, or CLI) is a transient consumer that submits work to the Host via requests. Clients never instantiate their own Runtime or mutate state directly; they rely entirely on the Host for durability and consistency.

### How does the Runtime Host ensure data consistency across client disconnections?

The Host uses **Session Continuity** mechanisms and **Durable Stores** as the single source of truth. When a client disconnects, the Host continues execution and persists state changes. Upon reconnection, the client receives a reconstructed canonical snapshot from the durable stores, ensuring the workspace appears exactly as it was before the interruption.

### Can multiple Runtime Hosts access the same State Root simultaneously?

No. The Runtime Host architecture enforces a strict **"one writer per State Root"** policy. When a Host starts, it acquires an exclusive write lease on the State Root. This prevents competing processes from corrupting the durable state and ensures that recovery logic always consults a single, authoritative source of truth.

### What happens when a client invokes a capability during active execution?

When a client publishes a capability (such as opening a file dialog), the Host invokes it through the **Client Capability Coordinator** without transferring ownership of the Session or Run. The Host makes a bounded reverse call into the client using `invokeCapability()`, waits for the result, and continues execution. This maintains the Host’s authority while enabling rich client-side integrations.