# Apache Maka's Architecture: The Single-Execution-Authority Model

> Explore Apache Maka's core principle: a single-execution-authority model. Discover how its Runtime Host centralizes work execution for efficient, thin-client operations.

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

---

**Apache Maka's architecture is built around a single-execution-authority model where the Runtime Host serves as the sole component authorized to execute work, while all front-ends act as thin clients that delegate operations to this central authority.**

Apache Maka is an open-source framework that implements a distinctive approach to AI agent orchestration through strict architectural separation. Understanding Apache Maka's architecture requires examining its foundational principle: the Runtime Host maintains exclusive rights to execute all sessions, tool calls, and lifecycle operations, providing a consistent and secure foundation for diverse client interfaces.

## The Single-Execution-Authority Principle

The cornerstone of Apache Maka's architecture, as documented in `ARCHITECTURE.md#L24-L33`, is the **single-execution-authority model**. The Runtime Host is the only component that can actually execute work, while all other interfaces—including Desktop, TUI, CLI, bots, and evaluation clients—function as passive requesters that lack execution capabilities.

This design centralizes five critical concerns within the Runtime Host:

- **Session Identity**: Unique session and turn IDs are generated and managed exclusively by the Runtime Host, guaranteeing reliable continuation across network failures or crashes
- **Tool Runtime**: All tool invocations flow through the Runtime Host, which maintains the **Runtime Event Log** for complete observability
- **Permissions**: Capability checks occur exclusively at the Runtime Host before any work is scheduled or admitted
- **Recovery**: Crash recovery and context pruning operate from a canonical source of truth, ensuring state consistency
- **Evaluation Boundary**: Even evaluation frameworks delegate execution to the Runtime Host rather than running experiments independently

## Centralized Control Mechanisms

### Session and Turn Management

Within `packages/runtime`, the Runtime Host implements exclusive control over session lifecycles through components like `SessionManager` and `AgentRun`. When a client initiates a conversation, the Runtime Host generates the canonical session identity and maintains the state necessary for turn-by-turn continuity. This prevents state drift between different client interfaces and ensures that recovery operations reference a single source of truth.

### Unified Tool Runtime and Logging

The Runtime Host funnels all tool calls through a centralized pipeline. When a client requests a tool invocation, the Runtime Host logs the operation in the **Runtime Event Log** before execution, captures the result, and returns the output to the requesting client. This centralized logging enables complete audit trails across all entry points, from CLI commands to programmatic API calls.

### Admission Control and Recovery

Before scheduling any work, the Runtime Host enforces capability checks based on the session's permissions. If a crash occurs, the recovery mechanisms in `packages/runtime` handle context pruning and state restoration, preserving the integrity of active sessions without requiring client-side intervention.

## Client Interaction Patterns

All front-end implementations follow a consistent pattern: package user intent, transmit to the Runtime Host, and render responses. This thin-client architecture ensures that business logic and security policies remain server-side.

### CLI Execution Flow

The command-line interface in [`packages/cli/src/cli.ts`](https://github.com/apache/maka/blob/main/packages/cli/src/cli.ts) demonstrates this delegation pattern. When a user executes:

```bash

# Initialise a new session and run a prompt

maka run "Summarize the latest Apache releases"

```

The CLI packages the request, transmits it to the Runtime Host, and streams the resulting output back to the terminal. The CLI itself never executes prompts or accesses tool runtimes directly.

### Programmatic Tool Invocation

For TypeScript applications, the `RuntimeHostClient` class in [`packages/runtime-host/src/client.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/client.ts) provides the bridge to the Runtime Host:

```typescript
import { RuntimeHostClient } from '@maka/runtime-host';

const client = new RuntimeHostClient();
await client.invokeTool({
  tool: 'web-search',
  args: { query: 'Apache HTTP Server release notes' },
});

```

This client forwards the tool request to the Runtime Host, which validates permissions, logs the invocation, executes the tool, and returns results.

### Evaluation Delegation

Even evaluation experiments follow the single-authority principle. The `EvalExperiment` class in [`packages/eval/src/experiment.ts`](https://github.com/apache/maka/blob/main/packages/eval/src/experiment.ts) defines benchmark semantics but delegates execution:

```typescript
import { EvalExperiment } from '@maka/eval';

const exp = new EvalExperiment({
  name: 'HTTP Server Benchmarks',
  subjects: ['httpd-2.6', 'httpd-2.8'],
  tasks: ['fetch-homepage'],
  repetitions: 5,
});
await exp.run();   // Internally contacts the Runtime Host

```

The evaluation framework only describes the experiment structure; the Runtime Host handles all actual execution, ensuring consistent measurement environments.

## Key Source Files and Components

The single-execution-authority principle is implemented across these critical paths:

- **`packages/runtime-host/`**: Implements the sole execution authority, handling session admissions, the public protocol, and the `RuntimeHostClient`
- **`packages/runtime/`**: Contains `SessionManager`, `AgentRun`, tool adapters, context handling, and crash recovery mechanisms
- **`packages/cli/`**: Front-end client including the `maka run` command and TUI implementation
- **`packages/eval/`**: Defines experiment semantics (cells, attempts, result selection) while routing execution through the Runtime Host
- **[`ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md)**: High-level design documentation specifying the single-authority principle at lines 24-33

## Summary

- Apache Maka's architecture centers on a **single-execution-authority model** where only the Runtime Host can execute work
- All front-ends (CLI, TUI, Desktop, bots, evaluators) function as thin clients that delegate to the Runtime Host
- The Runtime Host exclusively manages **session identity**, **permissions**, **event logging**, and **crash recovery**
- Tool invocations flow through the Runtime Host, enabling unified observability via the **Runtime Event Log**
- Even evaluation frameworks in `packages/eval` defer execution to the Runtime Host, maintaining architectural consistency

## Frequently Asked Questions

### What is the core principle of Apache Maka's architecture?

The core principle is the **single-execution-authority model**, where the Runtime Host acts as the exclusive execution engine. According to [`ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md), this design ensures that only one component manages session state, permissions, and tool execution, while all other interfaces remain thin clients that request services from this central authority.

### How do front-end clients interact with the Runtime Host?

Front-ends use client libraries like `RuntimeHostClient` (defined in [`packages/runtime-host/src/client.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/client.ts)) to send requests via the public protocol. The CLI in [`packages/cli/src/cli.ts`](https://github.com/apache/maka/blob/main/packages/cli/src/cli.ts) demonstrates this pattern by packaging user commands and transmitting them to the Runtime Host, then streaming results back without local execution.

### What happens if the Runtime Host crashes during execution?

The Runtime Host maintains the canonical state for all sessions in `packages/runtime`, enabling crash recovery and context pruning from a single source of truth. When the Runtime Host restarts, it can recover active sessions and resume operations without data loss, as all state remains centralized rather than distributed across client interfaces.

### Can evaluation experiments run independently of the Runtime Host?

No. Despite defining benchmark semantics in [`packages/eval/src/experiment.ts`](https://github.com/apache/maka/blob/main/packages/eval/src/experiment.ts), the `EvalExperiment` class internally contacts the Runtime Host to execute tasks. This ensures that evaluation runs occur within the same controlled environment as production sessions, maintaining consistent permissions, logging, and recovery capabilities across all execution contexts.