MeshCentral is an open-source, self-hosted platform for managing computers remotely from a web browser. Devices run a small agent that connects back to your server, and from the web interface you get remote desktop, a terminal, file transfer and device inventory without routing traffic through a third party. In this tutorial you will install MeshCentral on Ubuntu 24.04, run it as a systemd service with a Let's Encrypt certificate, create the administrator account and enroll a Linux device.

Prerequisites

To follow this tutorial, you will need:

  • A server running Ubuntu 24.04 LTS, for example a CubePath VPS with at least 1 vCPU and 2 GB of RAM, and a non-root user with sudo privileges.
  • A domain name such as mesh.your_domain with a DNS A record pointing to your_server_ip. Let's Encrypt needs it to issue the certificate.
  • Ports 80 and 443 free on the server. MeshCentral serves HTTPS itself, so do not run another web server on those ports.

Step 1 - Installing Node.js

MeshCentral is a Node.js application distributed through npm. The Node.js version in Ubuntu 24.04 (18.x) is supported, so install it from the distribution repositories:

sudo apt update
sudo apt install nodejs npm

Verify the installation:

node --version
npm --version

v18.19.1
9.2.0

Step 2 - Installing MeshCentral under a dedicated user

Run MeshCentral as an unprivileged system user whose home directory holds the installation:

sudo useradd --system --create-home --home-dir /opt/meshcentral --shell /usr/sbin/nologin meshcentral

Install the meshcentral package into that directory as the new user. MeshCentral installs extra npm modules on demand at runtime, so the user must own its own directory:

sudo -u meshcentral -H bash -c 'cd /opt/meshcentral && npm install meshcentral'

When the command finishes, the application is in /opt/meshcentral/node_modules/meshcentral. Create the data directory where the configuration, certificates and database will live:

sudo -u meshcentral mkdir /opt/meshcentral/meshcentral-data

Step 3 - Writing the configuration

MeshCentral reads meshcentral-data/config.json. Create it as the meshcentral user:

sudo -u meshcentral nano /opt/meshcentral/meshcentral-data/config.json

Replace mesh.your_domain and admin@your_domain with your own values:

{
  "settings": {
    "cert": "mesh.your_domain",
    "port": 443,
    "redirPort": 80
  },
  "domains": {
    "": {
      "title": "Remote Management"
    }
  },
  "letsencrypt": {
    "email": "admin@your_domain",
    "names": "mesh.your_domain",
    "production": false
  }
}

What each setting does:

  • cert: the hostname agents and browsers use to reach the server. Agents are bound to this name, so choose it carefully before enrolling devices.
  • port and redirPort: MeshCentral serves HTTPS on 443 and redirects HTTP on 80, which Let's Encrypt also uses for its challenge.
  • letsencrypt.production: false uses the Let's Encrypt staging environment, which has generous rate limits for testing. You will switch it to true in Step 6.

Validate the JSON syntax before continuing:

python3 -m json.tool /opt/meshcentral/meshcentral-data/config.json > /dev/null && echo "config OK"

config OK

Step 4 - Creating the systemd service

Create a unit file so MeshCentral starts at boot and restarts on failure. AmbientCapabilities lets the unprivileged user bind ports 80 and 443:

sudo nano /etc/systemd/system/meshcentral.service

[Unit]
Description=MeshCentral Server
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=meshcentral
Group=meshcentral
WorkingDirectory=/opt/meshcentral
ExecStart=/usr/bin/node /opt/meshcentral/node_modules/meshcentral
Environment=NODE_ENV=production
AmbientCapabilities=CAP_NET_BIND_SERVICE
LimitNOFILE=1000000
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Open the firewall, keeping SSH allowed:

sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable

Start the service and follow its log:

sudo systemctl daemon-reload
sudo systemctl enable --now meshcentral
sudo journalctl -u meshcentral -f

The first start takes a minute or two because MeshCentral generates its internal certificates and installs additional modules. Wait until the log reports that the HTTPS server is running on port 443, then press Ctrl+C. Confirm both ports are listening:

sudo ss -tlnp | grep -E ':(80|443) '

Step 5 - Creating the administrator account

Open https://mesh.your_domain in a browser. With the staging certificate your browser shows a warning; accept it for now. Click Create one to register an account.

The first account created on a new server becomes the full administrator, so do this immediately after the service starts. Use a strong password, then log in.

Once your account exists, prevent anyone else from registering. Add newAccounts to the default domain in config.json:

sudo -u meshcentral nano /opt/meshcentral/meshcentral-data/config.json

  "domains": {
    "": {
      "title": "Remote Management",
      "newAccounts": false
    }
  },

You will restart the service after the next step.

Step 6 - Switching to a production certificate

After you have confirmed the staging certificate was issued (the browser shows an issuer containing "STAGING"), switch to the production Let's Encrypt environment by setting production to true:

  "letsencrypt": {
    "email": "admin@your_domain",
    "names": "mesh.your_domain",
    "production": true
  }

Validate the file again and restart:

python3 -m json.tool /opt/meshcentral/meshcentral-data/config.json > /dev/null && echo "config OK"
sudo systemctl restart meshcentral

Reload https://mesh.your_domain after a minute. The browser should now show a valid certificate, and the registration link on the login page is gone. MeshCentral renews the certificate automatically.

Step 7 - Enrolling a device

Agents belong to device groups, which also control which users can manage which devices.

  1. In the web interface, go to My Devices and click Add Device Group. Give it a name, for example Servers, keep the type Manage using a software agent and click OK.
  2. Open the new group and click Add Agent.
  3. Select the Linux / BSD tab. MeshCentral shows an install command that already contains your server URL and the group identifier.

Run that command on the Linux machine you want to manage. It downloads an install script from your server, which installs the agent and registers it as the meshagent service. Verify it on the device:

systemctl status meshagent --no-pager

Back in the web interface, the device appears in the group within a few seconds. Click it to open the Terminal, Files and Desktop tabs. Desktop access requires a graphical session on the device; servers without one are managed through the terminal and file transfer.

For Windows and macOS, the same Add Agent dialog offers installers preconfigured for the group.

To give other people access, create their accounts under My Users, then open the device group and add them with only the rights they need, for example remote control without the ability to change group settings.

Step 8 - Backing up and updating

Everything that makes your server unique, including its identity certificates and the device database, lives in /opt/meshcentral/meshcentral-data. If you lose it, every agent must be reinstalled. Back it up regularly, for example:

sudo tar -czf ~/meshcentral-data-$(date +%F).tar.gz -C /opt/meshcentral meshcentral-data

To update MeshCentral, stop the service, install the latest package as the meshcentral user and start it again:

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

Troubleshooting

The service exits right after starting. Read the last log lines with sudo journalctl -u meshcentral -n 50. A JSON syntax error in config.json or another process already using port 80 or 443 are the most common causes. Check the ports with sudo ss -tlnp | grep -E ':(80|443) '.

No Let's Encrypt certificate is issued. The DNS A record must point to this server and port 80 must be reachable from the internet. Verify with dig +short mesh.your_domain and check the log for Let's Encrypt errors.

An agent installs but never appears online. The device must reach mesh.your_domain on port 443. From the device, run curl -I https://mesh.your_domain and check that it resolves and responds, then look at sudo journalctl -u meshagent.

Conclusion

MeshCentral is now running on Ubuntu 24.04 as a systemd service with a trusted certificate, a single administrator account and your first enrolled device. Next, organize devices into groups per team or customer, add users with limited rights, and schedule the backup of meshcentral-data so the server can be restored without re-enrolling agents.