# Apache Maka APIs: Complete Reference for the Modular Runtime

> Explore Apache Maka's eight core public APIs including Runtime Host bridge, SessionManager, Model Provider, Tool contracts, SQLite Storage, CLI, React UI, and Peer-Mesh networking. Discover the modular runtime's capabilities.

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

---

**Apache Maka exposes eight distinct public APIs—including a Runtime Host bridge, SessionManager façade, Model Provider interfaces, Tool contracts, SQLite Storage layer, CLI commands, React UI components, and Peer-Mesh networking—all explicitly exported through TypeScript declarations and package.json exports fields.**

Apache Maka is built as a **modular, multi-package TypeScript monorepo** where every public surface is strictly defined. Each package declares its consumer-facing entry points in the `exports` field of its [`package.json`](https://github.com/apache/maka/blob/main/package.json), ensuring type-safe access to runtime operations, model providers, and client interfaces.

## Core Runtime APIs

The foundation of Apache Maka consists of two primary APIs that manage the relationship between the host environment and session execution.

### Runtime Host API

The **Runtime Host API** (`@maka/runtime-host`) provides a sandboxed bridge between the Electron renderer and the underlying Runtime Host. Implemented in [`packages/runtime-host/src/preload/preload.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/preload/preload.ts), this API exposes methods via `window.maka.*` for creating sessions, sending messages, and subscribing to runtime events. It ensures secure isolation between the UI layer and the core runtime while enabling bidirectional communication.

### SessionManager API

The **SessionManager API** (`@maka/runtime`) serves as the public façade for all runtime operations. Defined in [`packages/runtime/src/session-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts) and re-exported via [`packages/runtime/src/index.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/index.ts), this API creates `SessionManager` instances that own sessions, queue turns, and stream `RuntimeEvent` objects. All UI clients—including Desktop, TUI, and CLI—interact with the runtime exclusively through this interface, making it the central entry point for session lifecycle management.

## Model and Tool Integration

Apache Maka abstracts third-party LLM providers and tool execution through standardized interfaces that enable pluggable model support and extensible tool calling.

### Model Provider APIs

The **Model Provider APIs** (`@maka/mcp`) wrap third-party LLM services such as OpenAI, Anthropic, and Google Gemini. Each provider implements the common `ModelProvider` interface defined in the package, exposing `chat`, `embed`, `complete`, and streaming methods. Provider implementations reside in files like [`packages/mcp/src/provider-openai.ts`](https://github.com/apache/maka/blob/main/packages/mcp/src/provider-openai.ts) and [`provider-anthropic.ts`](https://github.com/apache/maka/blob/main/provider-anthropic.ts), offering consistent access to diverse model backends through a unified contract.

### Tool APIs

**Tool APIs** define the contracts for model-invoked functions used during runtime execution. Located in `packages/runtime/src/tool-*.ts` (e.g., [`tool-format.ts`](https://github.com/apache/maka/blob/main/tool-format.ts), [`tool-output-stream.ts`](https://github.com/apache/maka/blob/main/tool-output-stream.ts)) and augmented by `@maka/computer-use`, these APIs specify how tools are discovered via the `ToolRegistry` and invoked through the `RuntimeKernel`. The Computer-Use package adds a dedicated backend protocol ([`maka-cu-protocol.ts`](https://github.com/apache/maka/blob/main/maka-cu-protocol.ts)) for specialized tool execution environments.

## Infrastructure and Storage

Persistent state management and distributed networking capabilities are exposed through dedicated infrastructure APIs.

### Storage API

The **Storage API** (`@maka/storage`) provides a thin wrapper around SQLite databases for persisting runtime state. Implemented in [`packages/storage/src/sqlite-store.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/sqlite-store.ts), this API manages `runtime.sqlite` files, connection catalogs, credential vaults, and persisted artifacts. Key methods include `open`, `query`, `transaction`, and migration helpers, offering transactional integrity for workspace data.

### Peer-Mesh API

The **Peer-Mesh API** (`@maka/peer-mesh`) enables direct-peer networking between multiple Runtime Hosts. Exported from [`packages/peer-mesh/src/peer-mesh.ts`](https://github.com/apache/maka/blob/main/packages/peer-mesh/src/peer-mesh.ts), it provides `connect`, `broadcast`, and `joinRoom` primitives for distributed execution scenarios, allowing multiple Maka instances to coordinate across network boundaries without centralized infrastructure.

## Client Interfaces

Apache Maka provides distinct APIs for command-line and graphical interface development, both consuming the same underlying runtime façade.

### CLI API

The **CLI API** (`@maka/cli`) offers a command-line interface entry point defined in [`packages/cli/src/cli.ts`](https://github.com/apache/maka/blob/main/packages/cli/src/cli.ts). Invoked as the `maka` command (or `npm run cli:dev` during development), it parses sub-commands including `run`, `graph`, `export`, and `import`, forwarding all operations to the same `SessionManager` façade used by graphical clients. This ensures behavioral parity between terminal and desktop interfaces.

### UI Component API

The **UI Component API** (`@maka/ui`) exposes React components and utility hooks through a barrel export in [`packages/ui/src/index.ts`](https://github.com/apache/maka/blob/main/packages/ui/src/index.ts). Public exports include components like `ChatView` and hooks such as `useChatScroll` and `useComposerHistory`. The API is deliberately scoped to cross-package consumers, with internal components kept private to maintain encapsulation.

## Implementation Examples

### Using the SessionManager API

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

// Create a new session (default workspace)
const manager = await SessionManager.create({
  workspacePath: '/tmp/maka-workspace',
});

// Send a user message and receive a streamed turn
const turn = manager.startTurn({
  role: 'user',
  content: 'Summarize the Apache Maka repository.',
});

for await (const event of turn.events) {
  console.log(event); // RuntimeEvent objects (model output, tool calls, etc.)
}

```

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

### Accessing the Runtime Host Bridge

```typescript
// In a React component running inside the Electron renderer
window.maka.createSession({ workspace: 'default' })
  .then(session => {
    return session.sendMessage({ role: 'user', content: 'List the public APIs.' });
  })
  .then(events => {
    // `events` is an async iterator of RuntimeEvent objects
    for await (const ev of events) {
      console.log(ev);
    }
  });

```

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

### Invoking a Model Provider Directly

```typescript
import { OpenAIProvider } from '@maka/mcp';

// Initialise provider with an API key (stored in the local credential vault)
const provider = new OpenAIProvider({ apiKey: 'sk-…' });

const response = await provider.chat({
  model: 'gpt-4o-mini',
  messages: [{ role: 'user', content: 'Explain the purpose of the CLI API.' }],
});

console.log(response.choices[0].message.content);

```

*Source:* [`packages/mcp/src/provider-openai.ts`](https://github.com/apache/maka/blob/main/packages/mcp/src/provider-openai.ts)

### Storing Artifacts with the Storage API

```typescript
import { SQLiteStore } from '@maka/storage';

const store = await SQLiteStore.open('/path/to/workspace/runtime.sqlite');

// Insert an artifact
await store.run(`
  INSERT INTO artifacts (id, type, payload)
  VALUES (?, ?, ?)
`, ['artifact-123', 'json', JSON.stringify({ foo: 'bar' })]);

```

*Source:* [`packages/storage/src/sqlite-store.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/sqlite-store.ts)

### Using UI Components in React

```tsx
import { ChatView, useComposerHistory } from '@maka/ui';

export function MyChat() {
  const { history, addMessage } = useComposerHistory();

  return (
    <ChatView
      messages={history}
      onSend={msg => addMessage({ role: 'user', content: msg })}
    />
  );
}

```

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

## Summary

- **Runtime Host API**: Exposes `window.maka.*` bridge in [`packages/runtime-host/src/preload/preload.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/preload/preload.ts) for Electron renderer communication.
- **SessionManager API**: Central façade in [`packages/runtime/src/session-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts) for session lifecycle and event streaming.
- **Model Provider APIs**: Unified interface in `@maka/mcp` for OpenAI, Anthropic, and Gemini integrations.
- **Tool APIs**: Registry and kernel execution contracts in `packages/runtime/src/tool-*.ts` and Computer-Use protocols.
- **Storage API**: SQLite persistence layer in [`packages/storage/src/sqlite-store.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/sqlite-store.ts) with transactional support.
- **CLI API**: Command-line interface in [`packages/cli/src/cli.ts`](https://github.com/apache/maka/blob/main/packages/cli/src/cli.ts) proxying to SessionManager.
- **UI Component API**: React library in [`packages/ui/src/index.ts`](https://github.com/apache/maka/blob/main/packages/ui/src/index.ts) exporting `ChatView` and interaction hooks.
- **Peer-Mesh API**: Distributed networking primitives in [`packages/peer-mesh/src/peer-mesh.ts`](https://github.com/apache/maka/blob/main/packages/peer-mesh/src/peer-mesh.ts).

## Frequently Asked Questions

### How do I access Apache Maka APIs from a desktop application?

Desktop applications access the Runtime Host API through the `window.maka` object exposed by the Electron preload script in [`packages/runtime-host/src/preload/preload.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/preload/preload.ts). This bridge provides methods like `createSession` and `sendMessage` that communicate with the underlying SessionManager while maintaining process isolation between the renderer and main threads.

### What is the primary entry point for runtime operations?

The **SessionManager** class, exported from `@maka/runtime` via [`packages/runtime/src/session-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts), serves as the sole public façade for runtime operations. All clients—including CLI, TUI, and Desktop—must instantiate a `SessionManager` using `SessionManager.create()` to initiate sessions, queue turns, and subscribe to `RuntimeEvent` streams.

### Are Apache Maka APIs type-safe?

Yes. All Apache Maka APIs ship with full TypeScript declarations. The repository uses [`package.json`](https://github.com/apache/maka/blob/main/package.json) `exports` fields to explicitly define public entry points, preventing accidental imports of internal modules. This ensures compile-time verification of method signatures, event types, and provider interfaces across the monorepo.

### How does Apache Maka handle persistent storage?

The Storage API (`@maka/storage`) wraps SQLite databases through the `SQLiteStore` class in [`packages/storage/src/sqlite-store.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/sqlite-store.ts). It provides methods for `open`, `query`, and `transaction` operations, storing data in `runtime.sqlite` files alongside workspace directories. This API manages everything from runtime state to encrypted credential vaults and serialized artifacts.