# How Does Apache Maka Work? Architecture, Event Log, and Runtime Host Explained

> Explore Apache Maka's architecture, event log, and runtime host. Discover how this agent workspace enables deterministic UI, crash recovery, and multi-agent coordination.

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

---

**Apache Maka is a high-performance, single-Runtime-Host-authority agent workspace that records every action as an append-only Runtime Event log, enabling deterministic UI projections, crash recovery, and multi-agent coordination through a thin client architecture.**

The `apache/maka` repository implements a deterministic agent execution environment where a single **Runtime Host** maintains authoritative control over session identity, tool execution, and state persistence. Unlike distributed agent systems, Maka centralizes execution authority in one host per **State Root** (a persistent SQLite store), while thin clients—Desktop, TUI, CLI, or bots—merely project the immutable event log. This architecture ensures that every model message, tool call, and permission decision is permanently recorded for auditability and deterministic replay.

## Core Architecture Components

### The Runtime Host

The **Runtime Host** is the single authority that owns the `SessionManager` and `AgentRun` instances controlling the lifecycle of a *Maka subject* (a model-driven task). According to the source code in `packages/runtime-host`, the host provides admission control, client capabilities, and the public protocol for all interactions. Only one host runs per State Root, executing work on behalf of all thin clients while maintaining the execution lifecycle and permission boundaries.

### The Runtime Event Log

At the heart of Maka lies the **Runtime Event Log**, an append-only SQLite store that serves as the **canonical source of truth** for every interaction. Located in `packages/storage`, this log records model messages, tool calls, tool results, permission decisions, and termination facts. Because the log is immutable, UI components can build deterministic projections of context, session state, and recovery views by simply querying the event sequence.

### Agent Graph and Multi-Agent Scheduling

