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

> Install Apache Maka with our step-by-step guide. Clone the repo, install dependencies, create a workspace, add skills, and launch the AI platform host and UI.

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

---

**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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/package.json) organizes the project into npm workspaces, allowing npm to hoist shared packages and install each module correctly.

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

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

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

```bash
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`](https://github.com/apache/maka/blob/main/docs/session-task-ledger-lifecycle.md) for the specification).

In another terminal, launch the desktop client:

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

```bash
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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/packages/cli/README.md). This file details how to create workspaces, add skills, and configure the runtime environment through the command-line interface.