# What Is the Runtime Host in Apache Maka? Execution Authority and Architecture

> Discover the Runtime Host in Apache Maka. It acts as the central execution authority, managing agent lifecycles and maintaining the event log as the sole truth.

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

---

**The Runtime Host is the central execution authority in Apache Maka that exclusively owns all session-level state, orchestrates every turn of an agent's lifecycle, and maintains the durable event log as the system’s sole source of truth.**

The Apache Maka project implements a strictly centralized architecture where the **Runtime Host** serves as the single authority for all runtime operations. According to the source code in `apache/maka`, every client—whether Desktop, TUI, CLI, or bot—delegates execution to this component rather than managing local runtimes. This design ensures consistent permission enforcement, tool sandboxing, and state recovery across all interaction modes.

## Centralized Execution Authority

The Runtime Host is the only component permitted to create and manage **Session** and **Turn** identities. As documented in [`ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md), it controls the agent lifecycle, handles permission grants, schedules tool executions, and emits canonical **RuntimeEvents**. No client-facing frontend maintains a secondary runtime; instead, all work requests flow through the host’s admission and queuing layer.

This authority model guarantees that:

- **Identity & Lifecycle** – The host owns Session, Turn, Run, and Invocation IDs.
- **Admission & Queuing** – It controls message admission, queuing policies, and turn boundaries.
- **Tool & Permission Management** – It executes sandboxed tools and records every permission action.
- **Event Logging** – It persists every model text, thinking trace, tool call, and terminal result.

## Control Flow Through the Host’s Pipeline

Internally, the Runtime Host implements a **control-plane** that connects the high-level `SessionManager` to the low-level tool execution stack. The execution flow follows a strict pipeline through six core components:

1. **SessionManager** – Receives public requests at [`packages/runtime/src/session-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts) and forwards them to the host kernel.
2. **RuntimeKernel** – Creates an `AgentRun` and registers the active run within the kernel’s state.
3. **AgentRun** – Provides a durable envelope for the execution and writes the initial `RuntimeEvent` to the log.
4. **RuntimeRunner** – Defines the uniform Invocation protocol and guarantees a single terminal `RuntimeEvent` per run.
5. **AiSdkFlow** – Maps legacy `SessionEvents` to canonical `RuntimeEvents` for backward compatibility.
6. **ToolRuntime** – Executes sandboxed tools, records their effects, and feeds results back to the model.

This pipeline ensures that every operation is recorded before state changes propagate to projections like the `SessionStore` or `AgentRunStore`.

## The Runtime Event Log as Source of Truth

All state within Apache Maka is a **projection** over the ordered **Runtime Event Log**. The host’s event log is immutable and serves as the system’s source of truth; UI views, model history, and recovery snapshots are derived solely from this sequence. Before a Run header is closed, the host guarantees that a terminal `RuntimeEvent` exists, enabling reliable crash recovery and deterministic continuation.

## Connecting to the Runtime Host

Clients communicate with the Runtime Host via WebSocket transport. The following TypeScript example demonstrates how to establish a connection, open a session, and send messages using the public client package:

```typescript
import { RuntimeHostConnectionImpl } from '@maka/runtime-host/client/connection';
import { RuntimeHostSessionChannel } from '@maka/runtime-host/client/session-channel';

async function main() {
  // Connect to the host (WebSocket endpoint started by the desktop/CLI runner)
  const conn = new RuntimeHostConnectionImpl('ws://localhost:8080');
  await conn.connect();

  // Open a new session for this client
  const session = await conn.openSession({
    clientId: 'example-cli',
  });

  // Send a user message – routed through SessionManager → RuntimeKernel → AgentRun
  await session.sendMessage({
    role: 'user',
    content: 'Explain the role of the Runtime Host.',
  });

  // Listen for live runtime events (model replies, tool calls)
  const channel = new RuntimeHostSessionChannel(session);
  channel.onEvent(event => {
    console.log('Runtime event:', event);
  });
}

main().catch(console.error);

```

