Self-hosting MeshCentral: the complete guide

MeshCentral is open-source remote management and control software: remote desktop, terminal, file transfer and multi-device management, all from a single web console. It is the self-hosted, subscription-free alternative to TeamViewer or AnyDesk.

Here we install it from scratch on a Linux server, configure it, secure it and connect the first device. By the end you will have a remote support setup entirely under your own control.

Who it is for: sysadmins and technicians with basic command-line familiarity. Every command is explained.

1. Why self-host

Self-hosting means the server is yours: data, connections and managed devices go through your machine, not a third party’s.

• No per-seat subscription.
• Full control over where the data lives and who can reach it.
• No client on your side: to provide support you only need the web console, from any computer.
• Customisation: the agent can carry your own name.

The flip side is that maintenance is yours: updates, backups and server security become your responsibility. That is the self-hosting bargain, and it is worth knowing before you sign it.

2. Prerequisites

Item	Detail
A VPS	Linux, preferably Ubuntu LTS. 1–2 vCPU and 2 GB of RAM is enough to start
A domain	A subdomain, for example support.yourdomain.com, pointed at the server
SSH access	With a non-root user that can sudo

MeshCentral is light: the requirement grows with the number of devices connected at the same time, not with how many are registered.

The DNS record, first of all

Create an A record pointing the subdomain at the server’s public address:

Type:  A
Name:  support
Value: YOUR_IP

Wait for propagation, then check from your own machine:

nslookup support.yourdomain.com

It must answer with the server’s address. Correct DNS is not a detail to sort out later: MeshCentral generates its own certificate from the host name, so if the name does not resolve, the certificate is born wrong.

3. Prepare the server

Connect and update:

ssh user@YOUR_IP
sudo apt update && sudo apt upgrade -y

A dedicated user, not root

MeshCentral must not run as root. Create a system user that will run the service with minimal privileges:

sudo useradd -r -m -d /opt/meshcentral -s /bin/bash meshcentral

• -r creates a system user, not meant for interactive login
• -m -d /opt/meshcentral gives it the directory we will install into as its home
• -s /bin/bash gives it a shell, needed for maintenance commands

4. Install Node.js

MeshCentral is written in Node.js. The cleanest route is the official NodeSource repository:

curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt install -y nodejs

Check it:

node --version
npm --version

Two version numbers and Node is ready.

5. Install MeshCentral

Install it as the dedicated user, inside its own directory:

sudo -u meshcentral -i
cd /opt/meshcentral
npm install meshcentral

Then a first manual start, which generates the configuration and certificates:

node node_modules/meshcentral --cert support.yourdomain.com

--cert tells MeshCentral which host name to generate the certificate for. On first start it creates the meshcentral-data directory — where configuration, certificates and database live — and begins listening. Once you see it running, stop it with Ctrl+C: we will configure it properly and then turn it into a service.

exit

6. config.json, field by field

The heart of the configuration is /opt/meshcentral/meshcentral-data/config.json.

sudo -u meshcentral tee /opt/meshcentral/meshcentral-data/config.json >/dev/null <<'EOF'
{
  "settings": {
    "cert": "support.yourdomain.com",
    "port": 443,
    "redirPort": 80,
    "WANonly": true
  },
  "domains": {
    "": {
      "title": "Remote Support",
      "title2": "Powered by MeshCentral",
      "newAccounts": true
    }
  }
}
EOF

Field	What it does
cert	The server’s host name. Must match the DNS record
port	The HTTPS console port
redirPort	The HTTP port that redirects to HTTPS
WANonly	true when the server is only reachable from the internet, typical of a VPS
title / title2	The text shown in the console
newAccounts	true temporarily, to create the first administrator. Closed immediately afterwards

Always validate the JSON before going on — a syntax error prevents startup, and the message you get talks about something else:

sudo cat /opt/meshcentral/meshcentral-data/config.json | python3 -m json.tool >/dev/null && echo "JSON VALID" || echo "JSON ERROR"

7. The systemd service

So it starts on boot and comes back after a crash:

sudo tee /etc/systemd/system/meshcentral.service >/dev/null <<'EOF'
[Unit]
Description=MeshCentral Server
After=network.target

[Service]
Type=simple
User=meshcentral
WorkingDirectory=/opt/meshcentral
ExecStart=/usr/bin/node /opt/meshcentral/node_modules/meshcentral
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

Three lines carry the weight: User=meshcentral runs the service as the dedicated user rather than root, Restart=always brings it back if it stops, WantedBy=multi-user.target starts it at boot.

sudo systemctl daemon-reload
sudo systemctl enable meshcentral
sudo systemctl start meshcentral
sudo systemctl status meshcentral

It must read active (running). For live logs:

sudo journalctl -u meshcentral -f

Permission to use low ports

Ports below 1024 need privileges, and the service runs as an unprivileged user. Rather than granting it root, you grant Node only what it needs:

sudo setcap 'cap_net_bind_service=+ep' $(which node)
sudo systemctl restart meshcentral

8. Firewall

Open the minimum:

sudo ufw allow 22/tcp     # SSH
sudo ufw allow 80/tcp     # HTTP, redirects to HTTPS
sudo ufw allow 443/tcp    # HTTPS: console and agents
sudo ufw enable
sudo ufw status

Match the ports to what you chose in config.json. Every open port is one more attack surface: if you are not using a specific feature, such as Intel AMT on 4433, do not open its port.

