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

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

# 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 – CLI entry points

Benchmarking with the Eval API

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

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:

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:

• docs/architecture/runtime-host-architecture.md – Detailed Runtime Host contract, admission control, and scope boundaries
• docs/architecture/peer-mesh-architecture.md – Network identity, stream recovery, and peer-to-peer mesh protocols
• docs/architecture/runtime-core-architecture-draft.md – Runtime core implementation and compaction strategies
• docs/architecture/runtime-resume-architecture.md – Crash recovery, continuation logic, and deterministic state restoration
• 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 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.

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