# How to Integrate Apache Maka with Other Systems: A Complete Developer Guide > Learn how to integrate Apache Maka with other systems using its Runtime Host for seamless session management backend registration and turn execution. Master Apache Maka integration today. - Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka) - Tags: how-to-guide - Published: 2026-09-13 --- **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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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: ```typescript 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`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/create-runtime-host.ts) ### Registering Custom LLM Backends Implement the `AgentBackend` contract and register it with the `BackendRegistry`: ```typescript 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`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts) (BackendRegistry class definition). ### Orchestrating Sessions via SessionManager Use the manager API to drive conversation turns: ```typescript 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`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts) ### Using MCP Clients in Custom Backends Inject MCP capabilities into your backend for tool discovery and OAuth handling: ```typescript 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`](https://github.com/apache/maka/blob/main/packages/mcp/src/tool-discovery.ts) ### Remote Integration from Python Connect to a running Maka host from non-Node systems using JSON-RPC: ```python 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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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.