The example above demonstrates three critical integration points:

- `RuntimeHostConnectionImpl` establishes the **WebSocket transport** defined in [`packages/runtime-host/src/transport/websocket-transport.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/transport/websocket-transport.ts).
- `openSession` invokes the **SessionManager** entry point at [`packages/runtime/src/session-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts).
- `sendMessage` triggers a **RuntimeEvent** that is persisted before any UI projection occurs.

## Key Source Files

The Runtime Host architecture is implemented across several critical files in the `apache/maka` repository:

- [`ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md) – High-level description of the Runtime Host’s responsibilities and execution spine.
- [`packages/runtime/src/session-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts) – Public façade that forwards requests to the host kernel.
- [`packages/runtime/src/runtime-kernel.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-kernel.ts) – Core control-plane that creates `AgentRun` objects and assembles the execution pipeline.
- [`packages/runtime/src/agent-run.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/agent-run.ts) – Durable envelope for runs; handles initial and terminal `RuntimeEvent` writes.
- [`packages/runtime/src/runtime-runner.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-runner.ts) – Defines the Invocation protocol and terminal event guarantees.
- [`packages/runtime/src/ai-sdk-flow.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/ai-sdk-flow.ts) – Adapts legacy `SessionEvents` to canonical `RuntimeEvents`.
- [`packages/runtime-host/src/transport/websocket-transport.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/transport/websocket-transport.ts) – WebSocket transport implementation for client connections.
- [`packages/runtime-host/src/client/connection.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/client/connection.ts) – High-level client wrapper exposing `openSession` and `sendMessage`.

## Summary

- The **Runtime Host** is the sole execution authority in Apache Maka, eliminating distributed state by centralizing all runtime operations.
- It exclusively manages **Session** and **Turn** identities, tool permissions, and the agent lifecycle through a six-stage control-plane pipeline.
- All system state is a projection of the immutable **Runtime Event Log**, enabling reliable recovery and deterministic replay.
- Clients connect via WebSocket transport using `RuntimeHostConnectionImpl` and delegate all work to the host rather than maintaining local runtimes.
- Key coordination occurs in [`runtime-kernel.ts`](https://github.com/apache/maka/blob/main/runtime-kernel.ts), [`session-manager.ts`](https://github.com/apache/maka/blob/main/session-manager.ts), and [`agent-run.ts`](https://github.com/apache/maka/blob/main/agent-run.ts), with durable guarantees enforced by [`runtime-runner.ts`](https://github.com/apache/maka/blob/main/runtime-runner.ts).

## Frequently Asked Questions

### How does the Runtime Host differ from client frontends in Apache Maka?

Client frontends—such as the Desktop app, TUI, or CLI—are stateless consumers that send requests to the Runtime Host. According to the architecture documentation, none of these frontends own a secondary runtime; they merely render projections of the host’s event log. The host alone performs admission control, queues messages, and executes tools.

### What guarantees the durability of agent runs in Apache Maka?

The `RuntimeRunner` component enforces a protocol that guarantees a single terminal `RuntimeEvent` before a Run header is closed, as implemented in [`packages/runtime/src/runtime-runner.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-runner.ts). This ensures that the `AgentRun` durable envelope contains a completed event sequence, enabling crash recovery and preventing partial state commits.

### Can tools execute outside the Runtime Host’s control?

No. The **ToolRuntime** executes all tools within a sandboxed environment managed by the host. It records tool effects and results back to the model only through the host’s event log, ensuring that permission boundaries and execution history remain centralized and auditable.

### Where is the session state actually stored in Apache Maka?

While the `SessionStore` and `AgentRunStore` maintain working projections for performance, the **Runtime Event Log** in the host is the authoritative source of truth. All stores derive their state from this log, meaning the physical storage of truth is the ordered sequence of `RuntimeEvents` managed by the host.