# How to Enable the Peer-Enabled Entry Point in Apache Maka: Direct Peer + Mesh Setup

> Learn how to enable the peer-enabled entry point in Apache Maka with direct peer and mesh setup. Configure environment variables and compile native addons for seamless integration.

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

---

**To enable the peer-enabled entry point in Maka, install Rust, run `npm run dev:peer` to compile the native addon, and set the `MAKA_RUNTIME_HOST_PEER_NATIVE_PATH` and `MAKA_RUNTIME_HOST_PEER_KEY_PATH` environment variables to activate the Direct Peer transport alongside the Peer Mesh layer.**

The peer-enabled entry point in Apache Maka unlocks two complementary networking transports that operate before the Desktop or CLI interface initializes. This configuration combines a high-performance native WebSocket transport with automatic multi-host discovery, requiring specific build steps and environment configuration to activate both the **Direct Peer** and **Peer Mesh** layers.

## Prerequisites for the Peer-Enabled Entry Point

Before enabling the peer-enabled entry point, you must install the Rust toolchain and platform-specific build tools. The native Direct Peer transport is implemented as a Rust addon in the `native/` directory and requires compilation before the Maka Runtime Host can load it.

- **Rust toolchain** (stable ≥ 1.98)
- **Platform linker**: Xcode command-line tools on macOS or MSVC Build Tools on Windows
- **Compiled native addon**: The build process outputs `libmaka_runtime_host_peer.so` (Linux), `.dylib` (macOS), or `.node` (Windows) in `native/target/release/`

According to the repository README, these components must be available before the entry point selection occurs, as the native addon initializes prior to the UI layer starting.

## Understanding the Dual Transport Architecture

The peer-enabled entry point activates two distinct transports that work together to provide low-latency local communication and distributed host discovery.

### Direct Peer Transport

The **Direct Peer** is an experimental native Rust addon that provides the Runtime Host with a TLS-free, high-performance WebSocket transport. This implementation lives in the `native/` crate and is exposed to the TypeScript client layer via [`packages/runtime-host/src/client/peer-client.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/client/peer-client.ts).

In [`peer-client.ts`](https://github.com/apache/maka/blob/main/peer-client.ts), the client checks for the environment variables `MAKA_RUNTIME_HOST_PEER_NATIVE_PATH` and `MAKA_RUNTIME_HOST_PEER_KEY_PATH` at line 144. When these variables are present, the client instantiates the native addon instead of falling back to the generic WebSocket implementation.

### Peer Mesh Layer

The **Peer Mesh** provides fully-featured mesh networking that allows multiple Runtime Host instances to discover and route messages between each other. This logic is exported from [`packages/runtime-host/src/protocol/peer-mesh.js`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/protocol/peer-mesh.js) and integrated into the main protocol stack through [`packages/runtime-host/src/protocol/index.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/protocol/index.ts).

The mesh routes are advertised in the host's status payload, which is logged at line 243 of the protocol index file, allowing you to verify active connections through the "Direct peer" status line.

## Enabling the Peer-Enabled Entry Point

There are two methods to enable the peer-enabled entry point: using the provided npm scripts for development or manually configuring the environment variables for custom deployments.

### Using the Development Scripts

