# What Are the Core Components of Apache Maka?

> Explore the ten core components of Apache Maka. Understand its layered architecture, runtime host, session identity, and tool execution for efficient data processing.

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

---

**Apache Maka is organized into ten distinct packages that form a layered architecture spanning core contracts, runtime execution, evaluation frameworks, and user interfaces, centered around a Runtime Host that owns session identity and tool execution.**

Apache Maka is a modular agent workspace designed for high-performance AI experimentation and execution. Understanding the core components of Apache Maka requires examining its package-based architecture, where each layer maintains strict boundaries while contributing to a unified backend spine. The repository structure follows a clear separation between backend services, frontend applications, and supporting infrastructure.

## Backend Infrastructure Layer

The foundation of Apache Maka rests on two packages that define contracts and manage persistence.

### Core Contracts

The **`packages/core`** directory contains pure TypeScript contracts that define the fundamental interfaces for the entire system. According to the source code in [`packages/core/src/agent-run.ts`](https://github.com/apache/maka/blob/main/packages/core/src/agent-run.ts) and related files, this layer specifies protocols for sessions, runtime events, agent runs, permissions, and model interactions. These contracts remain implementation-agnostic, ensuring that higher-level packages depend only on abstractions rather than concrete implementations.

### Storage Layer

The **`packages/storage`** package provides interactive runtime stores backed by SQLite. It handles configuration persistence and payload storage, ensuring that session state and agent outputs remain durable across restarts. This package manages the schema and query logic that underpin the runtime's state management capabilities.

## Runtime Execution Engine

The execution heart of Apache Maka resides in two tightly coupled packages that manage the lifecycle of AI agents.

### Session and Agent Management

The **`packages/runtime`** directory implements the core execution logic, including the **SessionManager**, **AgentRun**, model adapters, tool runtime, and context handling. As defined in [`packages/runtime/src/agent-run.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/agent-run.ts), this package contains the graph-based scheduling engine and recovery mechanisms that orchestrate multi-turn conversations. The runtime handles the complexities of model connections, tool invocation, and state transitions while maintaining the event log that drives the system.

### Execution Authority

The **`packages/runtime-host`** acts as the single-owner execution authority and exposes the public client/protocol boundary. This package owns session and turn identity, manages tool handling permissions, and serves as the definitive entry point for all execution requests. The Runtime Host maintains the state root and ensures that only authorized operations modify system state, creating a security boundary between user interfaces and the execution kernel.

## Evaluation and Interface Layers

Apache Maka provides comprehensive tooling for benchmarking AI performance and interacting with the system.

### Benchmark Framework

The **`packages/eval`** package supplies the experiment framework for testing and validating agent behavior. It defines the concepts of cells, attempts, and results while providing adapters for executors and subjects. Unlike the runtime packages, Eval sits atop the Runtime Host, providing experiment semantics without holding execution authority. This separation allows researchers to run reproducible experiments while leveraging the full capabilities of the runtime engine.

### Command Line and Desktop Interfaces

User interaction with Apache Maka occurs through three interface packages:

- **`packages/cli`**: Supplies the TUI, non-interactive CLI (`maka`), and the public `maka eval` command entry points documented in [`packages/cli/README.md`](https://github.com/apache/maka/blob/main/packages/cli/README.md)
- **`apps/desktop`**: Hosts the Electron-based desktop UI, including the main process, preload scripts, and React renderer located in `apps/desktop/src/main/`
- **`packages/ui`**: Shares reusable UI primitives for conversations, Markdown rendering, artifacts, and other front-end components across interface implementations

## Development and Documentation Support

Several additional components support development, distribution, and documentation.

### Native Extensions

The **`native`** directory contains Rust-based extensions, including the direct-peer addon for the Runtime Host and the `gitoxide` helper. These native modules provide performance-critical functionality that bridges TypeScript and system-level operations.

### Documentation and Website

The **`docs`** directory holds deep-dive architecture documents, design notes, and test contracts, while the **`website`** package builds the documentation site using Astro. These components ensure that the architecture decisions and usage patterns remain accessible to contributors and users.

## Data Flow Through the Architecture

The backend spine of Apache Maka follows a unidirectional flow that ensures clear ownership of state and execution:

```

Desktop / TUI / CLI → Runtime Host → SessionManager → AgentRun + RuntimeKernel

```

In this architecture, user interfaces communicate only with the Runtime Host, which then delegates to the SessionManager for session lifecycle management. The SessionManager coordinates with AgentRun instances and the RuntimeKernel to execute tool calls and model interactions. The Eval package operates at the same level as user interfaces, submitting experiment requests to the Runtime Host rather than directly manipulating the runtime internals.

## Working with Apache Maka Components

The following examples demonstrate how to interact with the core components from a TypeScript project.

### Initializing the Runtime Host

The Runtime Host serves as the primary entry point for backend operations:

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

// Create and start a host that owns a single state root
const host = new RuntimeHost({
  rootId: 'default',
  storagePath: './runtime.sqlite',
});
await host.start();

```

### Managing Sessions and Agent Runs

Once the host is running, create sessions and execute turns through the SessionManager:

```typescript
import { SessionManager } from '@maka/runtime';
import { ModelConnection } from '@maka/core';

// Obtain a model connection (e.g., OpenAI, local model)
const model = new ModelConnection({ apiKey: process.env.OPENAI_API_KEY });

// Create a new session
const session = await SessionManager.createSession({ model });

// Run a turn with a user prompt
const result = await session.runTurn('Summarize the Apache Maka repository');
console.log(result.output);

```

### Running Evaluation Experiments

The Eval package provides high-level abstractions for benchmarking:

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

// Define a simple experiment with one cell
const experiment = new Experiment({
  name: 'RiskAnalysis',
  cells: [{ task: 'summarize', subject: 'repo', repetitions: 1 }],
});

await experiment.run();   // Executes via the Runtime Host

```

## Summary

- **Apache Maka** organizes functionality into ten distinct packages with clear architectural boundaries.
- **`packages/core`** defines pure contracts while **`packages/storage`** handles SQLite persistence.
- **`packages/runtime`** implements execution logic including SessionManager and AgentRun, while **`packages/runtime-host`** owns the security boundary and protocol handling.
- **`packages/eval`** provides the experiment framework for benchmarking without execution authority.
- **User interfaces** span CLI (`packages/cli`), Desktop (`apps/desktop`), and shared UI components (`packages/ui`).
- **Native extensions** in the `native` directory provide Rust-based performance optimizations.
- The architecture follows a strict backend spine: interfaces → Runtime Host → SessionManager → AgentRun.

## Frequently Asked Questions

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

The Runtime Host acts as the single-owner execution authority that manages session identity, turn coordination, tool permissions, and the public protocol boundary. Located in [`packages/runtime-host/src/index.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/index.ts), this component ensures that all state modifications occur through a validated, centralized authority rather than direct manipulation of the runtime internals.

### How does Apache Maka handle persistence and state management?

State management occurs through the **`packages/storage`** layer, which provides SQLite-backed interactive runtime stores. The system maintains configuration and payload persistence through this dedicated storage package, while the Runtime Host manages the state root identity that links these stored artifacts to active sessions.

### What is the difference between packages/runtime and packages/runtime-host?

**`packages/runtime`** contains the implementation details of session management, agent runs, model adapters, and the scheduling engine, as seen in [`packages/runtime/src/agent-run.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/agent-run.ts). In contrast, **`packages/runtime-host`** serves as the security and protocol gateway that owns execution authority and exposes the public interface. The runtime-host depends on the runtime package but adds the critical ownership layer that prevents unauthorized state changes.

### How do I run evaluations using the Maka eval framework?

Import the **Experiment** class from `@maka/eval` and define experiment cells that specify tasks, subjects, and repetition counts. The Eval framework submits these experiments to the Runtime Host for execution rather than running them directly, ensuring that all evaluations benefit from the same security, logging, and recovery mechanisms as standard user sessions.