Core Principles of Maka's Architecture: How Apache Maka Orchestrates Multi-Agent Systems

Apache Maka is built on eight immutable design principles—modular plugin-driven runtime, strict separation of concerns between host/runtime/agent, event-sourced state machines, privacy-first data workspaces, declarative capability registries, deterministic scheduling, composable runtime phases, and language-agnostic JSON APIs—that collectively enable extensible, auditable, and privacy-preserving multi-agent workflows.

Apache Maka is an open-source framework designed to orchestrate complex multi-agent workflows through a carefully architected runtime environment. Understanding the core principles of Maka's architecture is essential for developers extending the platform or integrating custom LLM providers. These principles are documented throughout the repository in files like ARCHITECTURE.md and the docs/architecture/ directory, governing everything from plugin registration to state persistence.

The Eight Core Architectural Principles

The following principles shape every component of the Apache Maka system, from the sandboxed host environment to the LLM-driven agent logic.

Modular, Plugin-Driven Runtime

The core runtime loads capabilities—tools, agents, and storage back-ends—as independent plugins. Each plugin implements a well-defined interface, allowing new functionality to be added without modifying the core engine. According to ARCHITECTURE.md, this design ensures that the runtime remains lean while supporting extensible functionality through the Capability Registry.

Separation of Concerns: Host, Runtime, and Agent

As detailed in docs/architecture/runtime-host-architecture.md, Maka enforces a strict three-layer separation:

• Host: Provides the execution sandbox (container, OS, network)
• Runtime: Coordinates the flow of messages, state, and event logs
• Agent: Contains the LLM-driven logic that decides what to do next

This separation ensures that infrastructure concerns remain isolated from business logic, enabling the same agent code to run in different sandbox environments.

Event-Sourced State Machine

All state changes are persisted as immutable events. The current view of a session is reconstructed by replaying those events, guaranteeing reproducibility and auditability. The docs/architecture/runtime-core-architecture-draft.md file specifies that this pattern is implemented through the RuntimeEventStore and RuntimeReadModel classes.

Privacy-First Data Model

User data is compartmentalized into workspaces with explicit access controls. As documented in docs/workspace-privacy-context.md, the system enforces privacy boundaries at the data layer rather than just the UI layer, ensuring sensitive information remains isolated within workspace sandboxes.

Declarative Capability Registry

Capabilities are declared in a manifest (capability.yaml) that the runtime reads at start-up. This enables automatic discovery, versioning, and validation of plugins. The docs/archive/maka-capability-audit-v1-2026-05.md file describes how the CapabilityRegistry validates these manifests against the runtime's security and compatibility requirements.

Deterministic Scheduling

The scheduler assigns work to agents based on a deterministic priority queue, ensuring repeatable execution order across runs. According to docs/blogs/multi-agent-scheduling.md, this principle prevents race conditions in multi-agent workflows and guarantees that identical inputs produce identical execution sequences.

Composable Runtime Phases

The runtime is split into distinct phases (ingestion, planning, execution, post-processing). Each phase can be swapped or extended, allowing experimentation without breaking the entire pipeline. The docs/work-board-phase1.md documentation explains how these phases communicate through well-defined interfaces.

Open, Language-Agnostic APIs

Communication between host, runtime, and agents happens over JSON-based messages. As noted in docs/cli-distribution.md, this design makes it easy to replace the LLM backend (OpenAI, Anthropic, Azure, etc.) without code changes, since the protocol is strictly decoupled from implementation languages.

Implementation Patterns in the Apache Maka Source Code

These architectural principles manifest in specific code patterns throughout the apache/maka repository. Below are minimal snippets illustrating how developers interact with these core concepts.

Initializing the Runtime Host

The RuntimeHost class in @maka/runtime-host abstracts the OS/container boundary, keeping the runtime completely sandboxed:

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

// Create a host that runs inside a Docker container (the default sandbox)
const host = new RuntimeHost({
  containerImage: 'apache/maka-runtime:latest',
  env: { MAKAPORT: '8080' },
});

// Initialise the host – this spins up the sandbox and loads all registered capabilities
await host.start();

Registering Capabilities via the Registry

