# How to Build Apache Maka from Source: A Complete Development Guide

> Learn how to build Apache Maka from source with this guide. Install Node 22+, clone the repo, and run npm commands to build the desktop or CLI application.

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

---

**Build Apache Maka by installing Node 22+ and npm 11, cloning the repository, running `npm ci` to bootstrap the monorepo, and executing `npm run dev` to launch the Desktop application or `npm run cli:dev` for the terminal interface.**

Apache Maka is a multi-workspace agent platform comprising a Desktop UI (Electron + React), a TUI/CLI, and a pure-Node **Runtime Host** that executes model-driven tasks. Building the project from source requires setting up a modern JavaScript toolchain and understanding the monorepo structure defined in the top-level [`package.json`](https://github.com/apache/maka/blob/main/package.json). This guide walks through the exact commands and file locations needed to compile and run every component of the system.

## Prerequisites

Before cloning the repository, ensure your environment meets the following requirements defined in [`README.md`](https://github.com/apache/maka/blob/main/README.md):

- **Node.js** ≥ 22.19 (the CI pipeline currently uses Node 24)
- **npm** 11 (required for the lockfile format)
- **Git** for version control
- **ripgrep** (`rg`) for the Runtime Host's `Grep` tool functionality
- **Rust** ≥ 1.98 and a platform linker (only required when building the peer-enabled entry point with native addons)

You can verify your Node version with `node --version` and install ripgrep via your system's package manager (e.g., `brew install ripgrep` on macOS or `apt-get install ripgrep` on Ubuntu).

## Clone and Bootstrap the Monorepo

Apache Maka uses npm workspaces to manage dependencies across `packages/` and `apps/desktop`. Begin by cloning the repository and performing a clean install:

```bash
git clone https://github.com/apache/maka.git
cd maka
npm ci

```

The `npm ci` command reads the top-level [`package-lock.json`](https://github.com/apache/maka/blob/main/package-lock.json) and installs every workspace dependency deterministically. This process sets up the shared **Runtime Host** (`packages/runtime-host`), the UI primitives (`packages/ui`), and the desktop application shell.

If you previously set `ELECTRON_SKIP_BINARY_DOWNLOAD=1` to avoid downloading pre-built Electron binaries, manually install the platform binary before launching the desktop app:

```bash
node node_modules/electron/install.js

```

## Development Workflows

The repository provides distinct development modes for the Desktop GUI, CLI/TUI, and peer-enabled builds. All commands are defined in the root [`package.json`](https://github.com/apache/maka/blob/main/package.json) and delegate to individual workspaces.

### Desktop Application (Electron)

To start the Desktop application with hot-module-replacement (HMR) for the React renderer:

```bash
npm run dev

```

For a full build of all workspaces before starting the Desktop (useful after pulling updates):

```bash
npm run dev:full

```

The Desktop entry point resides in `apps/desktop/` and communicates with the Runtime Host via inter-process communication.

### CLI and TUI

To run the command-line interface or terminal UI, first compile the workspaces, then launch the development CLI:

```bash
npm run build
npm run cli:dev

```

Execute one-shot tasks by passing arguments after the double dash:

```bash
npm run cli:dev -- run "Summarize this repository and identify architectural risks"

```

Use the `--graph` flag to request a durable graph execution in non-interactive mode.

### Peer-Enabled Builds (Rust Native Addon)

If you intend to build the **peer-enabled** version that compiles Rust native add-ons for direct-peer functionality:

```bash
npm run dev:peer       # HMR with native addon built on-the-fly

npm run dev:full:peer  # Full build of all workspaces + native addon

```

These commands invoke the Rust toolchain to compile platform-specific binaries. Ensure `cargo` is available in your PATH before running.

## Production Builds

To generate distributable artifacts like `.dmg` (macOS), `.exe` (Windows), or `.AppImage` (Linux):

```bash
npm run build
npm --workspace @maka/desktop run dist

```

The `npm run build` command compiles all TypeScript workspaces and bundles Electron assets. The distribution step uses `electron-builder` configured in `apps/desktop/electron-builder.config.mjs`, outputting installers to `apps/desktop/dist/`.

Run end-to-end tests against the production build:

```bash
npm --workspace @maka/desktop run e2e
npm --workspace @maka/desktop run smoke:real-window

```

## Architecture Overview

Understanding the build structure helps debug compilation issues. Apache Maka uses a directed execution chain:

```

Desktop / TUI / CLI → Runtime Host → SessionManager → AgentRun
                                         ↓
                          Model + Tool Runtime → RuntimeEvent Log

```

All front-ends communicate with a single **Runtime Host** (`packages/runtime-host`) that owns the execution loop. The host records every model message, tool call, and permission decision as an append-only `RuntimeEvent` log. The UI layer (`packages/ui`) merely renders projections of this immutable log, while the Desktop shell (`apps/desktop`) provides the Electron container.

## Summary

- **Install Node 22+ and npm 11** before attempting to build; Rust 1.98+ is only needed for peer-enabled features.
- **Bootstrap with `npm ci`** in the repository root to install all workspace dependencies deterministically.
- **Start development** using `npm run dev` for Desktop hot-reloading or `npm run cli:dev` for the terminal interface.
- **Build production artifacts** with `npm run build` followed by the workspace-specific `dist` command.
- **Locate key configurations** in [`package.json`](https://github.com/apache/maka/blob/main/package.json) (workspaces), `apps/desktop/electron-builder.config.mjs` (packaging), and `packages/runtime-host/` (execution engine).

## Frequently Asked Questions

### What are the minimum system requirements for building Apache Maka?

You need Node.js version 22.19 or higher and npm 11 to match the lockfile format. The build also requires Git and ripgrep (`rg`) because the Runtime Host's `Grep` tool depends on it for file searching. Rust is only necessary if you are compiling the peer-enabled native addon.

### How do I build the peer-enabled version with Rust support?

Run `npm run dev:peer` for development with hot-reload or `npm run dev:full:peer` for a complete production-like build. These commands trigger the Rust compiler for the native addon in addition to the standard TypeScript build. Ensure Rust 1.98+ and a platform linker are installed before executing these commands.

### Can I run Apache Maka without the Desktop application?

Yes. After running `npm run build` to compile the workspaces, use `npm run cli:dev` to launch the terminal interface. This provides full access to the Runtime Host and agent execution capabilities without Electron dependencies, though you lose the graphical React-based UI.

### Why does the build require ripgrep?

The Runtime Host includes a `Grep` tool that delegates to the `rg` binary for high-performance file searching. During the build process, the presence of ripgrep is assumed for both the tool's runtime functionality and certain development scripts. Install it via your system's package manager before running `npm ci`.