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

> Set up your Apache Maka development environment quickly. Follow our guide to install Node.js, clone the repo, install dependencies, and launch your client or CLI in minutes.

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

---

**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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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:

```bash
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`](https://github.com/apache/maka/blob/main/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:

```bash
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:

```bash
npm run dev:peer

```

For a complete build including the native addon:

```bash
npm run dev:full:peer

```

### CLI/TUI Development

To run the terminal interface from source:

```bash
npm run cli:dev

```

Execute a single agent turn directly from the command line:

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

```

All development commands are defined in [`package.json`](https://github.com/apache/maka/blob/main/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:

```bash

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

```bash
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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md) at the repository root.