# How to Deploy Apache Maka: A Complete Guide to Runtime Host and CLI Installation

> Deploy Apache Maka easily by cloning the repo, installing Node.js, and running npm commands. Learn how to build the runtime host and manage deployments efficiently with this complete guide.

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

---

**Deploy Apache Maka by cloning the repository, installing Node.js ≥ 18, running `npm ci` to install workspace dependencies, building the runtime host with `npm run build`, and starting the host process that manages deployment ownership via file-lock mechanisms.**

Apache Maka is a modular multi-agent AI platform that separates **deployment ownership** from data ownership through a runtime host architecture. This guide explains how to deploy Apache Maka from source, including building the runtime host, configuring deployment locks, and installing the CLI client according to the [repository source code](https://github.com/apache/maka).

## Prerequisites

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

- **Node.js** ≥ 18 (LTS recommended)
- **npm** ≥ 9 (included with Node.js)
- **Git** for cloning the repository

The platform is built as a monorepo using npm workspaces, so a compatible Node version is essential for building the TypeScript sources.

## Clone and Install Workspace Dependencies

Start by cloning the official Apache Maka repository and installing dependencies across all packages:

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

```

The `npm ci` command installs locked dependencies for all workspace packages, including the runtime host, CLI, storage layer, and evaluation frameworks. This ensures consistent builds across the monorepo structure defined in the root [`package.json`](https://github.com/apache/maka/blob/main/package.json).

## Build and Start the Runtime Host

The **runtime host** is the central server process that owns the execution sandbox, persistence layer, and session management. To deploy it:

```bash

# Build the runtime-host package

npm run build --workspaces=runtime-host

# Start the host process

node packages/runtime-host/dist/main.js

```

By default, the host listens on `127.0.0.1:3000` and creates a deployment ownership record in [`runtime-host-deployments.json`](https://github.com/apache/maka/blob/main/runtime-host-deployments.json) within the user data directory. The host composition logic is implemented in [[`packages/runtime-host/src/server/execution-composition.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/execution-composition.ts)](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/execution-composition.ts), which wires together the `SessionManager` and `BackendRegistry`.

### Understanding Deployment Ownership

Apache Maka uses a **deployment ownership** model to prevent concurrent host instances on the same machine. The ownership logic resides in two key files:

