# Apache Maka Monorepo: Complete Guide to the Main Packages in the Repository

> Explore the Apache Maka monorepo and discover its ten main npm packages for modular React components, runtime engines, storage, and CLI tooling. Learn about the Maka repository's structure.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: deep-dive
- Published: 2026-09-10

---

**The Apache Maka repository organizes its functionality into ten first-party npm packages under the `packages/` directory, providing modular React components, runtime engines, storage abstractions, and CLI tooling.**

Apache Maka is an open-source framework for building AI-powered desktop applications, structured as a monorepo that separates concerns into discrete, reusable npm packages. Understanding the main packages in the Maka repository is essential for developers extending the platform or consuming specific modules. Each package maintains its own [`package.json`](https://github.com/apache/maka/blob/main/package.json) and source directory, exposing functionality through scoped `@maka/*` imports or the global `maka` CLI.

## UI Components and Frontend Infrastructure

The **`@maka/ui`** package provides reusable React components, Storybook stories, and UI utilities that power the desktop client. According to [`packages/ui/package.json`](https://github.com/apache/maka/blob/main/packages/ui/package.json), the library exports components like the `Toast` notification system from [`packages/ui/src/toast.tsx`](https://github.com/apache/maka/blob/main/packages/ui/src/toast.tsx).

```tsx
import { Toast } from '@maka/ui';

// Show a toast notification from anywhere in the app
Toast.show({ message: 'Hello from Maka!', type: 'info' });

```

The **`@maka/website`** package handles static site generation for documentation, Storybook hosting, and release notes. While not part of the core runtime, it supports the `website/` directory and manages the project's documentation build pipeline as defined in [`website/package.json`](https://github.com/apache/maka/blob/main/website/package.json).

## Runtime Engine and Execution Host

The execution layer splits responsibilities between the runtime engine and its sandboxed host process. The **`@maka/runtime`** package, defined in [`packages/runtime/package.json`](https://github.com/apache/maka/blob/main/packages/runtime/package.json), contains the core runtime engine that orchestrates tool execution, transcript handling, and skill management. It works in conjunction with **`@maka/core`**, located in `packages/core/`, which provides low-level utilities, type definitions, and the `ToolRegistry` used across all packages.

```ts
import { Runtime } from '@maka/runtime';
import { ToolRegistry } from '@maka/core';

// Register a simple echo tool
ToolRegistry.register('echo', {
  async run(input) {
    return `Echo: ${input}`;
  },
});

const runtime = new Runtime();
runtime.executeTool('echo', 'test input')
  .then(console.log); // → "Echo: test input"

```

The **`@maka/runtime-host`** package in `packages/runtime-host/` implements the host process responsible for running the runtime in a sandboxed environment. According to [`packages/runtime-host/package.json`](https://github.com/apache/maka/blob/main/packages/runtime-host/package.json), it manages IPC channels, WebSocket transport layers, and peer-to-peer streams, isolating tool execution from the main application process.

## Control Plane and Data Persistence

The **`@maka/mcp`** (Maka Control Plane) package, specified in [`packages/mcp/package.json`](https://github.com/apache/maka/blob/main/packages/mcp/package.json), provides central control-plane services including authentication, policy enforcement, and multi-session coordination. This package acts as the security and orchestration backbone for the desktop application.

For data management, the **`@maka/storage`** package in `packages/storage/` offers abstractions for persisting user data, session history, and configuration files. The Apache Maka source code indicates this layer ensures durable state management across application restarts.

## Evaluation Framework and Computer-Use Abstractions

Testing and agent capabilities reside in two specialized packages. The **`@maka/eval`** package in `packages/eval/` contains the evaluation framework used for testing toolchains, policies, and sandbox behaviors, providing utilities for automated validation of runtime configurations.

The **`@maka/computer-use`** package in `packages/computer-use/` delivers high-level abstractions that model "computer-use" actions such as mouse clicks and keyboard input for tool agents. This package bridges AI agent logic with system-level interaction primitives.

## Command Line Interface

The **`maka-agent`** package, exposed as the `maka` CLI, lives in `packages/cli/` and serves as the primary command-line interface. Defined in [`packages/cli/package.json`](https://github.com/apache/maka/blob/main/packages/cli/package.json), it boots the desktop client, bundles the runtime, and provides developer utilities. The entry point is implemented in [`packages/cli/src/cli.ts`](https://github.com/apache/maka/blob/main/packages/cli/src/cli.ts) and referenced in the package's `bin` field.

```bash

# Install the CLI globally (or use npx)

npm i -g maka-agent

# Launch the desktop client

maka start --workspace my-workspace

```

The desktop application (`apps/desktop`) consumes these packages through the monorepo's Yarn/PNPM workspace configuration, while external developers can install individual `@maka/*` packages directly from npm.

## Summary

The Apache Maka monorepo divides functionality into logical, reusable modules:

- **`@maka/ui`**: React component library and UI utilities located in `packages/ui/`
- **`@maka/runtime`**: Core engine for tool execution and skill management in `packages/runtime/`
- **`@maka/runtime-host`**: Sandboxed host process for secure execution in `packages/runtime-host/`
- **`@maka/mcp`**: Control-plane services for authentication and policy enforcement in `packages/mcp/`
- **`@maka/storage`**: Persistence layer for user data and configuration in `packages/storage/`
- **`@maka/core`**: Shared utilities and type definitions in `packages/core/`
- **`@maka/eval`**: Testing framework for toolchains and policies in `packages/eval/`
- **`@maka/computer-use`**: Abstractions for AI agent system interactions in `packages/computer-use/`
- **`maka-agent`**: Command-line interface and desktop launcher in `packages/cli/`
- **`@maka/website`**: Documentation and static site generation in `website/`

Each package maintains strict boundaries defined by its [`package.json`](https://github.com/apache/maka/blob/main/package.json), allowing selective consumption of Maka's capabilities without importing the entire framework.

## Frequently Asked Questions

### What is the difference between @maka/runtime and @maka/runtime-host?

The **`@maka/runtime`** package contains the orchestration logic for executing tools and managing transcripts, while **`@maka/runtime-host`** runs the runtime in a sandboxed environment handling IPC and WebSocket transport. The runtime-host isolates execution for security, whereas the runtime manages the business logic of tool invocation according to [`packages/runtime/package.json`](https://github.com/apache/maka/blob/main/packages/runtime/package.json) and [`packages/runtime-host/package.json`](https://github.com/apache/maka/blob/main/packages/runtime-host/package.json).

### How do I use individual Maka packages without installing the full desktop application?

External consumers can install specific scoped packages directly from npm using commands like `npm install @maka/ui` or `npm install @maka/core`. The monorepo structure allows you to import only the functionality you need, though the `maka-agent` CLI requires the full runtime environment to boot the desktop client.

### Which package contains the type definitions shared across Maka?

The **`@maka/core`** package in `packages/core/` serves as the foundation for all other modules, exporting TypeScript definitions, the `ToolRegistry` class, and low-level utilities. It is a peer dependency for most other packages in the repository and ensures type consistency across the framework as specified in [`packages/core/package.json`](https://github.com/apache/maka/blob/main/packages/core/package.json).

### Where is the source code for the maka CLI command located?

The CLI implementation resides in [`packages/cli/src/cli.ts`](https://github.com/apache/maka/blob/main/packages/cli/src/cli.ts) with its package configuration defined in [`packages/cli/package.json`](https://github.com/apache/maka/blob/main/packages/cli/package.json). The executable is published to npm as `maka-agent` but exposes the binary name `maka` for command-line usage, as specified in the package's `bin` field.