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

> Explore Apache Maka entry points: CLI, Runtime, Eval, UI, and Storage. Integrate Maka locally, programmatically, or remotely for flexible development and custom interfaces.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: how-to-guide
- Published: 2026-08-24

---

**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`](https://github.com/apache/maka/blob/main/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.

```bash

# 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`](https://github.com/apache/maka/blob/main/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.

```typescript
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`](https://github.com/apache/maka/blob/main/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.

```typescript
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`](https://github.com/apache/maka/blob/main/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.

```typescript
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`](https://github.com/apache/maka/blob/main/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.

```tsx
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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/packages/cli/src/cli.ts) for local development and manual toolchain execution
- **Runtime Library**: Programmatic API in [`packages/runtime/src/tool-runtime.ts`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/protocol.ts) for remote streaming and policy enforcement
- **Eval**: Test harness in [`packages/eval/src/runner.ts`](https://github.com/apache/maka/blob/main/packages/eval/src/runner.ts) for pre-deployment toolchain verification and metering validation
- **UI Components**: React library in [`packages/ui/src/tool-activity.tsx`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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.