How to Integrate Apache Maka with Other Systems: A Complete Developer Guide

Apache Maka integrates with external systems through its Runtime Host, a centralized authority that exposes HTTP/WebSocket RPC endpoints for session management, backend registration, and turn execution while maintaining immutable event logs.

Apache Maka is architected as a collection of composable, pure-Node packages designed for seamless integration with diverse external systems. Whether you need to integrate Apache Maka with other systems using a custom Node.js service, a Python application, or a proprietary CLI wrapper, the process centers on the Runtime Host and its SessionManager API. According to the apache/maka source code, all product shells communicate through this host to guarantee a single source of truth for workspace state.

Apache Maka Integration Architecture

The integration model relies on five core components that provide clear seams for external connectivity.

Runtime Host Authority

The Runtime Host (@maka/runtime-host) owns the execution authority and brokers the public client-protocol boundary. External systems communicate with the host via its HTTP/WebSocket RPC endpoint, implemented in packages/runtime-host/src/server/create-runtime-host.ts. This host maintains the session store, credential vault, and event log, ensuring that external clients see the same immutable state as native shells.

SessionManager and BackendRegistry

The SessionManager class in packages/runtime/src/session-manager.ts provides the public API for creating, listing, and manipulating sessions and turns. It drives the BackendRegistry, which is defined within the same file and manages model-backend factories. The registry allows dynamic registration of backends via registry.register(kind, factory), enabling integration with custom LLM providers like OpenAI, Azure, or local models.

MCP Client for Model Context Protocol

