# Prerequisites for Running Apache Maka: Complete Setup Guide

> Discover the essential prerequisites for running Apache Maka. Install Node.js 22.19+, npm 11, Git, and ripgrep for a smooth setup. Learn about optional Rust requirements.

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

---

**To run Apache Maka, you need Node.js 22.19 or newer, npm 11, Git, and ripgrep installed on your system; optional Rust 1.98+ is required only for peer-enabled builds.**

Apache Maka is a multi-workspace agent platform that requires specific development tools to compile its TypeScript workspaces and execute its Runtime Host. The prerequisites for running Apache Maka are strictly defined in the repository's [`README.md`](https://github.com/apache/maka/blob/main/README.md) and enforced by the monorepo's build scripts.

## Core Prerequisites

The following tools constitute the minimum set required before any `npm` command will succeed. These dependencies support the Desktop UI, TUI, CLI components, and the built-in tool chain.

### Node.js and npm Requirements

You must install **Node.js 22.19 or newer** to run Apache Maka. The continuous integration pipeline uses Node 24, and the entire codebase relies on ES 2023 language features that require a recent runtime. The [`tsconfig.base.json`](https://github.com/apache/maka/blob/main/tsconfig.base.json) file configures the TypeScript compiler target to utilize these modern JavaScript capabilities.

Additionally, you need **npm 11** specifically. The monorepo uses npm workspaces and a [`package-lock.json`](https://github.com/apache/maka/blob/main/package-lock.json) generated by npm 11. Build scripts such as `npm ci` and `npm run dev` expect npm 11 semantics to resolve dependencies correctly across the workspace hierarchy defined in [`package.json`](https://github.com/apache/maka/blob/main/package.json).

### Version Control and Search Tools

**Git** is mandatory for cloning the repository and handling workspace layout. The source checkout process relies on Git for version control and potential sub-module handling.

You must also install **ripgrep** (the `rg` binary). The Runtime's `Grep` tool shells out to ripgrep for fast, recursive text searching, as seen in utilities like `scripts/verify-linux.mjs`. You can install it via Homebrew on macOS:

```bash
brew install ripgrep

```

Or on Ubuntu/Debian:

```bash
sudo apt-get install ripgrep

```

## Optional Prerequisites for Peer-Enabled Builds

If you intend to run the peer-mesh runtime with direct-peer capabilities, you need additional tooling.

### Rust Toolchain

Install **Rust 1.98 or newer** to compile the direct-peer native addon and the `gitoxide` helper. These components are written in Rust and are only compiled when you enable peer features using scripts like `npm run dev:peer`. Install Rust using:

```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

```

### Platform Linkers

You need a platform-specific linker to compile native Rust addons. macOS requires the **Xcode Command Line Tools**, while Windows requires **MSVC Build Tools**. These provide the necessary compilers and libraries for building platform-specific binary modules.

## Installation and Verification

Once you have installed the core prerequisites, execute these commands to set up the development environment. First, clone the repository and install dependencies:

```bash

# Clone the repository

git clone https://github.com/apache/maka.git
cd maka

# Install exact dependencies (requires npm 11)

npm ci

```

Then build and run the application:

```bash

# Build every workspace (type-checking, compilation)

npm run build

# Start the Desktop development environment with hot-module-replacement

npm run dev

```

For peer-enabled builds, use the peer-specific scripts after installing Rust:

```bash

# HMR with peer addon

npm run dev:peer

# Full production-style build

npm run dev:full:peer

```

## Why Each Prerequisite Is Required

The prerequisite list is documented in multiple locations to ensure consistency across documentation and code. The [`README.md`](https://github.com/apache/maka/blob/main/README.md) file contains the authoritative requirements in the *Build from source* and *Requirements* sections. The same list surfaces in the website UI through [`website/src/copy/en.ts`](https://github.com/apache/maka/blob/main/website/src/copy/en.ts), specifically in the downloads source prerequisites section (lines 122-130), which states: "Node.js 22.19 or newer, npm 11, Git, ripgrep, which the Grep tool shells out to."

The [`package.json`](https://github.com/apache/maka/blob/main/package.json) at the repository root declares the monorepo's npm workspaces and enforces the npm 11 requirement through its lockfile format. Without ripgrep on your `PATH`, internal scripts and the Runtime Host's `Grep` tool will fail, as demonstrated in `scripts/verify-linux.mjs` where the tool invokes the binary directly.

## Summary

- **Node.js 22.19+ and npm 11** are mandatory for compiling TypeScript and managing the monorepo workspaces.
- **Git and ripgrep** must be available on your `PATH` for version control and Runtime tool execution.
- **Rust 1.98+ and platform linkers** are only needed for peer-enabled builds using `npm run dev:peer`.
- All prerequisites are verified through build scripts defined in [`package.json`](https://github.com/apache/maka/blob/main/package.json) and documented in [`README.md`](https://github.com/apache/maka/blob/main/README.md) and [`website/src/copy/en.ts`](https://github.com/apache/maka/blob/main/website/src/copy/en.ts).

## Frequently Asked Questions

### Do I need Rust to run the basic Apache Maka Desktop application?

No. Rust 1.98 or newer is only required if you are building the peer-enabled runtime with `npm run dev:peer` or `npm run dev:full:peer`. The standard Desktop, TUI, and CLI workspaces compile and run without Rust using only Node.js, npm, Git, and ripgrep according to the [`README.md`](https://github.com/apache/maka/blob/main/README.md) requirements section.

### Why does Apache Maka require npm 11 specifically?

The monorepo relies on npm workspaces and a [`package-lock.json`](https://github.com/apache/maka/blob/main/package-lock.json) lockfile generated by npm 11. The package resolution semantics and workspace handling in npm 11 are required for scripts like `npm ci` and `npm run dev` to function correctly across the repository's multiple packages.

### What happens if ripgrep is not installed?

The Runtime Host's `Grep` tool will fail to execute. This tool shells out to the `rg` binary for fast text searching, and several internal scripts (such as `scripts/verify-linux.mjs`) depend on it. You must have `ripgrep` available on your system `PATH` before starting the development server.

### Can I use a Node.js version older than 22.19?

No. The TypeScript configuration in [`tsconfig.base.json`](https://github.com/apache/maka/blob/main/tsconfig.base.json) targets ES 2023 language features that require Node.js 22.19 or newer. Older Node versions lack the necessary JavaScript runtime capabilities to execute the compiled code, particularly for the Electron-based Desktop UI and modern CLI features.