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

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.

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

The npm ci command defined in the root 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:

npm run dev

This command, defined in 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:

npm run dev:full

Peer-Enabled Desktop

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

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 for the Rust build pipeline). If you previously installed Electron with ELECTRON_SKIP_BINARY_DOWNLOAD=1, install the platform binary before launching:

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

Compile all workspaces first, then start the TUI:

npm run build
npm run cli:dev

Execute a non-interactive command directly:

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:

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:

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

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