Apache Maka Entry Points: 6 Ways to Drive the Runtime Host

Apache Maka exposes six stable entry points—Desktop UI, Terminal UI, CLI, headless Runtime Host, Direct-Peer Native Addon, and public npm package—all of which funnel into the centralized Runtime Host that orchestrates sessions, models, and tool execution.

Apache Maka provides multiple interfaces for users and programs to interact with its AI orchestration engine. Whether you prefer a graphical desktop environment, terminal workflows, or programmatic integration, each Apache Maka entry point ultimately delegates to the same core Runtime Host and SessionManager architecture implemented in the apache/maka repository.

Desktop UI (Electron Application)

The Desktop UI delivers a full-screen Electron application with a React renderer for graphical interaction with the system.

Starting the Desktop Application

Launch the development build using npm scripts from the repository root:

# Standard hot-reload build

npm run dev

# Build with native peer addon for high-performance filesystem operations

npm run dev:peer

The dev:peer variant compiles and loads the Rust-based Direct-Peer Native Addon automatically, enabling fast git and filesystem operations.

Architecture and Source Files

In apps/desktop/main.ts, the Electron main process bootstraps the renderer window and establishes communication with the Runtime Host via the preload bridge. This entry point displays live sessions, model output streams, and tool execution results through the React frontend, while delegating all business logic to the underlying host process.

Terminal UI and Interactive CLI

For terminal-centric workflows, Apache Maka provides a text-based user interface (TUI) and command-line interface that support both interactive and scripted usage.

Interactive TUI Mode

Start the curses-based terminal interface to monitor live logs and trigger graph-mode runs interactively:

npm run build
npm run cli:dev

The entry point at packages/cli/src/cli.ts implements the interactive shell, parsing user input and rendering the TUI while maintaining a connection to the Runtime Host.

Non-Interactive CLI Commands

Execute single "turns" without opening an interactive UI, useful for CI/CD pipelines and scripting:

# Single prompt execution

npm run cli:dev -- run "Summarize the Apache Maka architecture"

# Graph-mode execution (waits for durable graph completion)

npm run cli:dev -- run --graph "Explain entry points"

Both interactive and non-interactive modes share the same source file (packages/cli/src/cli.ts) but branch based on argument parsing to either launch the TUI or execute immediate commands.

Runtime Host Core Service

The Runtime Host serves as the universal backend for all entry points, managing the lifetime of sessions, SQLite event logging, and coordination between SessionManager, AgentRun, and tool adapters.

Headless Operation

Start the Runtime Host directly without any UI layer for service-based deployments or programmatic integration:

node packages/runtime-host/src/index.js

This entry point at packages/runtime-host/src/index.ts initializes the core service and exposes the internal API that Desktop, CLI, and peer-enabled variants consume.

Session Management Convergence

Regardless of which entry point you choose, all interactions ultimately route through the SessionManager defined in packages/runtime/src/session-manager.ts. According to the Apache Maka architecture documentation, this is the stable product entry point that abstracts model providers, tool loops, and provider-specific implementations, ensuring consistent behavior across all interfaces.

Direct-Peer Native Addon (Rust)

The Direct-Peer Native Addon provides a high-performance Rust bridge for operations requiring native system performance. Located in native/src/lib.rs, this entry point loads automatically when using peer-enabled variants such as npm run dev:peer.

This addon supports the "direct-peer" protocol and accelerates filesystem and git operations that would otherwise execute through slower JavaScript/abstraction layers.

Public npm CLI Package

Downstream users can install Apache Maka as a global CLI tool without cloning the source repository:

npm i -g @apache/maka
maka --help

As documented in packages/cli/README.md, this distribution packages the same TUI and CLI capabilities available in the monorepo, providing the maka command globally while maintaining parity with the npm run cli:dev workflow.

Summary

• Desktop UI: Electron-based graphical interface in apps/desktop/main.ts, started via npm run dev or npm run dev:peer
• Terminal/Interactive CLI: Text-based UI in packages/cli/src/cli.ts, launched with npm run cli:dev
• Non-Interactive CLI: Scriptable single-turn execution using npm run cli:dev -- run [command]
• Runtime Host: Headless core service at packages/runtime-host/src/index.ts, manageable via direct Node.js execution
• Direct-Peer Addon: Rust native extension in native/src/lib.rs for high-performance operations, auto-loaded with peer-enabled entry points
• Public npm Package: Global CLI distribution @apache/maka for end-user installation

Frequently Asked Questions

What is the main entry point for Apache Maka sessions?

The SessionManager class in packages/runtime/src/session-manager.ts serves as the primary stable entry point for all sessions. While users interact through Desktop, CLI, or other interfaces, every operation converes on this module, which hides implementation details of specific model providers and tool loops.

How do I run Apache Maka without the graphical interface?

Use the Terminal UI by running npm run cli:dev for interactive use, or execute single commands with npm run cli:dev -- run "your prompt". For completely headless operation, start the Runtime Host directly via node packages/runtime-host/src/index.js.

What is the difference between npm run dev and npm run dev:peer?

The dev:peer command builds and loads the Direct-Peer Native Addon (Rust), which provides high-performance filesystem and git operations through the native bridge in native/src/lib.rs. The standard dev command runs without this native component, using pure JavaScript implementations instead.

Can I install Apache Maka as a global command-line tool?

Yes. After running npm i -g @apache/maka, the maka command becomes available globally. This package, documented in packages/cli/README.md, provides the same TUI and CLI functionality as the development repository without requiring a local source checkout.

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