Apache Maka Entry Points: CLI, Runtime, and UI Integration Guide

Apache Maka exposes six distinct entry points—CLI, Runtime Library, Runtime-Host, Eval, UI Components, and Storage Layer—that enable local development, programmatic embedding, remote hosting, testing, and custom interface building.

Apache Maka is a modular, polyglot platform designed for flexible tool execution and session management. Whether you are building a local sandbox, embedding capabilities into an existing Node.js application, or connecting a remote frontend to a hosted runtime, understanding the entry points for interacting with Maka is essential to leverage the full stack. The repository at apache/maka organizes these interfaces across six purpose-built packages, each exposing a specific interaction surface for different developer workflows.

Command-Line Interface (CLI)

The CLI provides the ready-to-run maka command for terminal-based interaction, located in packages/cli/src/cli.ts. This entry point is ideal for starting local development servers, running sandboxed sessions, or executing toolchains directly from the shell without writing additional code.

# Start a development server with hot-reloading

maka start

# Run a single toolchain against a sample prompt

maka run --toolchain my-chain "Explain quantum tunnelling in simple terms"

The CLI handles environment initialization, toolchain resolution, and session lifecycle management, making it the fastest way to interact with Maka for development and debugging tasks.

Runtime Library (Node/TypeScript)

For programmatic control, the Runtime Library in packages/runtime/src/tool-runtime.ts exports the ToolRuntime class. This API allows host applications to embed a Maka session, invoke tools from the ToolCatalog, and stream output programmatically.

import { ToolRuntime } from '@apache/maka/runtime';

// Create a runtime that uses the default tool catalog
const runtime = new ToolRuntime({
  apiKey: process.env.MAKA_API_KEY,
});

// Invoke a tool and stream its output
const result = await runtime.runTool('web-search', { query: 'latest TypeScript features' });
for await (const chunk of result.output) {
  console.log(chunk);
}

The ToolRuntime constructor accepts configuration options including apiKey, while runTool() returns a ToolResult object containing the streamable output. This entry point is the primary choice for backend services that need to integrate Maka capabilities directly into their execution flow.

Runtime-Host (Data Plane)

The Runtime-Host acts as the data-plane service for remote Maka interactions, with protocol handling defined in packages/runtime-host/src/protocol.ts. It receives streamed tool output from remote runtimes, decodes protocol messages, and enforces policy before delivering data to connected clients.

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

const client = new RuntimeHostClient('wss://runtime.mycompany.com');
await client.connect();

const session = await client.startSession();
session.sendToolRequest('web-fetch', { url: 'https://example.com' });
session.on('output', data => console.log('Streamed:', data));

This entry point enables browser-based or remote Node.js clients to execute tools on a centralized runtime while maintaining a persistent WebSocket connection for real-time streaming.

Eval (Tool-chain Verification)

The Eval package provides a test harness for toolchain validation, implemented in packages/eval/src/runner.ts via the EvalRunner class. This entry point executes full-stack evaluations including policy checks, metering, and admission control against reproducible datasets before deployment.

import { EvalRunner } from '@apache/maka/eval';

const runner = new EvalRunner({
  toolchainPath: './toolchains/my-chain',
  testDataPath: './test-fixtures',
});
await runner.runAll();   // Executes admission, metering, and lifecycle tests

Use this entry point when you need automated testing of toolchain behavior, resource consumption verification, or regression testing across different Maka versions.

UI Component Library

For frontend developers, the UI Component Library in packages/ui/src/tool-activity.tsx exports React components that render Maka sessions. Components like ToolActivity and UserQuestionPrompt handle the presentation layer for tool output streaming and user input collection.

import { ToolActivity, UserQuestionPrompt } from '@apache/maka/ui';

export default function ChatPanel() {
  return (
    <div className="chat-panel">
      <ToolActivity sessionId="abc123" />
      <UserQuestionPrompt sessionId="abc123" />
    </div>
  );
}

This entry point abstracts the complexity of WebSocket management and state synchronization, allowing developers to build custom web interfaces without implementing low-level protocol handlers.

Storage Layer

The Storage Layer provides SQLite-backed persistence for operational state, workflow definitions, and archived tool results. Implemented in packages/storage/src/sqlite-storage.ts, this entry point handles session persistence, artifact storage, and historical querying capabilities.

While typically accessed indirectly through the Runtime or Runtime-Host APIs, the storage layer can be instantiated directly for custom data management scenarios requiring direct SQL access to Maka's operational database.

Summary

• CLI: Terminal-based entry point in packages/cli/src/cli.ts for local development and manual toolchain execution
• Runtime Library: Programmatic API in packages/runtime/src/tool-runtime.ts for embedding Maka sessions in Node.js applications
• Runtime-Host: Data-plane protocol handler in packages/runtime-host/src/protocol.ts for remote streaming and policy enforcement
• Eval: Test harness in packages/eval/src/runner.ts for pre-deployment toolchain verification and metering validation
• UI Components: React library in packages/ui/src/tool-activity.tsx for building custom web interfaces with built-in streaming support
• Storage Layer: SQLite persistence in packages/storage/src/sqlite-storage.ts for session state and artifact management

Frequently Asked Questions

What is the fastest way to start experimenting with Apache Maka?

The CLI entry point provides the fastest path. Install the package globally and run maka start to launch a local development server with hot-reloading, or use maka run to execute single toolchains from the terminal without writing any TypeScript code.

How do I integrate Maka into an existing Express.js application?

Use the Runtime Library. Import ToolRuntime from @apache/maka/runtime and instantiate it within your route handlers. The runTool() method returns a streamable ToolResult that you can pipe directly to HTTP responses or WebSocket connections, allowing seamless integration with existing Node.js backends.

Can I run Maka tools in a browser without exposing API keys?

Yes, by using the Runtime-Host entry point. Connect a browser-based client to a remote Runtime-Host service via WebSocket. The browser sends tool requests to the host, which manages API keys and executes the actual toolchain, streaming results back to the client without exposing credentials to the frontend.

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