The Apache Maka repository provides convenience scripts that handle the native addon compilation and entry point selection automatically. These scripts are defined in the root [`package.json`](https://github.com/apache/maka/blob/main/package.json) and invoke the build process with the `--peer` flag.

For hot-module replacement (HMR) during everyday development:

```bash
npm ci
npm run dev:peer

```

For a full production-style build that recompiles every workspace before launching Electron:

```bash
npm run dev:full:peer

```

These scripts trigger the native-addon compilation step and set the appropriate entry point flags before the Runtime Host initializes.

### Manual Configuration with Environment Variables

If you need to start the Runtime Host outside the `dev:peer` scripts—such as when running the CLI or TUI interfaces manually—you must explicitly point to the compiled native binary and its private key.

Set the transport variables before launching the host:

```bash
export MAKA_RUNTIME_HOST_PEER_NATIVE_PATH=$(pwd)/native/target/release/libmaka_runtime_host_peer.so
export MAKA_RUNTIME_HOST_PEER_KEY_PATH=$(pwd)/native/peer-key.pem

```

On macOS, use `.dylib` instead of `.so`; on Windows, use `.node`. The [`peer-client.ts`](https://github.com/apache/maka/blob/main/peer-client.ts) implementation reads these variables at startup and switches to the direct-peer transport when they are valid.

### Verifying the Configuration

After startup, verify that both transports are active by checking the host status output. The log at line 243 of [`packages/runtime-host/src/protocol/index.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/protocol/index.ts) displays a "Direct peer" line containing the lease ID and available routes. Additionally, the Desktop UI displays a "Peer Mesh" badge in the runtime-host-management panel when the peer-enabled entry point is successfully initialized.

## Key Implementation Details

The peer-enabled entry point relies on specific source files that handle transport initialization and protocol routing:

- **[`packages/runtime-host/src/client/peer-client.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/client/peer-client.ts)**: Validates environment variables at line 144 and creates the Direct Peer transport instance using the native addon path.
- **[`packages/runtime-host/src/protocol/peer-mesh.js`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/protocol/peer-mesh.js)**: Implements the mesh routing logic and discovery protocol for multi-host communication.
- **[`packages/runtime-host/src/protocol/index.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/protocol/index.ts)**: Exports the mesh module and logs peer status information at line 243, advertising available routes in the host status payload.
- **`native/`**: Contains the Rust crate that builds `libmaka_runtime_host_peer.*`, providing the high-performance WebSocket transport that bypasses TLS overhead.

## Summary

- The peer-enabled entry point requires **Rust ≥ 1.98** and platform-specific linkers to compile the native addon in `native/`.
- Use **`npm run dev:peer`** for HMR development or **`npm run dev:full:peer`** for full builds to enable both transports automatically.
- Set **`MAKA_RUNTIME_HOST_PEER_NATIVE_PATH`** and **`MAKA_RUNTIME_HOST_PEER_KEY_PATH`** manually when running the Runtime Host outside the provided npm scripts.
- Verify activation through the "Direct peer" status line in the protocol logs and the "Peer Mesh" badge in the Desktop UI.

## Frequently Asked Questions

### What is the difference between Direct Peer and Peer Mesh transports?

According to the Apache Maka source code, the **Direct Peer** is a native Rust addon that provides a high-performance, TLS-free WebSocket transport for low-latency local communication, while the **Peer Mesh** is a JavaScript-based layer that handles multi-host discovery and message routing between Runtime Host instances. The peer-enabled entry point activates both simultaneously.

### Can I use the peer-enabled entry point in production environments?

The **Direct Peer** transport is currently marked as experimental in the codebase. While the **Peer Mesh** layer is production-ready, the native addon relies on environment variables and manual key management (`MAKA_RUNTIME_HOST_PEER_KEY_PATH`) that may require additional security review before deployment in production systems.

### How do I troubleshoot if the native addon fails to load?

Check that `MAKA_RUNTIME_HOST_PEER_NATIVE_PATH` points to the correct compiled binary in `native/target/release/` with the appropriate extension for your platform (`.so`, `.dylib`, or `.node`). Ensure the file has execute permissions and that `MAKA_RUNTIME_HOST_PEER_KEY_PATH` points to a valid PEM file. The [`peer-client.ts`](https://github.com/apache/maka/blob/main/peer-client.ts) file will silently fall back to the generic WebSocket client if these variables are missing or invalid.

### Is the peer-enabled entry point compatible with the CLI and TUI interfaces?

Yes, but you must set the environment variables manually before launching the CLI. The `npm run dev:peer` script only configures the Desktop (Electron) entry point automatically. For CLI usage, export the `MAKA_RUNTIME_HOST_PEER_NATIVE_PATH` and `MAKA_RUNTIME_HOST_PEER_KEY_PATH` variables, then run `npm run cli:dev` to ensure the Runtime Host initializes with the direct peer transport enabled.