The MCP Client (packages/mcp/src/*) provides a provider-neutral implementation of the Model-Context Protocol. It handles tool discovery, output validation, and OAuth credential storage. External systems can obtain a client using createMcpClient and pass it to backends via the BackendFactoryContext.

Storage Layer

The Storage Layer (packages/storage) provides SQLite-backed persistence via FileSessionStore in packages/storage/src/file-session-store.ts. While the host automatically manages storage, custom implementations can be swapped by providing a compatible SessionStore interface.

Public API Seams

Integration must respect public seams declared in each package's package.json exports. For example, import { SessionManager } from '@maka/runtime' is the supported entry point. Direct imports of internal paths trigger ERR_PACKAGE_PATH_NOT_EXPORTED errors.

Integrating Apache Maka with External Systems

To integrate Apache Maka with other systems, follow this canonical flow implemented in the apache/maka repository:

1. Spin up a Runtime Host with a custom workspace configuration and RPC port.
2. Create a BackendRegistry and register required model backends.
3. Instantiate a SessionManager, passing the registry and a concrete storage implementation.
4. Start sessions and run turns using the manager's createSession and runTurn methods.
5. (Optional) Configure MCP clients for external model providers requiring OAuth or tool discovery.

All communication across process or network boundaries funnels through the Runtime Host's RPC layer, allowing any HTTP/WebSocket-capable language to act as a client.

Code Implementation Examples

The following examples demonstrate how to embed Maka into third-party services using source patterns from the apache/maka codebase.

Starting the Runtime Host Server

Create a host instance that exposes the RPC endpoint for external clients:

import { createRuntimeHost } from '@maka/runtime-host';
import { join } from 'node:path';

// Host configuration – use a temporary directory for the workspace
const host = await createRuntimeHost({
  workspaceRoot: join(process.cwd(), 'maka-workspace'),
  port: 3000,               // HTTP/WebSocket RPC port
});
await host.listen();        // Starts listening for external clients

Source: packages/runtime-host/src/server/create-runtime-host.ts

Registering Custom LLM Backends

Implement the AgentBackend contract and register it with the BackendRegistry:

import { BackendRegistry } from '@maka/runtime';
import { MyCustomBackend } from './my-backend';

// Create a registry and add the custom backend
const registry = new BackendRegistry();
registry.register('my-backend', async (ctx) => new MyCustomBackend(ctx));

// Export the registry for the host to consume
export { registry };

The factory receives a BackendFactoryContext containing the session ID, workspace root, and optional tool capabilities. Source: packages/runtime/src/session-manager.ts (BackendRegistry class definition).

Orchestrating Sessions via SessionManager

Use the manager API to drive conversation turns:

import { SessionManager } from '@maka/runtime';
import { FileSessionStore } from '@maka/storage';

const store = new FileSessionStore({ dbPath: './maka-workspace/runtime.sqlite' });

const manager = new SessionManager({
  store,
  backends: registry,
  newId: () => crypto.randomUUID(),
  now: () => Date.now(),
});

// Start a new session using the custom backend
const session = await manager.createSession({
  name: 'demo-session',
  backend: { kind: 'my-backend' },
  model: 'gpt-4',
  permissionMode: 'explore',
});

// Submit a user message and retrieve the assistant reply
await manager.runTurn({
  sessionId: session.id,
  messages: [{ role: 'user', content: 'Explain how to call the host API' }],
});
const output = await manager.getMessages(session.id);
console.log(output);

Source: packages/runtime/src/session-manager.ts

Using MCP Clients in Custom Backends

Inject MCP capabilities into your backend for tool discovery and OAuth handling:

import { createMcpClient } from '@maka/mcp';
import { AgentBackend, BackendFactoryContext } from '@maka/core/backend-types';

export class MyCustomBackend implements AgentBackend {
  private readonly mcp;

  constructor(private readonly ctx: BackendFactoryContext) {
    // Initialise the MCP client with the host's OAuth configuration
    this.mcp = createMcpClient({
      oauth: ctx.oauth,
      toolDiscovery: ctx.toolDiscovery,
    });
  }

  async callModel(request) {
    // Forward the request to the model via MCP
    const response = await this.mcp.modelCall(request);
    return response;
  }
}

Source: packages/mcp/src/tool-discovery.ts

Remote Integration from Python

Connect to a running Maka host from non-Node systems using JSON-RPC:

import requests
import json

base_url = "http://localhost:3000/rpc"

def create_session():
    payload = {
        "jsonrpc": "2.0",
        "method": "sessionManager.createSession",
        "params": {
            "input": {
                "name": "py-session",
                "backend": {"kind": "my-backend"},
                "model": "gpt-4",
                "permissionMode": "explore"
            }
        },
        "id": 1
    }
    r = requests.post(base_url, json=payload)
    return r.json()["result"]

session = create_session()
print(session)

The RPC method name mirrors the exported function name on SessionManager. The host automatically maps JSON-RPC calls to the underlying TypeScript implementation.

Critical Integration Concepts

Understanding these concepts ensures robust integration with Apache Maka's security and architectural guarantees.

Backend Factory Pattern

A backend is a factory function that returns an AgentBackend instance. The factory receives a BackendFactoryContext containing the session ID, workspace root, and optional tool capabilities. This pattern allows injection of custom LLM clients or sandboxed tool sets without modifying core Maka code.

Sandbox Boundaries

SessionManager can request a sandbox boundary via createSandboxBoundaryRequest to isolate tool side-effects. External systems respect these boundaries by forwarding requests to the host, ensuring that tool execution remains contained.

Credential Security

Secrets including API keys and OAuth tokens reside in the credential vault (credential-vault.json) and are accessed only by the Runtime Host. When integrating Apache Maka with other systems, keep credentials on the host side and pass only opaque identifiers to backends via the BackendFactoryContext.

Summary

• Apache Maka exposes integration points through the Runtime Host, which centralizes session state, credentials, and the event log.
• The SessionManager class in packages/runtime/src/session-manager.ts provides the primary API for creating sessions and executing turns.
• BackendRegistry enables dynamic registration of custom LLM backends using a factory pattern that accepts BackendFactoryContext.
• The MCP Client (packages/mcp/src/*) standardizes connections to external model providers with built-in OAuth and tool discovery.
• External systems written in any language can interact with Maka via the host's HTTP/WebSocket RPC endpoint, which maps to SessionManager methods.
• Integration must respect public API seams defined in package.json exports to avoid ERR_PACKAGE_PATH_NOT_EXPORTED errors.

Frequently Asked Questions

Can I integrate Apache Maka with Python applications?

Yes. While Maka is built in TypeScript, the Runtime Host exposes a JSON-RPC over HTTP/WebSocket interface that any language can consume. Python clients can send standard HTTP POST requests to the host's RPC endpoint (e.g., http://localhost:3000/rpc) using method names that mirror the SessionManager API, such as sessionManager.createSession and sessionManager.runTurn.

How do I add a custom LLM backend to Maka?

Create a class implementing the AgentBackend interface and register it with the BackendRegistry using registry.register(kind, factory). The factory function receives a BackendFactoryContext containing session metadata and tool capabilities. This registration pattern is defined in packages/runtime/src/session-manager.ts and allows seamless integration of proprietary or local models.

Where are API credentials stored when integrating Maka?

API keys and OAuth tokens are stored exclusively in the credential vault (credential-vault.json) on the Runtime Host. They are never exposed to renderers or external clients. When building integrations, provide credentials to the host configuration only, and reference them by opaque identifiers in backend factory contexts.

Is the Runtime Host required for all integrations?

Yes. The Runtime Host is the single authority that owns session identity, agent lifecycles, and the event log. All product shells—including custom integrations—must invoke Maka through this host rather than instantiating their own runtime. This architecture guarantees a single source of truth for workspace state and enables cross-process communication via the RPC layer.

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