- [[`packages/runtime-host/src/operator/local-deployment-owner.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/operator/local-deployment-owner.ts)](https://github.com/apache/maka/blob/main/packages/runtime-host/src/operator/local-deployment-owner.ts) – Handles single-user deployments using file-based locks
- [[`packages/runtime-host/src/operator/managed-deployment.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/operator/managed-deployment.ts)](https://github.com/apache/maka/blob/main/packages/runtime-host/src/operator/managed-deployment.ts) – Coordinates multi-instance deployments in CI or orchestrated environments

When the host starts, it attempts to acquire a **process-lifetime file lock** via [[`packages/storage/src/process-lifetime-file-update-lock.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/process-lifetime-file-update-lock.ts)](https://github.com/apache/maka/blob/main/packages/storage/src/process-lifetime-file-update-lock.ts). If another process already holds the lock, the new instance exits immediately, preventing data corruption.

### Configuring the Host Address

Set the `MAKA_RUNTIME_HOST_URL` environment variable to customize the host endpoint:

```bash
export MAKA_RUNTIME_HOST_URL=http://localhost:3000
node packages/runtime-host/dist/main.js

```

For production deployments, expose this variable to client processes so they can discover the host automatically.

## Deploy the CLI Client

The CLI package provides a command-line interface for connecting to the runtime host. Deploy it globally or locally:

```bash

# Global installation (recommended for client machines)

npm i -g @maka/cli

# Or run directly from the workspace

npm run cli --workspaces=packages/cli

```

Once installed, start a session against the running host:

```bash
export MAKA_RUNTIME_HOST_URL=http://localhost:3000
maka session start --backend ai-sdk

```

The CLI automatically discovers available backends and creates a REPL session. Refer to [[`packages/cli/README.md`](https://github.com/apache/maka/blob/main/packages/cli/README.md)](https://github.com/apache/maka/blob/main/packages/cli/README.md) and [[`docs/cli-npm-release.md`](https://github.com/apache/maka/blob/main/docs/cli-npm-release.md)](https://github.com/apache/maka/blob/main/docs/cli-npm-release.md) for advanced configuration options and release management procedures.

## Containerized Deployment

For production environments, package the runtime host as a Docker container. Create a `Dockerfile` in the repository root:

```dockerfile
FROM node:20-alpine
WORKDIR /app
COPY packages/runtime-host ./
RUN npm ci && npm run build
EXPOSE 3000
CMD ["node", "dist/main.js"]

```

Build and run the container:

```bash
docker build -t apache/maka-runtime-host .
docker run -d -p 3000:3000 --name maka-host apache/maka-runtime-host

```

This approach isolates the host process and allows you to mount persistent volumes for the SQLite storage layer located in the user data directory.

## Embed in Custom Applications

You can also deploy Apache Maka as a library within existing Node.js applications:

```typescript
import { SessionManager } from '@maka/runtime/session-manager';
import { AiSdkBackend } from '@maka/runtime/ai-sdk-backend';

const manager = new SessionManager({
  backendFactory: () => new AiSdkBackend(),
  hostUrl: 'http://localhost:3000',
});

await manager.start();
const result = await manager.runPrompt('Analyze this dataset for anomalies.');
console.log(result);

```

This pattern imports the runtime directly from the [`packages/runtime`](https://github.com/apache/maka/blob/main/packages/runtime/README.md) package, bypassing the CLI while maintaining full host connectivity.

## Summary

- **Clone and install** the monorepo with `npm ci` after ensuring Node.js ≥ 18 is installed
- **Build the runtime host** using workspace-specific build commands to compile TypeScript sources
- **Start the host** with `node packages/runtime-host/dist/main.js`, which creates a deployment ownership lock via [`local-deployment-owner.ts`](https://github.com/apache/maka/blob/main/local-deployment-owner.ts) or [`managed-deployment.ts`](https://github.com/apache/maka/blob/main/managed-deployment.ts)
- **Install the CLI** globally via `npm i -g @maka/cli` and connect using `MAKA_RUNTIME_HOST_URL`
- **Deploy via Docker** using the provided containerization pattern for isolated production environments
- **Reference architecture** details in [[`ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md)](https://github.com/apache/maka/blob/main/ARCHITECTURE.md) for deployment ownership concepts and file-lock implementations

## Frequently Asked Questions

### What Node.js version is required to deploy Apache Maka?

Apache Maka requires **Node.js ≥ 18** (LTS recommended). The build system relies on modern npm workspaces features and TypeScript compilation targets that depend on Node 18+ APIs. Older versions will fail during the `npm ci` or build phases.

### Can I run multiple runtime host instances on the same machine?

Yes, but each instance must manage its own **deployment ownership** boundaries. The [[`local-deployment-owner.ts`](https://github.com/apache/maka/blob/main/local-deployment-owner.ts)](https://github.com/apache/maka/blob/main/packages/runtime-host/src/operator/local-deployment-owner.ts) implementation uses a process-lifetime file lock to prevent conflicts. To run multiple hosts, configure separate data directories (via environment variables) so each host maintains its own [`runtime-host-deployments.json`](https://github.com/apache/maka/blob/main/runtime-host-deployments.json) and storage locks.

### How does the CLI find the runtime host?

The CLI discovers the host through the **`MAKA_RUNTIME_HOST_URL`** environment variable or falls back to the default Unix socket path. If the variable is unset and no local socket exists, the CLI exits with a connection error. Always export this variable when deploying the CLI on a different machine from the host.

### What is the purpose of the process-lifetime file lock?

The lock in [[`process-lifetime-file-update-lock.ts`](https://github.com/apache/maka/blob/main/process-lifetime-file-update-lock.ts)](https://github.com/apache/maka/blob/main/packages/storage/src/process-lifetime-file-update-lock.ts) ensures that only one active host process controls the SQLite persistence layer at any time. This prevents race conditions during session state writes and deployment metadata updates. If the host crashes, the lock is automatically released by the operating system when the process terminates.