MeshCentral Install Guide: Agents, Groups and Remote Desktop

This guide is for sysadmins, MSP technicians and home-lab owners who want browser-based remote desktop, terminal and file access to their own computers without a third-party cloud. The short answer: MeshCentral is installed with Node.js and npm (there is no classic server installer to download), the first account you create becomes the administrator, and computers join through a small agent that you download from your own server after you create a device group.

MeshCentral is free and open source under the Apache License 2.0. The current release is 1.2.6 (24 September 2026) and the server needs Node.js 20 or newer.

What you are installing

You do not install anything on the technician side, which is the main difference from desktop-client tools such as RustDesk.

Install the server with npm

The official quick start asks for Node.js and npm first. On Linux use the package-manager instructions on the nodejs.org download page; on Windows use the Node.js installer. Then create a folder and install the package as a normal user:

mkdir -p /opt/meshcentral
cd /opt/meshcentral
npm install meshcentral
node node_modules/meshcentral

The documentation is explicit: do not run npm install meshcentral with sudo. The server starts in LAN-only mode, where agents find it by multicast on the local network. Settings live in meshcentral-data/config.json, which must be valid JSON.

Open the server address in a browser and create your account immediately. MeshCentral has no default username or password: the first account created becomes the server administrator. Do this before the server is reachable from the internet.

Once it works, stop it with Ctrl+C and run node node_modules/meshcentral --install to register it as a background service. Run --help to see the other service options.

Windows

The easiest route is the same npm procedure after installing Node.js. The official site also offers a MeshCentral installer for Windows, but the documentation says it is not recommended for advanced users.

Run it in Docker instead

Official images are published as ghcr.io/ylianst/meshcentral. The tag selects the database backend:

• no suffix: all backends supported;
• -slim: local database only;
• -mongodb, -postgresql, -mysql: images for those databases.

The latest tag follows released versions and master follows development code; you can also pin a version. The Docker readme documents environment variables such as HOSTNAME for the server name and ALLOW_NEW_ACCOUNTS, which defaults to false. The most important volume is meshcentral-data, mounted at /opt/meshcentral/meshcentral-data, because it holds the server configuration and certificates. The image no longer creates volumes by itself, so declare them or you lose that data when the container is recreated. The readme also lists volumes for files, web customisation and backups.

Move from LAN-only to internet access

To manage laptops outside the office, give the server a DNS name that resolves from the internet and put it in config.json:

{
  "settings": {
    "cert": "mesh.example.com",
    "port": 443,
    "redirPort": 80
  },
  "domains": {
    "": { "title": "IT Remote", "newAccounts": false }
  },
  "letsencrypt": {
    "email": "it@example.com",
    "names": "mesh.example.com",
    "production": true
  }
}

Restart the service and confirm that ports 80 and 443 reach the server; Let’s Encrypt needs both for issuing the certificate. Setting newAccounts to false stops strangers from registering their own accounts. If you use Intel AMT CIRA, TCP 4433 is also needed.

Agents carry the server address inside the installer. Installers built before you changed the name will not find the new one, so download fresh agents after any hostname change.

Groups and agents

MeshCentral organises computers into device groups, and rights are granted per group or per device. A practical layout is one group per customer or per office.

1. In the web console create a device group, for example “Office PCs”.
2. Click Add Agent, choose the operating system and download the installer, or copy the one-line install command shown for Linux.
3. Run it on the target computer with administrator or root rights. The device should appear in the group within about a minute.
4. Open the device and use the Desktop, Terminal or Files tabs.

Beyond remote control, the console offers power actions (wake, sleep, restart), an events log and optional local session recording. On Intel vPro hardware, AMT support can reach a machine even when its operating system is down.

Choosing a database

MeshCentral uses the built-in NeDB database by default, which is fine for a small fleet. For larger setups it can use MongoDB, PostgreSQL or MySQL/MariaDB. Pick the external database before you enrol a large number of devices, and include it in your backups.

Updates and hardening

• Back up the meshcentral-data folder before every upgrade. It holds certificates, configuration and, with the default database, your device data.
• Administrators can upgrade from the web interface when self-update is allowed, or reinstall the newer npm package and restart the service.
• The npm registry can lag behind GitHub releases by a few days. On 1 October 2026 npm still offered 1.2.5 while GitHub had 1.2.6.
• The documentation recommends running the server under a dedicated low-privilege user. That turns off self-update and requires an external database, so updates become manual.
• Turn on two-factor authentication for administrators and keep new account registration disabled.

For a wider checklist, see our remote access security checklist.

Limitations

• You own TLS, backups, updates and uptime. A public server with an unclaimed first-account screen is a real risk.
• The configuration file has hundreds of options and few guard rails.
• There is no vendor support contract; help comes from documentation, GitHub issues and the community.
• Remote desktop suits support work, not video or graphics-heavy use.
• Releases are frequent, so read the release notes before upgrading a production server.

MeshCentral or something else?

More options are covered in our self-hosted remote access overview.

FAQ

What is the MeshCentral default login?

There is none. The first account created on a new server becomes the administrator, so create it right after the first start.

Where do I download MeshCentral?

The server is installed with npm install meshcentral, or from the official Docker images. Agents are downloaded from your own server’s web console after you create a device group.

How do I install MeshCentral on Ubuntu or Debian?

Install Node.js 20 or newer using the nodejs.org instructions, then follow the npm steps above as a normal user and add --install to run it as a service.

Can I run MeshCentral in Docker?

Yes. Use ghcr.io/ylianst/meshcentral with the tag for your database and keep meshcentral-data on a persistent volume.

Why does my MeshCentral agent not connect?

Check that the server name resolves from the device and that ports 80 and 443 are reachable. If you changed the hostname, the old installer still points at the old name; download a new agent.

MeshCentral vs RustDesk: which is better?

MeshCentral is a browser-based console for managing your own fleet; RustDesk is a desktop client built for quick ID-based sessions. Many admins use MeshCentral for unattended computers and RustDesk for ad-hoc help.

Last updated: 9 October 2026 · CtrlRemote editorial team. Licence, version and platform details are checked against each developer's official documentation.