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

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.

In 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 and integrated into the main protocol stack through 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 and invoke the build process with the --peer flag.

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

npm ci
npm run dev:peer

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

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:

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 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 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: 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: Implements the mesh routing logic and discovery protocol for multi-host communication.
• 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 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.

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