# Apache Maka Peer Mesh Architecture: How Direct-Peer Connections Work and Native Build Requirements

> Explore Apache Maka's peer mesh architecture for direct peer connections. Discover how it works and learn the native build requirements, including Rust and Node.js.

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

---

**Apache Maka implements Direct-Peer connections through a decentralized Peer-Mesh subsystem that allows Runtime Hosts to discover, join, and communicate without central servers, while requiring Rust 1.98+, Node.js 22.19.0+, and platform-specific toolchains to build the native networking addon.**

Apache Maka is an open-source runtime host platform designed for decentralized peer-to-peer communication. Understanding Maka's peer mesh architecture is essential for developers who want to enable direct peer connections between distributed Runtime Hosts or contribute to the underlying Rust-based native addon.

## Core Components of the Peer-Mesh Architecture

The Peer-Mesh subsystem consists of several coordinated layers that handle everything from low-level wire protocol definitions to high-level UI interactions.

### PeerMeshNode and the Mesh Authority

At the heart of the architecture lies the **`PeerMeshNode`**, the in-process representation of a mesh instance defined in [`packages/runtime-host/src/server/peer-mesh-authority.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/peer-mesh-authority.ts). This component maintains the **member roster**, tracks **member routes**, and manages **transit-mesh state** for all connected peers.

The same file implements the **operation handlers** for all `peer.mesh.*` protocol requests. These handlers forward commands to the `PeerMeshNode` and include the **`projectPeerMeshQuery`** helper, which translates internal mesh state into public projections consumed by the UI and CLI tooling. The authority centralizes error handling, converting low-level mesh failures—such as persistence errors or unknown post-commit outcomes—into user-readable operation results.

### Wire Protocol and Type Definitions

The stable contract between the Runtime Host and its clients is defined in [`packages/runtime-host/src/protocol/peer-mesh.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/protocol/peer-mesh.ts). This module exports the **`PeerMeshProjection`** and **`PeerMeshQueryResult`** interfaces, ensuring that the desktop UI and CLI consume a consistent, versioned API regardless of internal implementation changes.

### Management UI and Desktop Integration

