# Can Apache Maka Be Integrated with Other Systems? Technical Architecture and Implementation Guide

> Discover how Apache Maka integrates with external systems using its modular runtime host, pluggable AI, and WebSocket protocols. Learn about its technical architecture and implementation.

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

---

**Apache Maka integrates with external systems through a modular runtime host that exposes standardized capability negotiation, pluggable AI backends, and WebSocket transport protocols.**

Apache Maka is designed from the ground up as a modular, extensible AI-agent runtime capable of embedding into or communicating with diverse external platforms. According to the `apache/maka` source code, the architecture intentionally separates the core runtime from product shells (Desktop, TUI, CLI, bots), exposing well-defined integration points that treat external services as first-class clients.

## Integration Architecture Overview

The Apache Maka architecture isolates integration concerns into distinct layers. The **Runtime Host** manages public client boundaries, admission control, and secure transport via WebSocket, IPC, or peer-to-peer connections. Every product shell communicates through this same host, meaning external systems implementing the client protocol receive identical treatment—including capability negotiation and security checks—as native applications.

Key architectural components include the **Session Manager** (`SessionManager`), which orchestrates session lifecycles and tool execution, and the **Backend Registry**, which allows registration of custom AI models. These components reside in `packages/runtime/` while transport-level concerns live in `packages/runtime-host/`.

## Key Integration Points in Apache Maka

### Runtime Host and Client Capability Service

The primary integration seam resides in [`packages/runtime-host/src/server/client-capability-service.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/client-capability-service.ts). This service handles per-client capability negotiation, authentication, and scoped permission sets—critical for SaaS integrations like Slack or Microsoft Teams.

External systems connect to the **Runtime Host** and undergo admission control where the `ClientCapabilityService` validates tokens and assigns capability scopes (e.g., `chat`, `tools`). The host then manages session availability through [`host-session-availability.ts`](https://github.com/apache/maka/blob/main/host-session-availability.ts), enabling remote clients to initiate turns.

### Backend Registry for Custom AI Models

For organizations requiring custom model integration, [`packages/runtime/README.md`](https://github.com/apache/maka/blob/main/packages/runtime/README.md) documents the `BackendRegistry` API. Located conceptually within the runtime package, this registry allows developers to implement the `AgentBackend` interface and register alternative LLM providers—whether OpenAI, Azure, or self-hosted endpoints.

This pattern enables Apache Maka to route specific sessions to proprietary models while maintaining the same session orchestration and tool execution semantics.

### Tool Composition API

Apache Maka exposes functionality to external systems through the `buildBuiltinTools()` function, documented in [`packages/runtime/README.md`](https://github.com/apache/maka/blob/main/packages/runtime/README.md). This API lets integrators add custom tools—HTTP callers, file system adapters, or proprietary SDKs—that become available to any connected client.

Tools defined through this interface execute within the runtime's session turn management, ensuring consistent error handling and permission scoping.

### External Session Contracts

Third-party agents receive stable identifiers through [`packages/core/src/external-session.ts`](https://github.com/apache/maka/blob/main/packages/core/src/external-session.ts). This contract allows external platforms to plug in as "agents" within the Maka ecosystem, maintaining persistent identity across session boundaries. The `ExternalSession` type ensures that outside systems can participate in multi-turn conversations without losing context.

## Common Apache Maka Integration Patterns

**Embedding Maka in a web service** involves starting a Runtime Host within a Node.js process, exposing its WebSocket endpoint, and allowing the service to issue session turns via the public protocol. The service authenticates through the `ClientCapabilityService` and receives scoped access to tools.

**Creating platform-specific bots** (Slack, Teams) requires implementing a client that authenticates via the capability service, registers a specific capability (e.g., `slack-chat`), and forwards incoming messages to the `SessionManager`. The bot receives the same security guarantees as native desktop clients.

**Adding proprietary AI backends** entails implementing the `AgentBackend` interface and registering it with `BackendRegistry`. The runtime host routes eligible sessions to this backend while maintaining standard tool composition and session management.

## Apache Maka Integration Code Examples

### Registering a Custom Backend

Integrate proprietary LLMs by implementing the `AgentBackend` interface:

```typescript
// src/custom-backend.ts
import { AgentBackend, BackendRegistry } from '@maka/runtime';

export class MyHttpBackend implements AgentBackend {
  async generate(prompt: string): Promise<string> {
    const resp = await fetch('https://my-llm.example.com/generate', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ prompt }),
    });
    const { completion } = await resp.json();
    return completion;
  }
}

