Prerequisites for Running Apache Maka: Complete Setup Guide

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 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 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 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.

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:

brew install ripgrep

Or on Ubuntu/Debian:

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:

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:

# 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:

# 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:

# 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 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, 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 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 and documented in README.md and 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 requirements section.

Why does Apache Maka require npm 11 specifically?

The monorepo relies on npm workspaces and a 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 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.

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