# System Requirements for Apache Maka: Complete Installation Prerequisites

> Discover the essential system requirements for Apache Maka. Ensure Node.js 22.19+, npm 11, Git, and ripgrep are installed, with macOS arm64 as the main platform.

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

---

**To build and run Apache Maka, you need Node.js 22.19 or newer, npm 11, Git, and ripgrep installed on your system, with macOS arm64 serving as the primary supported platform.**

Apache Maka is a **local-first AI-agent workspace** designed to run entirely on a developer's machine. Before installing this open-source tool from the `apache/maka` repository, you must ensure your environment meets the specific system requirements for Apache Maka outlined in the project's [`README.md`](https://github.com/apache/maka/blob/main/README.md) and configuration files.

## Core System Requirements

### Node.js Runtime and Package Manager

According to [`README.md`](https://github.com/apache/maka/blob/main/README.md) lines 105-109, Apache Maka requires **Node.js version 22.19 or newer**. The continuous integration pipeline actually uses Node 24, making that version the de facto standard for stability. You also need **npm 11**, as the [`package-lock.json`](https://github.com/apache/maka/blob/main/package-lock.json) and installation scripts assume npm-specific behavior locked in the engines field of [`package.json`](https://github.com/apache/maka/blob/main/package.json).

### Essential System Tools

The workspace depends on several command-line utilities that must be available in your system `PATH`:

- **Git**: Required for cloning the repository and for work-tree based operations performed by the runtime host (as noted in [`README.md`](https://github.com/apache/maka/blob/main/README.md) lines 109-110).
- **ripgrep (`rg`)**: Used by the built-in Grep tool for fast file searching (documented in [`README.md`](https://github.com/apache/maka/blob/main/README.md) lines 110-111).

### Operating System Compatibility

As documented in [`README.md`](https://github.com/apache/maka/blob/main/README.md) lines 30-33, **macOS arm64 (Apple Silicon)** is the primary target platform for Apache Maka. Windows support exists as an **unsigned preview** with limited stability guarantees, while **Linux support is not yet released**. While the project can technically compile on other platforms, official builds and comprehensive testing focus on Apple Silicon Macs.

## Optional Prerequisites for Native Builds

### Rust Toolchain for Peer-Enabled Features

If you plan to build the **native peer addon**, you need **Rust 1.98 or newer** plus a platform-specific linker. On macOS, this requires the Xcode Command Line Tools; on Windows, you need MSVC Build Tools. These dependencies are only necessary when using the peer entry points flagged as optional in [`README.md`](https://github.com/apache/maka/blob/main/README.md) lines 127-129.

## Verifying Your Environment

Before cloning the repository, confirm your tools meet the minimum versions specified in the [`package.json`](https://github.com/apache/maka/blob/main/package.json) engines field.

Check your current toolchain:

```bash

# Verify Node.js version (must be >= 22.19)

node -v

# Check npm version (expects 11.x)

npm -v

# Confirm ripgrep installation

rg --version

# Validate Git installation

git --version

```

## Installing Apache Maka

Once you verify the system requirements for Apache Maka, install the project using npm's clean install method to respect the exact dependency tree defined in the lockfile.

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

```

The `npm run dev` command launches the Electron-React desktop UI with hot-module reload enabled, creating the local-first workspace environment described in [`ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md).

## Building the Native Peer Addon (Optional)

For developers requiring peer-to-peer functionality, compile the native addon using the Rust toolchain:

```bash

# Install Rust 1.98+ if not present

rustup install stable
rustup default stable

# Build with peer support

npm run dev:peer

```

This produces a native addon integrated with the runtime host's sandbox boundaries defined in [`packages/runtime/src/sandbox-boundary-declaration.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/sandbox-boundary-declaration.ts).

## Summary

- Apache Maka requires **Node.js 22.19+** and **npm 11** as specified in [`README.md`](https://github.com/apache/maka/blob/main/README.md) and [`package.json`](https://github.com/apache/maka/blob/main/package.json).
- **Git** and **ripgrep** must be installed and available in your system `PATH` for core functionality.
- **macOS arm64** is the officially supported platform; Windows is available as an unsigned preview only.
- **Rust 1.98+** is only required when building the optional native peer addon.
- The runtime environment constraints are enforced through [`packages/runtime/src/sandbox-boundary-declaration.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/sandbox-boundary-declaration.ts), which declares filesystem boundaries for secure command execution.

## Frequently Asked Questions

### What version of Node.js is required for Apache Maka?

Apache Maka requires Node.js version 22.19 or newer, though the CI pipeline uses Node 24 for continuous integration. You can verify your version by running `node -v` in your terminal before attempting installation.

### Is Windows supported for Apache Maka?

Windows is currently available as an unsigned preview with limited support, as documented in [`docs/windows-support.md`](https://github.com/apache/maka/blob/main/docs/windows-support.md). macOS arm64 remains the primary platform, and Linux support has not yet been released.

### Do I need Rust to run Apache Maka?

No, Rust is only required if you plan to build the native peer addon. For standard operation using `npm run dev`, only Node.js, npm, Git, and ripgrep are necessary according to the source repository documentation.

### Why is ripgrep required instead of standard grep?

The built-in Grep tool specifically relies on ripgrep (`rg`) for its performance characteristics and regex capabilities. The runtime host expects `rg` to be available in your `PATH` when executing file search operations within the sandbox environment defined in the boundary declaration files.