MeshCentral — Deep System Reference

Agents connect to the MeshCentral server over a persistent WebSocket connection secured with TLS (WSS — WebSocket Secure) to the path /agent.ashx. All data is binary-framed; the agent sets binaryType = "arraybuffer" and all messages are transmitted as raw binary buffers rather than text frames. The underlying TLS layer encrypts all traffic end-to-end.

Because the transport is a standard WebSocket over TLS, the agent connection is structurally identical to a browser WebSocket connection. This is a deliberate design decision: it allows the full stack of web infrastructure — Nginx reverse proxies, load balancers, CDN edge nodes — to sit in front of a MeshCentral deployment without any special protocol handling. It also means a browser tab can open the same WebSocket connection a native binary agent uses, which is the foundational observation behind the CyberSector Browser Agent.

The agent protocol is a structured binary protocol with no text framing or delimiter characters. All integer fields are big-endian — this is non-negotiable and is confirmed by the agent source code's u16 and u32 helper functions, which write the most-significant byte first. Command IDs are 16-bit unsigned integers (uint16). Length fields for certificates and hostnames are uint16. Fields for info version, agent ID, agent version, platform type, and capabilities are 32-bit unsigned integers (uint32). Messages are raw binary buffers concatenated in a defined order with field boundaries determined entirely by fixed field sizes — there are no length-prefixed frames at the outer message level and no delimiters between fields.

The binary protocol uses a numbered command space. Commands 0–9 are the authentication phase; commands 10 and above are post-authentication and require the agent to already be authenticated before the server will process them.

The following is the exact, correct protocol flow. Step order is fixed — sending AUTH_INFO before AUTH_VERIFY, for example, will cause the server to reject or ignore the message.

Each agent has a persistent identity based on an RSA keypair. The agent generates a 3072-bit RSA keypair and issues itself a self-signed X.509 certificate. The certificate is DER-encoded (binary ASN.1) for transmission in the AUTH_VERIFY message.

The NodeID — the unique identifier for the device in MeshCentral's database — is derived deterministically from the public key, not from the certificate itself and not from the private key:

The result is a 64-character string that uniquely identifies the agent across all reconnections, provided the same keypair is reused.

