# How Apache Maka Ensures Consistent Behavior Across Desktop, CLI, and Eval Entry Points

> Learn how Apache Maka ensures consistent behavior across desktop CLI and eval entry points. Discover its Runtime Host architecture for unified session and tool management.

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

---

**Apache Maka guarantees identical runtime behavior across all interfaces by funneling every user interaction through a single Runtime Host that manages a shared SessionManager, AgentRun, and ToolRuntime pipeline.**

Apache Maka is an open-source agent framework that provides multiple user interfaces including a Desktop GUI, a TUI/CLI, and an evaluation harness. To ensure consistent behavior across different entry points, Maka implements a centralized **Runtime Host** architecture where all interfaces delegate to the same kernel-level services. This design eliminates behavioral divergence regardless of how users interact with the system.

## The Runtime Host Architecture

### Unified Bootstrap Process

Every entry point—whether the Electron Desktop app, the CLI, or the evaluation runner—starts the same process defined in [`packages/runtime-host/src/server/runtime-host.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/runtime-host.ts). This host instantiates a **Runtime Kernel** that encapsulates the agent, model adapters, tool runtimes, and the durable event log. By centralizing initialization in a single file, Maka ensures that all interfaces begin with identical runtime configuration and state management capabilities.

### SessionManager as the State Authority

Once the Runtime Host starts, it hands the kernel to a **SessionManager** located at [`packages/runtime/src/session-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts). This manager owns the lifecycle of sessions and turns, persisting all state to a SQLite ledger (`runtime.sqlite`). Because every entry point uses the identical SessionManager implementation, actions such as starting a turn, recording a tool call, or persisting a transcript follow the exact same code path and storage semantics.

## Shared Execution Pipeline

The **AgentRun** implementation ([`packages/runtime/src/agent-run.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/agent-run.ts)) and the **ToolRuntime** ([`packages/runtime/src/tool-runtime.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/tool-runtime.ts)) are instantiated once per process by the kernel. This singleton pattern guarantees that model calls, tool invocations, and error handling behave identically whether they originate from the Electron renderer, the CLI, or the evaluation runner. The `runtimeHost.runTurn()` method serves as the unified entry point for agent execution across all interfaces.

## Persistence and Configuration Standards

### Single Source of Truth for State

All entry points read from and write to the same `runtime.sqlite` database, which acts as the authoritative record of every turn. According to the architecture documentation in [`docs/architecture/runtime-resume-architecture.md`](https://github.com/apache/maka/blob/main/docs/architecture/runtime-resume-architecture.md), this shared persistence layer ensures that recovery and resume operations function identically across interfaces. A turn started in the Desktop GUI can be resumed in the CLI without state translation or migration.

### Common Configuration Layer

Configuration files such as [`connection-catalog.json`](https://github.com/apache/maka/blob/main/connection-catalog.json) and [`settings.json`](https://github.com/apache/maka/blob/main/settings.json) reside in the Electron `userData` directory and are accessible to all entry points. This shared configuration space prevents divergent behaviors caused by interface-specific settings, ensuring that model connections, tool registrations, and runtime parameters remain consistent.

## Transport Protocol Standardization

The Desktop, TUI, and Eval layers communicate with the Runtime Host via a lightweight framed-transport protocol defined in [`packages/runtime-host/src/transport/framed-transport.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/transport/framed-transport.ts). This strictly typed, JSON-RPC-style message contract ensures that the host receives identically structured requests regardless of the client. By standardizing the UI-to-Kernel contract at the protocol level, Maka eliminates divergence in request handling and response processing.

## Cross-Interface Execution Example

The following examples demonstrate how the same turn executes through identical pipeline stages across different entry points.

To run a turn from the CLI (TUI/CLI entry point):

```bash

# Install the development CLI

npm run build
npm run cli:dev -- run "Summarize this repository and identify its most important risk"

```

To execute the same turn from the Desktop UI:

1. Launch the Electron app (`npm run dev`).
2. Open the workspace pane, create a new turn, and type the prompt *"Summarize this repository and identify its most important risk"*.
3. The UI sends the prompt over the framed-transport to the Runtime Host, which processes it through the identical AgentRun flow as the CLI.

To run an evaluation spec (Eval entry point):

```bash
npm run cli:dev -- eval run specs/example-spec.yaml --out results/

```

All three commands ultimately invoke the same `runtimeHost.runTurn()` method inside the shared kernel.

## Summary

- **Centralized Runtime Host**: All entry points bootstrap through [`packages/runtime-host/src/server/runtime-host.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/runtime-host.ts), ensuring identical initialization.
- **Unified Session Management**: The SessionManager in [`packages/runtime/src/session-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts) provides consistent state handling and SQLite persistence across interfaces.
- **Singleton Execution Components**: AgentRun and ToolRuntime are instantiated once per process, guaranteeing uniform model and tool behavior.
- **Standardized Transport**: The framed-transport protocol in [`packages/runtime-host/src/transport/framed-transport.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/transport/framed-transport.ts) ensures identical message contracts between all clients and the Runtime Host.
- **Shared Persistence**: The `runtime.sqlite` database serves as the single source of truth for all turns, enabling seamless cross-interface resume.

## Frequently Asked Questions

### Does Maka share the same database between the Desktop GUI and CLI?

Yes. Both interfaces read from and write to the same `runtime.sqlite` file managed by the SessionManager. This allows you to start a session in the GUI and resume it in the CLI, or vice versa, with full state preservation.

### How does Maka prevent configuration drift between entry points?

All entry points load configuration from the same `userData` directory, accessing files like [`connection-catalog.json`](https://github.com/apache/maka/blob/main/connection-catalog.json) and [`settings.json`](https://github.com/apache/maka/blob/main/settings.json). By reading from a shared configuration space rather than maintaining interface-specific configs, Maka ensures that model connections and tool registrations remain synchronized.

### What happens if I run the same turn in both the Desktop app and CLI simultaneously?

Since both interfaces delegate to the same Runtime Host process and SessionManager, simultaneous execution attempts are serialized through the SQLite ledger. The durable event log prevents state corruption by treating the database as the single source of truth for turn state.

### Are tool executions deterministic across different interfaces?

Yes. Tool invocations are handled by the singleton ToolRuntime ([`packages/runtime/src/tool-runtime.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/tool-runtime.ts)) regardless of the entry point. This ensures that tool behavior, error handling, and side effects are consistent whether triggered from the Desktop GUI, CLI, or evaluation harness.