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

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.

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:

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.

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:

# 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 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), 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) – 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) – 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). 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:

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:

# 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:

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) and [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:

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:

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:

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 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 or 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) 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/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 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/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.

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