How to Set Up an Apache Maka Development Environment: Complete Guide

To set up an Apache Maka development environment, install Node.js ≥22.19 and npm 11, clone the repository, run npm ci to install dependencies, and launch your target client using npm run dev for Desktop or npm run cli:dev for the CLI.

Apache Maka is a multi-client agent workspace that routes all work through a single Runtime Host. Developing against the codebase requires specific toolchain versions and monorepo commands defined in the package.json file. This guide covers the complete setup process from prerequisites to running your first agent turn.

Prerequisites

Before cloning the repository, ensure your system meets the toolchain requirements specified in the project documentation.

Core Toolchain

The following tools are mandatory for all development workflows:

• Node.js ≥22.19 (the CI pipeline currently uses Node 24)
• npm 11 (the lockfile expects npm 11.19.0 as specified in package.json)
• Git (any recent version)
• ripgrep (required by the Runtime Grep tool)

These requirements are documented in the README under the Requirements section and enforced via the engines field in package.json.

Optional Native Dependencies

If you plan to work with Peer-Mesh functionality or direct peer connections, you need additional tooling:

• Rust stable ≥1.98
• Platform-specific linker: Xcode Command Line Tools (macOS) or MSVC Build Tools (Windows)

These dependencies are only necessary when building the native addons located in the native/ directory, such as the peer-enabled Runtime Host and gitoxide helper.

Clone and Install

Fetch the source code and install dependencies using the exact versions locked in the repository:

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

The npm ci command is strictly preferred over npm install because it guarantees reproducible builds by installing exact versions from the lockfile. This is critical for the monorepo workspace structure defined in package.json.

Launch Development Targets

Apache Maka supports multiple client interfaces. Choose the command that matches your development focus.

Desktop (Electron) Development

For UI development with hot-module reload (HMR), which automatically refreshes code changes:

npm run dev

This command starts the Electron main process alongside the React renderer with HMR enabled. For a full build without HMR, use npm run dev:full instead.

Peer-Enabled Desktop Development

If your work involves the native peer addon, build the Rust components first:

npm run dev:peer

For a complete build including the native addon:

npm run dev:full:peer

CLI/TUI Development

To run the terminal interface from source:

npm run cli:dev

Execute a single agent turn directly from the command line:

npm run cli:dev -- run "Summarize the repository structure"

All development commands are defined in package.json under the "scripts" section.

First Run Configuration

When launching Desktop or CLI for the first time, you must configure a model provider before running tasks:

1. Open Settings → Models (or use the CLI configuration flow)
2. Add an API, local-model, or supported account connection
3. Test the connection and set it as the default model
4. Return to the workspace to begin agent execution

This configuration process is documented in the README under "First run".

Verify Your Setup

Ensure your environment is functional by compiling and testing the codebase:

# Compile all workspaces (core, storage, runtime, desktop, etc.)

npm run build

# Run unit and integration tests

npm test

# Run tests against built artifacts

npm run test:dist

For a clean verification, use:

npm run clean
npm run build
npm test

Understanding the Architecture

Familiarity with the high-level architecture helps when extending Maka. The system flows through these layers as documented in ARCHITECTURE.md:

Desktop / TUI / CLI → Runtime Host → SessionManager → AgentRun
                                            ↓
                              Model + Tool Runtime → Runtime Event Log
                                            ↓
                               Context / Session / UI projections

Key components include:

• Runtime Event Log – The canonical source of all model messages, tool calls, and results located in packages/runtime/
• SessionManager & AgentRun – Own the execution lifecycle and turn identity
• Storage – SQLite-backed operational state (no Eval authority)

Essential Development Commands

Reference these commands during daily development:

Command	Purpose
npm run build	Compile every workspace
npm run typecheck	Run TypeScript type-checking across all packages
npm run lint	Lint the repository with Biome
npm run check:release	Perform release-gate checks (deps, notices, model metadata)
npm --workspace @maka/desktop run e2e	Run end-to-end tests for the Desktop client
npm run refresh:model-metadata	Update generated model-metadata from upstream catalog

Summary

• Install Node.js ≥22.19 and npm 11 before cloning, plus Rust ≥1.98 if building peer-mesh features
• Use npm ci instead of npm install to ensure reproducible builds in the monorepo
• Launch Desktop with npm run dev (HMR) or npm run dev:peer (with native addons)
• Run CLI development mode with npm run cli:dev and execute turns with the -- run flag
• Configure a model provider on first launch via Settings → Models
• Verify your setup with npm run build followed by npm test

Frequently Asked Questions

What Node.js version is required for Apache Maka development?

Apache Maka requires Node.js ≥22.19, though the CI pipeline currently uses Node 24. The package.json explicitly defines these engine requirements, and the lockfile expects npm 11.19.0. Using older versions may cause dependency resolution failures.

Do I need to install Rust to build Apache Maka?

Rust is only required if you are developing Peer-Mesh functionality or direct peer connections. The native addons in the native/ directory require Rust ≥1.98 and platform-specific linkers (Xcode CLI tools on macOS, MSVC on Windows). For standard Desktop or CLI development, Node.js and npm are sufficient.

How do I run the CLI in development mode with a specific prompt?

Use the command npm run cli:dev -- run "Your prompt here". The double-dash (--) passes arguments to the CLI process itself, allowing you to execute single agent turns without entering interactive mode. For example: npm run cli:dev -- run "Analyze this codebase for security issues".

Where is the Runtime Host implementation located?

The Runtime Host implementation resides in packages/runtime/ and contains the core logic for SessionManager, AgentRun, and the tool runtime. The Desktop client code is located in apps/desktop/, while CLI entry points are in packages/cli/. The architecture is documented in ARCHITECTURE.md at the repository root.

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