The **Agent Graph** control plane, documented in [`docs/architecture/agent-graph-stream-scheduling-draft.md`](https://github.com/apache/maka/blob/main/docs/architecture/agent-graph-stream-scheduling-draft.md), schedules dependent work using child sessions and feeds activations back through the Runtime Host. This enables **multi-agent coordination** where parent sessions can spawn child tasks while maintaining deterministic execution order through the same event log mechanism.

### Eval Boundary (`@maka/eval`)

Maka separates benchmark concerns through the **Eval Boundary** in `packages/eval`. This component manages experiments as purely declarative structures containing subjects, tasks, repetitions, cells, attempts, and result selection. The Runtime Host executes only the defined subjects, ensuring that evaluation logic remains separate from runtime execution.

## Code Boundaries and Package Structure

The repository organizes functionality into strict package boundaries:

- **`packages/core`** – Pure TypeScript contracts for Sessions, Events, Permissions, and Protocol definitions
- **`packages/storage`** – Interactive SQLite stores for runtime state and configuration persistence
- **`packages/runtime`** – Execution engine containing `SessionManager`, `AgentRun`, model adapters, tool runtimes, context management, and recovery logic
- **`packages/runtime-host`** – Single-owner Runtime Host lifecycle implementation and public client protocol
- **`packages/eval`** – Experiment definition, cell/attempt handling, and evaluation adapters
- **`packages/cli`** – TUI implementation, `maka run` command, and public `maka eval` entry points
- **`apps/desktop/src/main`** – Electron composition layer and product-entry adapters

## High-Level Data Flow

When you interact with Apache Maka, data flows through a deterministic pipeline:

1. A thin client (Desktop, TUI, or CLI) sends a **run request** to the Runtime Host process
2. The Host instantiates a **Session** and **AgentRun**, loading the specified model adapter and required tool runtimes from `packages/runtime`
3. Each interaction turn produces a **RuntimeEvent** (model message, tool invocation, or permission resolution)
4. Events append to the **Runtime Event Log** via `packages/storage` utilities
5. UI components query the log to build live **projections** of context, task state, and session views
6. If the Host crashes, the **resume** logic in [`docs/architecture/runtime-resume-architecture.md`](https://github.com/apache/maka/blob/main/docs/architecture/runtime-resume-architecture.md) replays the log to reconstruct exact state

## Practical Usage Examples

### Running Tasks from the CLI

Build the workspace and launch the interactive TUI to execute agent tasks:

```bash

# Build the workspace

npm run build

# Start the interactive TUI

npm run cli:dev

# Run a single turn task

npm run cli:dev -- run "Summarise the Apache Maka repository and list its main components"

```

*Source: [`README.md`](https://github.com/apache/maka/blob/main/README.md) – CLI entry points*

### Benchmarking with the Eval API

Define and run declarative experiments using the `@maka/eval` package:

```javascript
import { createEvalClient } from '@maka/eval';

// Initialize with your model configuration
const evalClient = createEvalClient({ model: 'gpt-4o-mini' });

await evalClient.runExperiment({
  name: 'Maka-Benchmark',
  subjects: [{ id: 'default' }],
  tasks: [{ prompt: 'Summarise the architecture of Apache Maka' }],
  repetitions: 3,
});

```

*Source: `packages/eval` – Experiment definition API*

### Querying the Runtime Event Log

Access the canonical event store directly for debugging or audit purposes:

```javascript
import { openRuntimeDb } from '@maka/storage';

async function listRecentEvents() {
  const db = await openRuntimeDb('runtime.sqlite');
  const rows = await db.all(
    `SELECT id, type, timestamp, payload 
     FROM runtime_events 
     ORDER BY timestamp DESC 
     LIMIT 10`
  );
  console.table(rows);
}

listRecentEvents();

```

*Source: `packages/storage` – SQLite storage utilities*

## Essential Architecture Documents

For deep dives into specific subsystems, consult these problem-oriented documents referenced in [`ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md):

- **[`docs/architecture/runtime-host-architecture.md`](https://github.com/apache/maka/blob/main/docs/architecture/runtime-host-architecture.md)** – Detailed Runtime Host contract, admission control, and scope boundaries
- **[`docs/architecture/peer-mesh-architecture.md`](https://github.com/apache/maka/blob/main/docs/architecture/peer-mesh-architecture.md)** – Network identity, stream recovery, and peer-to-peer mesh protocols
- **[`docs/architecture/runtime-core-architecture-draft.md`](https://github.com/apache/maka/blob/main/docs/architecture/runtime-core-architecture-draft.md)** – Runtime core implementation and compaction strategies
- **[`docs/architecture/runtime-resume-architecture.md`](https://github.com/apache/maka/blob/main/docs/architecture/runtime-resume-architecture.md)** – Crash recovery, continuation logic, and deterministic state restoration
- **[`docs/architecture/agent-graph-stream-scheduling-draft.md`](https://github.com/apache/maka/blob/main/docs/architecture/agent-graph-stream-scheduling-draft.md)** – Multi-agent scheduling algorithms and dependency resolution

## Summary

- **Apache Maka** operates as a single-Runtime-Host-authority system where one host controls execution per State Root (SQLite database)
- The **Runtime Event Log** provides an append-only, immutable record of all model interactions and tool executions, enabling deterministic replay
- **Thin clients** (Desktop, TUI, CLI) are stateless projectors that communicate via the Host protocol, with no local execution authority
- **Code boundaries** separate concerns into `packages/core` (contracts), `packages/runtime` (execution), `packages/runtime-host` (authority), and `packages/eval` (benchmarking)
- **Crash recovery** works by replaying the event log from `packages/storage`, ensuring no state loss during Host restarts

## Frequently Asked Questions

### What is the Runtime Host in Apache Maka?

The **Runtime Host** is the single authoritative process that owns session lifecycle, tool execution, and the event log for a given State Root. According to the `apache/maka` source code in `packages/runtime-host`, it provides the public protocol for all client interactions and maintains the only mutable authority over the append-only Runtime Event Log. Only one Host runs per SQLite State Root, ensuring deterministic execution without distributed consensus overhead.

### How does Apache Maka handle crash recovery?

Maka implements deterministic crash recovery through **log replay**. When the Runtime Host restarts after a failure, the resume logic documented in [`docs/architecture/runtime-resume-architecture.md`](https://github.com/apache/maka/blob/main/docs/architecture/runtime-resume-architecture.md) reads the immutable Runtime Event Log from `packages/storage` and reconstructs the exact execution state, including model context and pending tool calls. Because all state changes append to the log, recovery requires no checkpoints or snapshots—just sequential event replay.

### What is the Eval Boundary used for?

The **Eval Boundary** (`@maka/eval`) separates benchmarking and experimentation concerns from production runtime execution. Located in `packages/eval`, it manages declarative experiment definitions containing subjects, tasks, cells, attempts, and result selection criteria. The Runtime Host executes these experiments as pure subjects, allowing researchers to benchmark agent performance without modifying core runtime logic or polluting production state stores.

### How do thin clients interact with the Runtime Host?

Thin clients—including the Electron Desktop app (`apps/desktop`), TUI, and CLI (`packages/cli`)—communicate with the Runtime Host through a public protocol, sending run requests and receiving event projections. These clients possess no execution authority; they merely render views based on queries to the Runtime Event Log. This architecture allows multiple client types to share the same deterministic execution state while maintaining security boundaries between untrusted UI code and the privileged Host process.