How to Install Apache Maka: A Step-by-Step Guide to the Modular AI Platform

To install Apache Maka, clone the monorepo repository, install workspace dependencies with npm ci, create a new workspace using the CLI tool, install desired skill packages, and launch both the runtime host and desktop UI.

Apache Maka is a modular, multi-agent AI platform built with a micro-frontend architecture that separates the core runtime, UI components, storage back-ends, and optional skill packages. Because the repository follows a monorepo layout using npm workspaces (defined in the root package.json), you can build and run each component independently or deploy the full stack together. This guide walks through the complete installation process using the source code from the official apache/maka repository.

Prerequisites

Before installing Apache Maka, ensure your environment meets the following requirements:

• Node.js version 18 or higher
• npm version 9 or higher
• A recent Git client

The platform is container-agnostic, meaning you can run the runtime on a plain Node.js process or inside a Docker container, while the desktop client runs on Electron.

Step 1: Clone and Install the Monorepo

First, obtain the full source code and install all workspace dependencies. The root package.json organizes the project into npm workspaces, allowing npm to hoist shared packages and install each module correctly.

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

This command installs dependencies for all packages in the repository, including the CLI, UI components, storage adapters, and core runtime.

Step 2: Create a New Workspace

Apache Maka uses the concept of workspaces to isolate different agent configurations. Use the CLI (located in packages/cli/) to scaffold a fresh workspace folder.

npx maka create my-workspace
cd my-workspace
npm install

The maka create command generates a new workspace directory with default configuration files, while npm install inside the workspace fetches the default skill packages required to run the runtime.

Step 3: Add Skill Packages

Maka's capabilities are extended through skill packages—individual AI capabilities packaged as npm modules that the runtime loads dynamically. For example, to enable computer control capabilities, add the computer-use package:

npm add @apache/maka-computer-use

You can install multiple skills depending on your use case. The runtime coordinates these lifecycles according to the architecture described in ARCHITECTURE.md.

Step 4: Launch the Runtime and Desktop UI

Apache Maka requires two processes running simultaneously: the headless runtime host and the desktop client.

Start the core runtime in one terminal:

npm run start:runtime

The runtime host provides the execution sandbox, message queue, and remote-access APIs. It uses a JSON-based task ledger for durable task tracking (see docs/session-task-ledger-lifecycle.md for the specification).

In another terminal, launch the desktop client:

npm run start:desktop

The desktop client (located in packages/ui/) automatically connects to the local runtime via the embedded message queue, presenting a chat-style interface where installed skills can be invoked.

Step 5: Build for Production (Optional)

To create a production build of the desktop application, navigate to the UI package and run the build command:

cd packages/ui
npm run build

This produces a bundled Electron app in the dist/ directory. You can package this further with electron-builder or deploy the static assets to any compatible host.

Summary

• Apache Maka uses an npm workspace monorepo structure managed from the root package.json.
• Installation requires Node.js ≥ 18, npm ≥ 9, and Git to clone the repository.
• Use the CLI tool (npx maka create) in packages/cli/ to scaffold isolated workspaces.
• Extend functionality by installing skill packages like @apache/maka-computer-use.
• Run the runtime host (npm run start:runtime) and desktop UI (npm run start:desktop) as separate processes.
• Production builds are generated in packages/ui/dist/ using standard npm build scripts.

Frequently Asked Questions

Do I need Docker to run Apache Maka?

No. While Apache Maka is container-agnostic and can run inside Docker, you can run the platform directly on a plain Node.js process. The runtime host executes as a standard Node.js application, and the desktop client runs on Electron without requiring containerization.

What is the purpose of the task ledger mentioned in the architecture?

The task ledger is a JSON-based communication protocol that guarantees ordering and durability for messages exchanged between the runtime host and UI components. According to docs/session-task-ledger-lifecycle.md, it ensures that agent tasks are tracked reliably even if components restart or encounter network interruptions.

Can I run the web UI without the desktop client?

Yes. The repository includes React-based front-ends for both desktop and web deployments located in packages/ui/. While the desktop client runs on Electron, the underlying React components can be built for web deployment using the standard build scripts defined in packages/ui/README.md.

Where can I find detailed information about the CLI commands?

Complete CLI usage documentation, including workspace management and package installation commands, is available in packages/cli/README.md. This file details how to create workspaces, add skills, and configure the runtime environment through the command-line interface.

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