The serverHash field in AUTH_REQUEST is the SHA-384 hash of the TLS public key of the certificate the server presents on the WebSocket connection — specifically the public key component. This is distinct from the domain certificate fingerprint in the traditional sense, and it is also distinct from the ServerID field present in .msh provisioning files (which is the hash of the agent's own certificate).

When running behind a TLS-terminating reverse proxy such as Nginx, the agent must hash the public key of the proxy's certificate — the certificate actually seen on the WebSocket TLS handshake — not the backend MeshCentral server's internal certificate. This is a common source of configuration error.

MeshCore is a JavaScript module that the MeshCentral server pushes to connected agents after authentication. It runs inside the agent's embedded DukTape JavaScript runtime — a lightweight ECMAScript engine compiled into the native MeshAgent binary. MeshCore provides higher-level management functionality on top of the binary protocol: remote desktop, terminal, file management, and scripting.

The core hash exchange (commands 0x000A, 0x000B) allows the server to selectively update MeshCore on individual agents without a full agent binary update. Because MeshCore runs on DukTape, which is an embedded C runtime, browser-based agents cannot execute MeshCore — the DukTape environment is not available in a browser context and cannot be polyfilled.

React2API is a two-part system: a Node.js REST API that runs alongside MeshCentral on the same server, and a React/Next.js frontend operator console that consumes it. Together they replace the default MeshCentral web UI for operator workflows, providing real-time device status, group orchestration, and a clean JSON/REST interface that mobile clients and automation scripts can consume directly.

MeshCentral's native UI is a full-stack server-rendered application. Direct WebSocket access to /control.ashx — the user-facing management WebSocket — requires handling MeshCentral's proprietary JSON message format and maintaining a stateful WebSocket session. React2API abstracts this behind a stateless REST/JSON API layer, making it straightforward to build any frontend or automate management tasks from scripts. JWT authentication makes the API stateless and portable across serverless environments.

The API is a Node.js application (server.js) that runs on localhost:3001 and is reverse-proxied by Nginx at the /api/ path prefix, keeping MeshCentral's own UI accessible at the root. It uses both meshctrl.js and libmeshctrl.js — two distinct files that ship with every MeshCentral installation — as its backend engines. meshctrl.js is the command-line control tool located at node_modules/meshcentral/meshctrl.js, invoked as a subprocess for operations where parsed text output is sufficient. A separate utility module, utils/parseDevices.js, converts meshctrl's line-oriented text output into structured JSON for API responses.

libmeshctrl.js is a JavaScript library file bundled within MeshCentral's npm package itself — found at node_modules/meshcentral/libmeshctrl.js in a standard MeshCentral installation. It provides a programmatic async API over MeshCentral's WebSocket management channel (/control.ashx) for device listing, user management, and group operations. It is distinct from meshctrl.js (the command-line tool) and distinct from the separately maintained github.com/Ylianst/LibMeshCtrl project — the React2API implementation uses the version bundled with MeshCentral itself, not the external project.

A client POSTs credentials to /api/mobile-auth. The API validates credentials against MeshCentral via meshctrl, issues a signed JWT (Authorization: Bearer <token>), and returns it. All subsequent API calls include this token in the Authorization header, validated by jwtMiddleware.js on every protected route. The JWT secret is set via the JWT_SECRET environment variable. Token expiry is 3600 seconds. On the React side, tokens are stored in localStorage for session persistence across page reloads.

After receiving a JWT, the login flow immediately calls /api/devices to validate the session. MeshCentral returns [{}] — an array containing one empty object — for invalid credentials rather than an error status code. The API and React client both treat a devices response of [{}] as an authentication failure and surface an error to the user.

The reverse proxy configuration forwards /api/ to http://127.0.0.1:3001/ while MeshCentral's own UI continues serving from http://127.0.0.1:8443 at the root. WebSocket upgrade headers are forwarded. proxy_read_timeout and proxy_send_timeout are set to 360 seconds to accommodate long-running management operations.

The frontend is a Next.js application deployed to Vercel. It includes a login page (app/page.tsx), a dashboard (app/dashboard/page.tsx), and a component library: LoginForm.tsx, ServerSettings.tsx, DeviceList.tsx, and DeviceCard.tsx. The server URL is configurable at runtime via ServerSettings.tsx, persisted in localStorage, making the frontend capable of targeting multiple MeshCentral deployments without a rebuild. The dashboard displays device name, ID, group, connection status, and power state for every device visible to the authenticated user.

The three projects form a coherent vertical stack over MeshCentral. Auto-Config provisions the server and establishes device groups. The Browser Agent demonstrates that any browser-accessible device can be enrolled as a managed node without distributing a binary. React2API provides the operator interface for managing the resulting fleet — viewing status, organizing groups, and managing users — through a clean REST interface that is more accessible to mobile clients and automation scripts than MeshCentral's native WebSocket management protocol.

MeshCentral itself sits at the center as the source of truth for device identity, session management, and MeshCore distribution. The CyberSector work does not modify MeshCentral's server code; it operates entirely through documented protocols and published interfaces: the binary /agent.ashx handshake for the Browser Agent, meshctrl.js and libmeshctrl.js for Auto-Config and the React2API backend, and the /control.ashx WebSocket management channel for the React2API operator interface.

The browser-native approach to agent enrollment has specific practical implications. Because the Browser Agent runs in a tab, any device with a modern web browser — regardless of operating system, architecture, or the ability to execute unsigned code — can be enrolled into a MeshCentral-managed fleet. The identity persists across page reloads if the keypair is stored in IndexedDB; without persistence, the agent registers as a new node on each session. This is a deliberate tradeoff, and the architecture is designed to make persistence opt-in rather than default.

The entire stack is production-deployable. React2API's API layer and React frontend are live on Vercel and a VPS respectively. The Browser Agent is a deployable static site. Auto-Config runs against real MeshCentral installations. None of these are proof-of-concept scaffolding — they are operational implementations built to run.

The MeshCentral Protocol Demo is a self-contained, browser-native simulation of the full agent lifecycle — RSA-3072 identity generation, binary authentication handshake over /agent.ashx, KVM relay tunnel establishment, and real-time JPEG tile streaming. Everything runs inside this server with no external connections.

The demo runs on its own dedicated page with a live protocol flow visualizer, agent computer canvas, server viewer canvas, and control buttons for refresh, pause/resume, and text injection.