System Requirements for Apache Maka: Complete Installation Prerequisites

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 and configuration files.

Core System Requirements

Node.js Runtime and Package Manager

According to 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 and installation scripts assume npm-specific behavior locked in the engines field of 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 lines 109-110).
• ripgrep (rg): Used by the built-in Grep tool for fast file searching (documented in README.md lines 110-111).

Operating System Compatibility

As documented in 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 lines 127-129.

Verifying Your Environment

Before cloning the repository, confirm your tools meet the minimum versions specified in the package.json engines field.

Check your current toolchain:

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

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.

Building the Native Peer Addon (Optional)

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

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

Summary

• Apache Maka requires Node.js 22.19+ and npm 11 as specified in README.md and 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, 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. 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.

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