Plugins integrate through the CapabilityRegistry using declarative manifests that specify permissions and schemas:

import { CapabilityRegistry } from '@maka/capability-registry';
import { MyTool } from './my-tool';

CapabilityRegistry.register({
  name: 'my-tool',
  version: '1.0.0',
  implementation: MyTool,
  // Declare required permissions and the data schema it consumes/produces
  permissions: ['read:workspace', 'write:log'],
});

Executing Agent Sessions

Agents interact with the runtime only through the well-defined JSON message protocol, preserving language-agnosticism:

import { AgentRun } from '@maka/agent-run';
import { OpenAIProvider } from '@maka/providers/openai';

const run = new AgentRun({
  provider: new OpenAIProvider({ apiKey: process.env.OPENAI_API_KEY! }),
  workspaceId: 'ws-1234',
});

await run.execute();   // Orchestrates ingestion → planning → execution phases

Reconstructing State from Events

The event-sourced architecture guarantees that session state can be fully reconstructed at any point by replaying events:

import { RuntimeEventStore } from '@maka/event-store';

// Pull all events for a given session
const events = await RuntimeEventStore.readRuntimeEvents({ sessionId: 'sess-5678' });

// Build the current view by replaying the events
const sessionView = RuntimeReadModel.applyEvents(events);
console.log(sessionView);

Key Architectural Documentation Files

The following files in the Apache Maka repository capture the architectural vision, implementation details, and contracts that maintain system cohesion:

• ARCHITECTURE.md — High-level description of all core principles and component interactions
• docs/architecture/runtime-host-architecture.md — Details the host sandbox, lifecycle, and communication contracts
• docs/architecture/runtime-core-architecture-draft.md — Explains the event-sourced runtime core, phases, and scheduler
• docs/workspace-privacy-context.md — Defines the privacy model and workspace isolation mechanisms
• packages/eval/README.md — Shows how the evaluation package validates architecture contracts and compliance
• packages/cli/README.md — Provides the CLI entry-point that ties together host, runtime, and agents

Summary

• Apache Maka implements a plugin-driven architecture where capabilities are loaded dynamically via the CapabilityRegistry, allowing extension without core modifications.
• The system enforces strict separation of concerns between the Host (sandbox), Runtime (coordination), and Agent (LLM logic) layers.
• Event sourcing provides immutable audit trails and reproducible state through RuntimeEventStore and RuntimeReadModel.
• Workspace-based privacy controls enforce data isolation at the storage layer, not just the application layer.
• Declarative manifests (capability.yaml) enable automatic plugin discovery, versioning, and validation.
• Deterministic scheduling and composable phases ensure repeatable, modular workflow execution.
• JSON-based APIs decouple components, enabling language-agnostic integration and swappable LLM providers.

Frequently Asked Questions

How does Maka's plugin system work without modifying core code?

Maka uses the CapabilityRegistry class to load plugins dynamically at startup. Each plugin declares its interface, permissions, and version in a manifest file (capability.yaml), which the runtime validates and registers automatically. This allows developers to add tools, agents, or storage backends by simply placing files in the capabilities directory without touching the core engine source.

What makes Maka's state management reproducible and auditable?

The system implements an event-sourced state machine where all state changes are stored as immutable events in the RuntimeEventStore. The current session view is computed by calling RuntimeReadModel.applyEvents() to replay the event sequence. Since the event log is append-only and immutable, any past state can be reconstructed exactly, providing complete auditability and debugging capabilities.

How does Maka enforce privacy boundaries between different users or teams?

Maka implements a privacy-first data model that compartmentalizes data into isolated workspaces. As documented in docs/workspace-privacy-context.md, access controls are enforced at the data layer, meaning the runtime validates workspace permissions before any data read or write operation. This ensures that agents and tools operating in one workspace cannot access data from another, regardless of UI configurations.

Can I use Maka with LLM providers other than OpenAI?

Yes. The language-agnostic API principle ensures that all communication between components uses JSON messages. The AgentRun class accepts any provider implementing the standard interface, such as OpenAIProvider, AnthropicProvider, or AzureProvider. Because the protocol is decoupled from the implementation, switching LLM backends requires only configuration changes, not code modifications.

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