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

> Set up your Apache Maka development environment quickly. Follow this guide to install dependencies, clone the repo, and launch the UI with npm commands for seamless development.

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

---

**To set up an Apache Maka development environment, install Node.js 22.19+ and npm 11, clone the repository, run `npm ci` to install workspace dependencies, then execute `npm run dev` to launch the Desktop UI with hot-module replacement.**

Apache Maka is a high-performance, agent-centric workspace built on a modular runtime host that powers a Desktop UI, TUI/CLI, and evaluation kernel. The repository uses npm workspaces to manage multiple packages including the Electron-based desktop application, core runtime, and command-line interface. This guide walks you through provisioning the toolchain, installing dependencies, and launching the appropriate client for your development workflow.

## Prerequisites

Before cloning the repository, ensure your system meets the baseline requirements defined in the root [`README.md`](https://github.com/apache/maka/blob/main/README.md).

### Node.js and npm

You need **Node.js 22.19 or higher** (the CI pipeline uses Node 24) and **npm 11** to handle the workspace structure and lockfile format. The project relies on npm workspaces to link packages under `packages/` and `apps/`.

### System Tools

- **Git** – for source control
- **ripgrep** – required by the Runtime’s `Grep` tool implementation
- **Rust 1.98+** – only necessary for Peer-enabled builds with the native addon
- **Platform-specific toolchains** – Xcode CLI tools on macOS or MSVC Build Tools on Windows if compiling the Rust peer components

## Clone and Install Dependencies

Once the toolchain is ready, clone the repository and install the exact dependency versions locked in [`package-lock.json`](https://github.com/apache/maka/blob/main/package-lock.json).

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

```

The `npm ci` command defined in the root [`package.json`](https://github.com/apache/maka/blob/main/package.json) installs all workspace packages and applies custom patches located under `patches/` (such as `patches/run+2.1.4.patch`). This ensures consistent dependency trees across the runtime, desktop, and CLI packages.

## Launch the Desktop Development Environment

The Desktop UI resides in `apps/desktop/` and consists of an Electron main process with a Vite-powered React renderer.

### Standard Desktop with Hot-Module Replacement

For active UI development with live reload, run the development script:

```bash
npm run dev

```

This command, defined in [`apps/desktop/package.json`](https://github.com/apache/maka/blob/main/apps/desktop/package.json), starts the Electron main process alongside the Vite dev server for the renderer.

### Full Pre-Build Desktop

If you need to pre-compile all workspaces before Electron starts:

```bash
npm run dev:full

```

### Peer-Enabled Desktop

For development requiring the native peer addon (Rust-based direct-peer implementation), use the peer-specific scripts:

```bash
npm run dev:peer          # HMR with native peer

npm run dev:full:peer     # Full pre-build with native peer

```

These commands trigger builds in `native/` (see [`native/README.md`](https://github.com/apache/maka/blob/main/native/README.md) for the Rust build pipeline). If you previously installed Electron with `ELECTRON_SKIP_BINARY_DOWNLOAD=1`, install the platform binary before launching:

```bash
node node_modules/electron/install.js

```

## Configure Your First Model Connection

When the Desktop UI starts for the first time, you must provision a model connection before running agents:

1. Open **Settings → Models**
2. Add an API key, local-model endpoint, or supported provider connection
3. Test the connection and set the default model

Credentials are stored in [`credential-vault.json`](https://github.com/apache/maka/blob/main/credential-vault.json) within the Electron user-data directory. According to the source code architecture, this file remains in the main process and is never exposed to the renderer, ensuring secure key management.

## Develop with the CLI and TUI

Apache Maka provides a text-based interface for headless development and automation. The CLI entry point is defined in [`packages/cli/README.md`](https://github.com/apache/maka/blob/main/packages/cli/README.md).

Compile all workspaces first, then start the TUI:

```bash
npm run build
npm run cli:dev

```

Execute a non-interactive command directly:

```bash
npm run cli:dev -- run "Summarize this repository and identify its most important risk"

```

The CLI uses the same `Maka Dev` profile as the Desktop build, ensuring consistent runtime configuration between interfaces.

## Run Tests and Verify Your Setup

Verify your environment by running the workspace-level test suites:

```bash
npm --workspace @maka/runtime run test:dist
npm --workspace @maka/eval run test:dist
npm --workspace @maka/desktop run test:dist

```

For end-to-end Desktop validation:

```bash
npm --workspace @maka/desktop run e2e
npm --workspace @maka/desktop run smoke:real-window

```

These commands are documented in the "Development and verification" section of the root README and ensure the Runtime Host, SessionManager, and AgentRun components function correctly.

## Key Source Files and Architecture

Understanding the repository layout helps navigate the codebase effectively:

- **`apps/desktop/`** – Electron main process, preload scripts, and React renderer (Desktop UI entry point)
- **`packages/runtime/`** – Core agent runtime, model adapters, and tool implementations (Runtime Host)
- **`packages/runtime-host/`** – Single-owner Runtime Host lifecycle and protocol management
- **`packages/cli/`** – TUI and non-interactive CLI implementation
- **`packages/ui/`** – Shared UI primitives including conversation views and markdown rendering
- **`packages/eval/`** – Experiment kernels, cells, attempts, and result handling
- **`native/`** – Rust source for the direct-peer native addon
- **`docs/`** – Architecture documentation including [`ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md) detailing the Desktop/TUI/CLI → Runtime Host → SessionManager → AgentRun flow
- **`patches/`** – npm dependency patches applied at install time

The architecture follows the flow: **Desktop / TUI / CLI → Runtime Host → SessionManager → AgentRun**, with parallel tracks for Model + Tool Runtime and Runtime Event Log that feed into Context, Session, and UI projections.

## Summary

- **Install prerequisites**: Node.js 22.19+, npm 11, Git, ripgrep, and optionally Rust 1.98+ for peer builds.
- **Clone and setup**: Use `git clone` followed by `npm ci` to apply locked dependencies and patches.
- **Launch Desktop**: Execute `npm run dev` for HMR or `npm run dev:peer` for native addon development.
- **Configure models**: Add API keys via Settings → Models before first use; credentials store locally in [`credential-vault.json`](https://github.com/apache/maka/blob/main/credential-vault.json).
- **Use CLI**: Run `npm run build` then `npm run cli:dev` for terminal-based development.
- **Verify**: Run workspace tests via `npm --workspace @maka/[package] run test:dist` to ensure correct setup.

## Frequently Asked Questions

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

Apache Maka requires **Node.js 22.19 or higher**, though the CI pipeline uses Node 24. The npm lockfile and workspace scripts assume npm 11. Earlier versions may fail to resolve workspaces or apply patches correctly.

### How do I fix Electron binary download issues during development?

If you installed dependencies with `ELECTRON_SKIP_BINARY_DOWNLOAD=1`, you must manually download the platform binary before launching the Desktop. Run `node node_modules/electron/install.js` to fetch the correct binary for your operating system, then execute `npm run dev` normally.

### What is the difference between `npm run dev` and `npm run dev:peer`?

**`npm run dev`** starts the standard Desktop with hot-module replacement using only Node.js and Electron. **`npm run dev:peer`** additionally compiles and loads the Rust-based native addon from `native/`, which is required for peer-to-peer networking features. Use the peer variant only when developing or testing direct-peer functionality.

### Can I use the CLI without running the Desktop application?

Yes. The CLI in `packages/cli/` operates independently using the same `Maka Dev` profile as the Desktop. After running `npm run build` to compile workspaces, use `npm run cli:dev` to start the TUI or append `-- run "prompt"` for non-interactive execution. This allows headless development and automation without launching the Electron UI.