Skip to content

prerequisites.md

Latest commit

 

History

History
196 lines (141 loc) · 5.75 KB

prerequisites.md

File metadata and controls

196 lines (141 loc) · 5.75 KB
Raw

Prerequisites

This page describes everything you need before building, running, or contributing to MeshAgent.

System Requirements

MeshAgent is a native C/C++ project that compiles and runs on three major operating systems. Ensure your host meets the minimum requirements below.

Requirement Minimum Recommended
Operating System Windows 7+, Linux (kernel 3.x+), macOS 10.12+ Windows 10/11, Ubuntu 20.04+, macOS 12+
CPU Architecture x86, x86-64, ARM, ARM64 x86-64 or ARM64
RAM 64 MB free 256 MB free
Disk Space 50 MB 200 MB (including build toolchain)
Network TCP outbound on port 16990 Stable internet or LAN to management server

Build Toolchain

To compile MeshAgent from source, you need a C/C++ build environment appropriate for your platform.

Linux

Tool Version Purpose
gcc or clang 7.0+ C/C++ compiler
make 4.0+ Build system
libssl-dev / openssl-devel 1.1.x or 3.x TLS/crypto development headers
libx11-dev Any X11 remote desktop (KVM on Linux)
libxtst-dev Any X11 input event injection (KVM)
libxext-dev Any X11 extensions
libxfixes-dev Any X11 fixes extension (cursor)
zlib1g-dev 1.2+ Compression (log rotation, JPEG)
pthreads POSIX Threading (included in glibc)

Install on Ubuntu/Debian:

sudo apt-get update
sudo apt-get install -y \
  build-essential \
  libssl-dev \
  libx11-dev \
  libxtst-dev \
  libxext-dev \
  libxfixes-dev \
  zlib1g-dev

Install on Red Hat/CentOS/Fedora:

sudo dnf install -y \
  gcc gcc-c++ make \
  openssl-devel \
  libX11-devel \
  libXtst-devel \
  libXext-devel \
  libXfixes-devel \
  zlib-devel

macOS

Tool Version Purpose
Xcode Command Line Tools 12.0+ C/C++ compiler (clang), linker
make 4.0+ Build system
macOS SDK 11.0+ CoreGraphics, IOKit (KVM capture)

Install Xcode Command Line Tools:

xcode-select --install

Note: On macOS, the KVM engine uses CoreGraphics for screen capture and requires Accessibility and Screen Recording permissions to be granted to the agent binary or its parent process. The TCC (Transparency, Consent, and Control) permission handling is built into the agent.

Windows

Tool Version Purpose
Visual Studio 2019 or 2022 C/C++ compiler (MSVC), linker
Windows SDK 10.0.18362+ GDI, DXGI, WinCrypt APIs
Git for Windows 2.x Source control

Note: The Windows KVM engine supports both GDI (legacy) and DXGI (DirectX) screen capture. Multi-monitor support and secure desktop handling are included.

JavaScript Tooling (for module development)

MeshAgent's modules/ directory contains JavaScript files that run inside the agent's embedded Duktape engine. The agent itself executes them natively — no separate Node.js runtime is required at deploy time. However, for development and tooling:

Tool Version Purpose
Node.js 18+ Running build tools and the VoltAgent AI SDK
npm 9+ Package management

The repository's package.json includes these JavaScript dependencies:

Package Version Purpose
@ai-sdk/anthropic ^2.0.91 Anthropic Claude AI SDK (Vercel AI SDK adapter)
@anthropic-ai/sdk ^0.115.0 Anthropic API client
@voltagent/core ^2.9.0 VoltAgent AI agent framework
glob ^13.0.6 File glob matching
zod ^4.4.3 Schema validation

Install JavaScript dependencies:

npm install

Note: These packages power the AI-assisted development tooling (documentation generation, code analysis). They are not required to build or run the native agent binary itself.

Networking Requirements

Port Protocol Direction Purpose
16990 TCP (TLS WebSocket) Outbound Agent → management server control channel
16991 UDP Outbound STUN protocol for WebRTC NAT traversal
Ephemeral UDP (DTLS) Both WebRTC peer-to-peer data channel

Ensure your firewall allows the agent to make outbound connections on port 16990. Inbound connections are generally not required unless running the agent in server/relay mode.

Account and Access Requirements

Requirement Notes
Management Server A running MeshCentral or OpenFrame server to connect the agent to
MeshID Unique mesh network identifier — provided in the .msh configuration file
MeshServer URL WebSocket URL (wss://...) of your management server
Agent Certificate Auto-generated by the agent on first run; stored in meshagent.db

Required Files

File Purpose
meshagent (binary) The compiled agent executable
meshagent.msh Configuration file containing MeshServer, MeshID, and other settings
meshagent.db Auto-created persistent identity store (certificates, node ID)

The .msh file is a plain key=value format:

MeshServer=wss://your-server.example.com/agent.ashx
MeshID=your-mesh-id-here
MeshType=2

Verifying Your Environment

Run these commands to confirm your toolchain is ready before building:

Linux / macOS

# Verify C compiler
gcc --version
# OR
clang --version

# Verify make
make --version

# Verify OpenSSL development headers
pkg-config --modversion openssl

# Verify zlib
pkg-config --modversion zlib

# Verify Node.js (for JS tooling)
node --version
npm --version

Windows (from Developer Command Prompt)

cl /?

Community support: For help with prerequisites or environment setup, join the OpenMSP Slack community.