# What Is Apache Maka? Understanding the "Log Is the Runtime" Architecture

> Discover Apache Maka, an agent-centric workspace using a Runtime Event Log as its single source of truth for deterministic replay, transparent debugging, and verifiable benchmarking.

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

---

**Apache Maka is an agent-centric workspace that treats an append-only Runtime Event Log as the single source of truth, enabling deterministic replay, transparent debugging, and verifiable benchmarking.**

Apache Maka (Incubating) is a high-performance workspace designed for AI agent development and evaluation. According to the repository's [`README.md`](https://github.com/apache/maka/blob/main/README.md) and [`ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md), every action taken during a session is recorded in an immutable log that serves as the runtime itself, allowing all UI components and evaluation harnesses to function as thin clients projecting views from this canonical state.

## Core Principle: The Log Is the Runtime

The fundamental architecture of Apache Maka revolves around a single, append-only **Runtime Event Log**. As implemented in [`README.md`](https://github.com/apache/maka/blob/main/README.md) (lines 48-50), every model message, tool call, permission decision, and termination is stored as an append-only `RuntimeEvent`. This design means the log *is* the runtime—not a side effect of it.

All UI components—including Desktop, TUI, and CLI—function as **thin clients** that project views from this immutable log rather than maintaining separate copies of state. This approach enables crash recovery, deterministic replay, and transparent debugging since the entire session history exists as a queryable, ordered sequence of events.

## Architectural Layers of Apache Maka

The system implements a strict layered architecture as documented in [`ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md) (lines 43-49):

### Runtime Event Log

The **canonical source of truth** sits at the bottom layer. Stored in a SQLite-backed database (typically `runtime.sqlite`), this append-only log contains every observable effect of the system. According to [`packages/runtime/src/log.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/log.ts), developers can iterate through events chronologically, with each entry containing a timestamp, event kind, and payload.

### Session Manager and Agent Run

The second layer handles lifecycle control through `SessionManager` and `AgentRun` abstractions. As defined in [`packages/core/src/session.ts`](https://github.com/apache/maka/blob/main/packages/core/src/session.ts), these components manage turn identity, model connections, and permission boundaries while persisting all state changes to the underlying log.

### Agent Graph

The scheduling and dependency resolution layer manages how agents coordinate. This graph structure determines execution order and tool dependencies while ensuring all decisions are ultimately recorded as events in the Runtime Event Log.

### Storage Layer

SQLite-backed operational state provides durable persistence. The storage layer ensures ACID compliance for the append-only log, guaranteeing that once an event is written, it becomes immutable and searchable for future replay or analysis.

## Key Design Tenets of Apache Maka

### Measured, Not Claimed

Benchmarks are published alongside the complete event log, making every run reproducible and comparable. As noted in the source code (lines 46-50 of [`README.md`](https://github.com/apache/maka/blob/main/README.md)), this transparency eliminates opaque performance claims—anyone can replay the exact sequence of events to verify results.

### Your Machine, Your Model

Sessions, settings, and run records remain local to the user's machine. The user supplies their own model endpoint—whether through a cloud API, local model, or gateway—ensuring data sovereignty and allowing flexibility in model selection without vendor lock-in.

### One Runtime Host

All front-ends (Desktop, TUI, CLI, bots, and evaluation frameworks) interact with a **single Runtime Host** that owns the session. As documented in [`ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md) (lines 24-33), this host manages turn identity, tool execution, and permissions, ensuring consistent behavior across all interfaces.

## Working with Apache Maka: Code Examples

### Running Tasks via CLI

To start using Apache Maka immediately:

```bash

# Clone, install dependencies, and run a task

git clone https://github.com/apache/maka.git
cd maka
npm ci
npm run cli:dev -- run "Summarize the repository's purpose"

```

The CLI client connects to the local Runtime Host, streams the log, and prints the final answer. This implementation is documented in [`packages/cli/README.md`](https://github.com/apache/maka/blob/main/packages/cli/README.md).

### Programmatic Session Control

For custom integrations, instantiate the Runtime Host directly:

```typescript
import { createRuntimeHost } from '@maka/runtime-host';
import { createSession } from '@maka/core';

// Create a host bound to a specific state-root (workspace)
const host = await createRuntimeHost({ workspace: './workspaces/default' });

// Open a new session
const session = await createSession(host, { model: 'gpt-4o-mini' });

// Run a single turn
const result = await session.runTurn('Explain the core principle of Apache Maka');
console.log(result.output);

```

All interactions—including model calls, tool usage, and permission prompts—are persisted to the Runtime Event Log. This example references implementations in [`packages/runtime-host/src/index.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/index.ts) and [`packages/core/src/session.ts`](https://github.com/apache/maka/blob/main/packages/core/src/session.ts).

### Querying the Runtime Event Log

Inspect session history programmatically:

```typescript
import { openRuntimeLog } from '@maka/runtime';

const log = await openRuntimeLog('./workspaces/default/runtime.sqlite');
for await (const ev of log.iterate()) {
  console.log(`[${ev.timestamp}] ${ev.kind}: ${ev.payload}`);
}

```

The log is a standard SQLite database where each entry is immutable and replayable. This functionality is implemented in [`packages/runtime/src/log.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/log.ts).

## Core Source Files and Responsibilities

Understanding the repository structure clarifies how the "log is the runtime" principle manifests in code:

- **[`README.md`](https://github.com/apache/maka/blob/main/README.md)** - High-level overview, core principles, and getting-started guide (lines 46-51 detail the tenets)
- **[`ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md)** - System map, component boundaries, and deep-dive links (lines 24-33 cover the Runtime Host)
- **`packages/core/`** - Pure TypeScript contracts for sessions, events, permissions, and connections
- **`packages/runtime/`** - `SessionManager`, `AgentRun`, model adapters, tool runtime, and log handling
- **`packages/runtime-host/`** - Single-owner Runtime Host implementation and public client protocol ([`src/index.ts`](https://github.com/apache/maka/blob/main/src/index.ts))
- **`packages/cli/`** - TUI/CLI front-ends that drive the host
- **`apps/desktop/`** - Electron UI that projects the log into a rich desktop experience
- **`packages/eval/`** - Experiment framework for benchmark cells, attempts, and results
- **`native/`** - Rust addon for peer-to-peer communication and git-oxide helpers

## Summary

- **Apache Maka** treats an append-only **Runtime Event Log** as the single source of truth, where the log itself constitutes the runtime state.
- All interfaces (CLI, TUI, Desktop) are **thin clients** that project views from this immutable log, ensuring consistent state across all access methods.
- The architecture enforces **"measured, not claimed"** benchmarking by publishing complete event logs alongside performance results.
- **Data locality** ensures sessions and settings remain on the user's machine, with support for local or cloud-based models.
- The codebase is organized into distinct layers: Runtime Event Log, Session Management, Agent Graph, and Storage, implemented across `packages/runtime/`, `packages/core/`, and `packages/runtime-host/`.

## Frequently Asked Questions

### What makes Apache Maka different from other AI agent frameworks?

Unlike frameworks that maintain state in mutable variables or distributed services, Apache Maka persists every operation to an append-only **Runtime Event Log**. This design enables deterministic replay of entire sessions, transparent debugging by inspecting the event sequence, and verifiable benchmarking where published results include the complete log for independent verification.

### How does the append-only log improve reproducibility?

Because every model message, tool call, and permission decision is stored as an immutable `RuntimeEvent` in the SQLite-backed log (as implemented in [`packages/runtime/src/log.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/log.ts)), developers can replay the exact sequence of events to reproduce any bug or benchmark result. The log captures not just outputs but the complete operational context, including timing and intermediate states.

### Can I use Apache Maka with local LLMs?

Yes. Apache Maka follows the **"your machine, your model"** principle. When creating a session via `createSession()`, you specify the model endpoint—whether that's a local Ollama instance, a self-hosted vLLM server, or a cloud API. The framework handles the connection while keeping all session data and logs local to your workspace.

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

Session state persists in a SQLite database (typically `./workspaces/default/runtime.sqlite`) managed by the **Runtime Host**. As documented in [`ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md), the host owns the session lifecycle and ensures all state changes are written to the append-only log before acknowledgment. This single-source-of-truth approach eliminates synchronization issues between multiple front-ends accessing the same workspace.