User-facing mesh operations are implemented in [`packages/runtime-host/src/operator/peer-mesh-management-frame.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/operator/peer-mesh-management-frame.ts), which provides the **`runtime-host-peer-mesh-dialog`** panel. This UI allows users to create meshes, join existing ones, and view member status including pending invitations and transit details.

The Desktop Runtime Host exposes Direct-Peer configuration through [`apps/desktop/src/renderer/features/runtime-host-management/ports.ts`](https://github.com/apache/maka/blob/main/apps/desktop/src/renderer/features/runtime-host-management/ports.ts), implementing the **`getDirectPeer`** and **`configureDirectPeer`** methods. For command-line workflows, [`packages/cli/src/runtime-host-cli.ts`](https://github.com/apache/maka/blob/main/packages/cli/src/runtime-host-cli.ts) parses the **`--enable-direct-peer`** flag and injects the `directPeer` configuration into runtime host launch options.

## How Direct-Peer Connections Work in the Mesh

The Direct-Peer feature operates as a six-stage workflow managed by the mesh operation handlers:

1. **Enable Direct-Peer** – Set `enableDirectPeer = true` via the CLI flag or Desktop UI to activate the mesh subsystem.

2. **Create Mesh** – The Runtime Host invokes `peer.mesh.create` to establish a mesh namespace that serves as the container for all direct connections.

3. **Invite and Join** – Peers exchange invitations through `peer.mesh.invite`, embedding a unique `meshId`. Recipients accept via `peer.mesh.join`, gaining access to the mesh namespace.

4. **Member Routing** – Each peer registers a **member route** containing their address, display name, and role. The mesh authority maintains this roster and distributes updates to all members.

5. **Configure Transit Mesh** – Optionally, a peer selects a transit mesh via `peer.mesh.transit.set`, enabling one peer to act as a relay for others to facilitate NAT traversal or traffic shaping.

6. **Establish Direct Communication** – Once joined, Runtime Hosts open **direct channels** (typically WebRTC data channels) between peers, bypassing central relays for low-latency communication.

All stages are orchestrated by the operation handlers in [`peer-mesh-authority.ts`](https://github.com/apache/maka/blob/main/peer-mesh-authority.ts), which translate UI and CLI commands into low-level mesh actions.

## Native Addon Build Requirements for Direct-Peer

The Direct-Peer feature relies on a **Rust-based native addon** that compiles to a Node.js binary, powering the low-level WebRTC and UDP/TCP transport stacks. Building this addon requires specific toolchain versions:

- **Rust toolchain**: **Stable Rust ≥ 1.98** (minimum required for the current native code)
- **Node.js runtime**: **Node ≥ 22.19.0** (required to load the compiled addon)
- **Package manager**: **npm 11.19.0** (triggers the native build during `npm install`)
- **Platform-specific toolchains**:
  - **macOS**: Xcode Command Line Tools (provides `clang`, `make`, etc.)
  - **Windows**: MSVC Build Tools (provides `cl.exe`, `link.exe`, etc.)

The build process integrates through `npm run build`, which internally invokes Cargo via `node-gyp`, `neon`, or `napi-rs`. These prerequisites are documented in the repository's [`README.md`](https://github.com/apache/maka/blob/main/README.md) and [`CONTRIBUTING.md`](https://github.com/apache/maka/blob/main/CONTRIBUTING.md) files.

## Implementation Code Examples

Enable Direct-Peer when launching a Runtime Host via CLI:

```bash
runtimeHostCli.run(['--enable-direct-peer']);

```

Fetch current mesh status in the Desktop UI:

```typescript
const meshInfo = await bridge.runtimeHostManagement.getDirectPeer(profileId);

```

Configure Direct-Peer with coordination relays and discovery settings:

```typescript
await bridge.runtimeHostManagement.configureDirectPeer(
  profileId,
  true,                     // enable Direct-Peer
  ['wss://relay.example'],  // coordination relays
  true,                     // automatic discovery
  'default'                 // WebRTC STUN policy
);

```

## Summary

- **PeerMeshNode** in [`peer-mesh-authority.ts`](https://github.com/apache/maka/blob/main/peer-mesh-authority.ts) serves as the central authority for mesh state, roster management, and transit configuration.
- The **wire protocol** defined in [`peer-mesh.ts`](https://github.com/apache/maka/blob/main/peer-mesh.ts) provides a stable API contract between Runtime Hosts and client applications.
- Direct-Peer connections follow a six-stage workflow: enable, create mesh, invite/join, route members, configure transit, and establish direct channels.
- Building the native addon requires **Rust 1.98+**, **Node.js 22.19.0+**, and platform-specific compilers (Xcode CLT for macOS, MSVC for Windows).
- The feature can be enabled via CLI flags (`--enable-direct-peer`) or the Desktop UI methods `getDirectPeer` and `configureDirectPeer`.

## Frequently Asked Questions

### What is the minimum Rust version required to build Maka's Direct-Peer native addon?

According to the Apache Maka source code, you need **Rust stable 1.98 or newer** to compile the native addon. This version requirement is specified in both the [`README.md`](https://github.com/apache/maka/blob/main/README.md) and [`CONTRIBUTING.md`](https://github.com/apache/maka/blob/main/CONTRIBUTING.md) files to ensure compatibility with the WebRTC and transport layer dependencies.

### How does Maka handle NAT traversal for Direct-Peer connections?

Maka implements NAT traversal through the **transit mesh** feature. Peers can invoke `peer.mesh.transit.set` to designate themselves as relays for other meshes, enabling traffic to flow between peers behind restrictive firewalls. This transit functionality is managed by the `PeerMeshNode` in [`packages/runtime-host/src/server/peer-mesh-authority.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/peer-mesh-authority.ts).

### Where is the Peer Mesh protocol defined in the source code?

The Peer Mesh wire protocol and type definitions are located in [`packages/runtime-host/src/protocol/peer-mesh.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/protocol/peer-mesh.ts). This file exports the `PeerMeshProjection` and `PeerMeshQueryResult` interfaces that define the stable contract between the Runtime Host server and its desktop or CLI clients.

### Can I enable Direct-Peer connections from the command line?

Yes. The CLI implementation in [`packages/cli/src/runtime-host-cli.ts`](https://github.com/apache/maka/blob/main/packages/cli/src/runtime-host-cli.ts) supports the **`--enable-direct-peer`** flag. When provided, this flag injects the `directPeer` configuration into the runtime host launch options, allowing headless or terminal-based workflows to utilize the peer mesh functionality without the Desktop UI.