9. First login and hardening

Open https://support.yourdomain.com.

The first account created becomes the administrator. Create it now, then secure it with three steps that are not optional.

sudo -u meshcentral sed -i 's/"newAccounts": true/"newAccounts": false/' /opt/meshcentral/meshcentral-data/config.json
sudo systemctl restart meshcentral

10. The first device

The logic is: create a device group, then add machines to it by installing the agent.

From there you open remote desktop, terminal or file transfer, all in the browser. It is the machines being supported that receive the agent, not yours.

User consent

Each group has a consent level. On client machines the right choice is explicit consent — the user accepts before you connect — plus a notification bar visible during the session.

This is not merely courtesy: the person must know when someone is on their computer. Reserve the no-consent mode for your own machines and the lab.

11. Service mode or Assistant: what decides your capabilities

This part is not in the official documentation, and it explains most of the frustrations that follow.

On Windows, MeshCentral has two ways of living on a machine.

	Agent installed as a service	Portable Assistant
Runs as	LOCAL SYSTEM	the launching user
Elevated terminal	yes	no
UAC prompt / Secure Desktop	yes	no: input fields are not transferred
Admin operations on a standard user	yes	no, not even “run as administrator”
Installation	permanent	none

The ten-second test

Open the Terminal tab on a device and type:

whoami

Response	Meaning
nt authority\system	The agent is a service: install, configure and elevate without ever touching a UAC prompt
PCNAME\user	Interactive mode: limited to that user’s privileges

12. Where files and clipboard went

A recurring question: “MeshCentral has no file transfer and no clipboard”. It has both.

Feature	Where it lives
File transfer	The Files tab, bidirectional drag and drop in the browser
Clipboard	Buttons in the Desktop toolbar: pull reads from the remote, push writes to it

If the Files tab does not appear, the permission is not granted: in the group, Edit user permissions, enable the Files flag.

Permissions are granular per group: a junior technician can get read-only desktop access, with file transfer denied entirely on certain clients.

13. Customisation and branding

The agent can carry your name instead of the generic one. It is set in config.json, inside the domain:

"agentCustomization": {
  "displayName": "YourName Support",
  "description": "Remote support service",
  "companyName": "YourName",
  "serviceName": "YourNameAgent"
}

• displayName — the name shown in Windows and in the installer
• companyName — also determines the install directory, C:\Program Files\YourName\
• serviceName — the technical service name

A second block, agentFileInfo, customises the file metadata you see under Properties → Details: productname, filedescription, companyname, legalcopyright.

14. Maintenance and updates

Back up before every significant change

Configuration, certificates and database all live in meshcentral-data. It is the only genuinely indispensable directory: save it and you can rebuild the server anywhere.

sudo cp -r /opt/meshcentral/meshcentral-data /opt/meshcentral/meshcentral-data.backup-$(date +%Y%m%d)

Updating

sudo systemctl stop meshcentral
sudo -u meshcentral bash -c 'cd /opt/meshcentral && npm install meshcentral@latest'
sudo systemctl start meshcentral
sudo systemctl status meshcentral

15. When something does not add up

Symptom	Where to look
The service will not start	sudo journalctl -u meshcentral -n 50. The most frequent cause is a syntax error in config.json: revalidate it with python3 -m json.tool
The console is unreachable	In order: is the service active? Is the port open in the firewall? Does the DNS record point at the right address? Are you using https:// and the right port?
The agent stays offline	The console port must be reachable from the internet: it is the same one agents use. Check the server’s clock too, since TLS is time-sensitive
Permission denied inside meshcentral-data	The files must belong to the dedicated user: sudo chown -R meshcentral:meshcentral /opt/meshcentral/meshcentral-data
Port conflict at startup	Another service occupies 443. Change port in config.json, update the firewall, use the new port in the URL
Customisation not applied	It only applies to agents downloaded after the change. Reinstall the agent

Frequently asked questions

Is MeshCentral free for commercial use? Yes. It ships under the Apache 2.0 licence: you may use it commercially, modify it and manage paying clients, with no per-device cost and no approval process.

How much VPS resource does it need? 1–2 vCPU and 2 GB of RAM is enough to start. The requirement grows with the number of devices connected at the same time, not with how many are registered.

Do I need a reverse proxy in front of MeshCentral? No, and this guide does not use one: MeshCentral handles TLS itself and binds 443 directly. A proxy is needed when other services on the VPS have to share that port, and in that case the configuration changes considerably.

Why does the browser say the certificate is untrusted? Because it is self-signed. That does not compromise agent security, since agents pin the certificate, but the browser will keep warning you. MeshCentral also supports Let’s Encrypt natively: that is the route to take if the warning bothers you.

Can I see and click UAC prompts remotely? Only when the agent is installed as a service, running as LOCAL SYSTEM. Not with the portable Assistant: that is a Windows limitation, not a MeshCentral one. Check with whoami in the Terminal.

Does MeshCentral support file transfer and clipboard? Yes, both. Files in the Files tab, clipboard in the Desktop toolbar buttons. A missing Files tab means a missing permission on the group.

Can I brand the agent with my own name? Yes, with agentCustomization and agentFileInfo in config.json. Do it before deploying agents: already-installed ones do not update themselves.

---

For information only. Use MeshCentral in line with applicable law and, when supporting third-party devices, always with informed consent.