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

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 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, the host instantiates the SessionManager and orchestrates all agent runs:

// 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, the runtime selects appropriate backends based on permission profiles:

// 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, this layer supplies experiment semantics but delegates actual execution to the Runtime Host:

// 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 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.

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