// Register at startup
BackendRegistry.register('my-http-backend', new MyHttpBackend());

```

*Source:* [`packages/runtime/src/BackendRegistry.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/BackendRegistry.ts)

### Exposing a WebSocket Client Capability

Allow external web applications to connect as first-class clients:

```typescript
import { startRuntimeHost } from '@maka/runtime-host';
import { ClientCapabilityService } from '@maka/runtime-host/src/server/client-capability-service';

const capability = {
  id: 'webapp',
  name: 'WebApp Integration',
  transport: 'websocket',
  scopes: ['chat', 'tools'],
};

startRuntimeHost({
  capabilities: [capability],
  auth: async (token) => token === process.env.WEBAPP_TOKEN,
});

```

*Source:* [`packages/runtime-host/src/server/client-capability-service.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/client-capability-service.ts)

### Building a New Tool for External Use

Extend runtime capabilities with custom tools accessible to all clients:

```typescript
import { buildBuiltinTools } from '@maka/runtime';

const httpFetchTool = {
  name: 'http-fetch',
  description: 'Perform a GET request and return the body',
  async run({ url }: { url: string }) {
    const resp = await fetch(url);
    return await resp.text();
  },
};

buildBuiltinTools([httpFetchTool]);

```

*Source:* [`packages/runtime/README.md`](https://github.com/apache/maka/blob/main/packages/runtime/README.md)

## Testing Integration Implementations

The `apache/maka` repository includes comprehensive test suites in `packages/runtime-host/src/__tests__` that verify capability negotiation, credential handling, and cross-transport tool execution. Specific files like [`runtime-resource-two-client-uds.test.ts`](https://github.com/apache/maka/blob/main/runtime-resource-two-client-uds.test.ts) demonstrate how external capabilities are exercised, providing reference implementations for production integrations.

Consult [`ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md) in the repository root for high-level diagrams of the Runtime Host, SessionManager, and integration seams.

## Summary

- Apache Maka exposes integration through the **Runtime Host**, which manages WebSocket, IPC, and peer-to-peer transport with standardized capability negotiation.
- External systems authenticate via the **ClientCapabilityService** ([`packages/runtime-host/src/server/client-capability-service.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/client-capability-service.ts)) and receive scoped permissions identical to native clients.
- Custom AI backends integrate by implementing the **AgentBackend** interface and registering with **BackendRegistry**.
- The **Tool Composition API** (`buildBuiltinTools()`) allows external systems to invoke custom tools through the session turn API.
- Stable third-party agent identities are managed through **ExternalSession** contracts in [`packages/core/src/external-session.ts`](https://github.com/apache/maka/blob/main/packages/core/src/external-session.ts).

## Frequently Asked Questions

### How does Apache Maka handle authentication for external integrations?

Apache Maka authenticates external systems through the `ClientCapabilityService`, which validates tokens during the admission phase and assigns scoped permission sets. This mechanism applies uniformly across all transport types—WebSocket, IPC, or Unix Domain Sockets—ensuring that external bots and web services receive appropriate access controls without modifying core runtime code.

### Can I use Apache Maka with my own LLM instead of commercial providers?

Yes. Implement the `AgentBackend` interface to create a custom backend adapter, then register it using `BackendRegistry.register()`. The runtime routes designated sessions to your implementation while preserving standard session management, tool execution, and capability negotiation features.

### What transport protocols does Apache Maka support for system integration?

Apache Maka supports **WebSocket** for network-based integration, **IPC** (Inter-Process Communication) for local co-location, and **peer-to-peer** transports. The Runtime Host abstracts these protocols, allowing integrators to focus on capability declarations and session management rather than transport specifics.

### Where can I find production examples of Apache Maka integrations?

Production integration patterns are demonstrated in the test suites within `packages/runtime-host/src/__tests__`, particularly files like [`runtime-resource-two-client-uds.test.ts`](https://github.com/apache/maka/blob/main/runtime-resource-two-client-uds.test.ts). These tests exercise multi-client scenarios, capability negotiation, and secure session handoff. For architectural context, consult [`ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md) and [`packages/runtime/README.md`](https://github.com/apache/maka/blob/main/packages/runtime/README.md) in the `apache/maka` repository.