# Main Backend System Components in Apache Maka: Architecture and Package Guide

> Explore Apache Maka's backend system components. Understand the Runtime Host and six specialized packages that power its core protocols, storage, scheduling, and more.

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

---

**Apache Maka's backend architecture centers on the Runtime Host as the sole execution authority, supported by six specialized packages handling core protocols, storage, scheduling, evaluation, and user interfaces.**

The Apache Maka repository implements a modular agent runtime designed for secure, reproducible AI execution. Understanding the main backend system components in Maka reveals how the platform isolates agent work, persists state, and scales evaluations across distributed environments. The architecture is documented in [`ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md) and implemented across the `packages/` directory.

## The Runtime Host: Central Execution Authority

The **Runtime Host** serves as the single execution authority in Maka's backend. Located in `packages/runtime-host`, this component owns the public client protocol, admission control, and capability negotiation.

According to the Apache Maka source code, the Runtime Host is the only component that creates and manages execution contexts. In [`packages/runtime-host/src/server/index.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/index.ts), the host instantiates the `SessionManager` and orchestrates all agent runs:

```typescript
// Runtime Host entry point (packages/runtime-host/src/server/index.ts)
import { SessionManager } from '@maka/runtime';
import { RuntimeHost } from '@maka/runtime-host';

// Create a hosted runtime and start a session
const host = new RuntimeHost();
const session = await host.createSession({ client: 'cli' });
await session.runAgent();   // invokes SessionManager → AgentRun

```

## Core Backend Packages

Maka organizes its backend into loosely-coupled packages, each owning distinct responsibilities from data persistence to agent scheduling.

### packages/core: Foundation and Protocol Definitions

The `packages/core` directory contains the pure session model, **Runtime Event Log**, `AgentRun` definitions, permission contracts, and public protocol definitions. This package provides the immutable data structures that other layers depend upon but contains no execution logic.

### packages/storage: Persistent State Management

Located in `packages/storage`, this package manages interactive runtime state persisted in **SQLite**. It provides the low-level data plane for sessions, turns, and artifacts. While the storage layer holds session transcripts and turn history, it maintains no evaluation-specific ledger, keeping concerns separated from the `eval` package.

### packages/runtime: Scheduling and Context Handling

The `packages/runtime` package implements the **Agent Graph** scheduler, model adapters, tool integration, and crash-recovery mechanisms. This layer contains the `SessionManager` and `RuntimeKernel` that execute agent work.

In [`packages/runtime/src/sandbox/sandbox-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/sandbox/sandbox-manager.ts), the runtime selects appropriate backends based on permission profiles:

```typescript
// Sandbox selection (packages/runtime/src/sandbox/sandbox-manager.ts)
import { SandboxManager } from '@maka/runtime';
import { PermissionProfile } from '@maka/core';

// Choose a backend based on a permission profile
const profile = PermissionProfile.fromJSON(json);
const backend = SandboxManager.selectBackend(profile);

```

### packages/runtime-host: Hosted Execution Service

While `packages/runtime` contains the execution engine, `packages/runtime-host` adds the hosted service layer. This distinction allows the runtime logic to remain environment-agnostic while the host handles network protocols and client admission.

## Evaluation and Interface Layers

Beyond the core execution engine, Maka provides specialized packages for benchmarking and user interaction.

### packages/eval: Experimentation Framework

The `packages/eval` package defines the evaluation framework (`@maka/eval`), including experiments, cells, attempts, result selection, and executor adapters (Harbor, Pier). Located in [`packages/eval/src/eval_framework.ts`](https://github.com/apache/maka/blob/main/packages/eval/src/eval_framework.ts), this layer supplies experiment semantics but delegates actual execution to the Runtime Host:

```typescript
// Evaluation experiment setup (packages/eval/src/eval_framework.ts)
import { Experiment } from '@maka/eval';

const exp = new Experiment({
  subjects: ['subjectA'],
  tasks: ['task1'],
  repetitions: 3,
});
await exp.run();   // delegates execution to Runtime Host

```

### packages/cli and Desktop: User Entry Points

The `packages/cli` directory provides command-line utilities including `maka run` and `maka eval`, bridging user commands to the Runtime Host. For desktop users, [`apps/desktop/src/main/index.ts`](https://github.com/apache/maka/blob/main/apps/desktop/src/main/index.ts) implements the Electron-based entry point that composes the UI with the Runtime Host via `runtime-host` APIs.

## Component Interaction Flow

The backend components follow a strict routing pattern illustrated in the architecture documentation. All execution flows through the Runtime Host:

1. **Desktop**, TUI, CLI, or Bot clients send work to the **Runtime Host**.
2. The host creates a **SessionManager** that owns session and turn identity.
3. **AgentRun** and **RuntimeKernel** execute the work within the session.
4. The **Agent Graph** schedules dependent work across child sessions, always routing through the Runtime Host.
5. All events—model messages, tool calls, tool results, and termination facts—are written to the **Runtime Event Log** provided by `packages/core`.

## Summary

- **Runtime Host** (`packages/runtime-host`) serves as the sole execution authority, managing admission, sessions, and the public protocol.
- **Core** (`packages/core`) defines the immutable session model, event log schema, and permission contracts.
- **Storage** (`packages/storage`) persists interactive state to SQLite without handling evaluation-specific data.
- **Runtime** (`packages/runtime`) implements the agent graph scheduler, sandbox management, and execution kernel.
- **Eval** (`packages/eval`) provides the experimentation framework while delegating execution to the Runtime Host.
- **CLI and Desktop** (`packages/cli`, `apps/desktop`) provide user interfaces that communicate exclusively through the Runtime Host APIs.

## Frequently Asked Questions

### What is the Runtime Host in Maka?

The Runtime Host is the single execution authority in Apache Maka's backend architecture. Implemented in `packages/runtime-host`, it owns the public client protocol, manages session admission, and coordinates all agent execution through the `SessionManager` and `AgentRun` components.

### How does Maka handle data persistence?

Maka persists interactive runtime state through the `packages/storage` package, which uses SQLite as the underlying datastore. This layer manages session transcripts, turn history, and artifacts, but deliberately excludes evaluation-specific ledgers to maintain clean separation of concerns.

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

The `packages/runtime` package contains the execution engine, including the agent graph scheduler, sandbox management, and `RuntimeKernel`. The `packages/runtime-host` package adds the hosted service layer, handling network protocols and client admission while delegating actual execution to the runtime components.

### How does the evaluation framework execute experiments?

The `packages/eval` framework defines experiment semantics including subjects, tasks, cells, and attempts. However, it does not execute code directly; instead, it delegates all execution to the Runtime Host through the `Experiment.run()` method, ensuring consistent sandboxing and logging across both interactive and batch workloads.