Install MeshCentral: Self-hosted with Docker, Let's Encrypt and Hardening (2026)

Rather not run MeshCentral yourself? WZ-IT installs and operates MeshCentral as a managed platform with monitoring, updates and backups. See MeshCentral managed hosting

MeshCentral is a free, open-source web platform for remote computer management: remote desktop, terminal and file management in the browser, through a server you run yourself (docs.meshcentral.com). The official installation guide is based on npm, and Docker guides on the web point to various community images. This guide covers the path with the official container image, TLS through the built-in Let's Encrypt support and a hardened baseline configuration. As of October 2026, MeshCentral 1.2.6 (24 Sep 2026) is current.

Table of contents

• What is MeshCentral?
• MeshCentral or RustDesk?
• Official Docker image instead of community images
• Installation with Docker Compose
• config.json with Let's Encrypt
• Let's Encrypt: staging first, then production
• With a reverse proxy in front
• Rolling out agents
• Hardening
• Backup and updates
• Maintenance status and risk
• How WZ-IT approaches it
• Further guides

What is MeshCentral?

MeshCentral consists of a Node.js-based server and an agent on the managed devices. The agent opens an outbound connection to the server and keeps it open; technicians sign in to the web console and work from there with remote desktop, terminal and file transfer (MeshCentral Guide). The technician only needs a browser.

MeshCentral is also embedded in other tools: Tactical RMM uses it for remote control (Take Control) and the real-time file browser and installs its own MeshCentral instance for this.

MeshCentral or RustDesk?

Both can be self-hosted, but they solve different problems. The full comparison including Apache Guacamole and NetBird is in Self-hosted TeamViewer alternative.

For a fixed fleet of workstations and servers, MeshCentral fits; for ad-hoc support with changing counterparts, RustDesk fits.

Official Docker image instead of community images

The official image is built from the MeshCentral repository and published in the GitHub Container Registry as ghcr.io/ylianst/meshcentral (container docs, package page):

Images on Docker Hub such as typhonragewind/meshcentral come from the community; there is no image under ylianst on Docker Hub. For production, pin a version tag instead of latest so updates happen deliberately.

One quirk of the official image: environment variables such as HOSTNAME or ALLOW_NEW_ACCOUNTS only take effect with DYNAMIC_CONFIG=true, which is off by default (Docker README). Without an existing config.json, the container copies a template on first start in which NewAccounts is set to true (entrypoint.sh). Write the config.json yourself before the container starts for the first time.

Installation with Docker Compose

The setup below follows the official Compose example: ports 80 and 443 are published directly, MeshCentral terminates TLS itself and obtains the certificate through its built-in Let's Encrypt support. Deviations from the example: a pinned version tag, bind mounts instead of named volumes (easier to back up and edit) and a separate directory for session recordings. meshcentral-web is only needed for custom themes and is left out here (Docker README).

services:
  meshcentral:
    image: ghcr.io/ylianst/meshcentral:1.2.6
    container_name: meshcentral
    restart: unless-stopped
    environment:
      - DYNAMIC_CONFIG=false
    volumes:
      - ./meshcentral-data:/opt/meshcentral/meshcentral-data
      - ./meshcentral-files:/opt/meshcentral/meshcentral-files
      - ./meshcentral-backups:/opt/meshcentral/meshcentral-backups
      - ./meshcentral-recordings:/opt/meshcentral/meshcentral-recordings
    ports:
      - "80:80"
      - "443:443"

Steps:

1. Point the DNS record mesh.example.com at the server's public IP and open TCP 80 and 443 to the outside. Port 80 is mandatory: Let's Encrypt validates the domain with the HTTP-01 challenge, which MeshCentral's HTTP server answers on port 80 (SSL/Let's Encrypt). The docs recommend having the DNS record in place for more than a day before requesting the certificate; letsdebug.net checks the domain beforehand (Let's Encrypt section).
2. Create the meshcentral-data directory and place the config.json from the next section in it, initially with "production": false.
3. Run docker compose up -d and follow the log: docker compose logs -f meshcentral. MeshCentral requests the certificate on startup and restarts automatically once it arrives; the request can take a few minutes to a few hours (Let's Encrypt section).
4. Open https://mesh.example.com right away and create the first account. It automatically becomes server administrator (Quickstart). The browser shows a warning in this phase: first MeshCentral serves a self-signed certificate, then one from the staging CA, whose root certificates are not in any browser trust store (Let's Encrypt staging).
5. Switch to the production certificate, see Let's Encrypt: staging first, then production.

Step 4 is time-critical: as long as no account exists, MeshCentral allows registration even with newAccounts: false (webserver.js). If you want to expose the server later, set userAllowedIP to your own IP first (see Hardening).

config.json with Let's Encrypt

The values follow the Let's Encrypt section of the docs and the configuration schema. Key names are case-insensitive (Guide, Annex 1); letsEncrypt is the spelling used in the schema, the docs write letsencrypt.

{
  "$schema": "https://raw.githubusercontent.com/Ylianst/MeshCentral/master/meshcentral-config-schema.json",
  "settings": {
    "cert": "mesh.example.com",
    "WANonly": true,
    "port": 443,
    "redirPort": 80,
    "selfUpdate": false,
    "autoBackup": {
      "backupIntervalHours": 24,
      "keepLastDaysBackup": 10,
      "zipPassword": "a-long-random-password"
    }
  },
  "domains": {
    "": {
      "title": "Remote support",
      "newAccounts": false,
      "passwordRequirements": { "force2factor": true },
      "sessionRecording": { "protocols": [1, 2, 5], "index": true }
    }
  },
  "letsEncrypt": {
    "email": "[email protected]",
    "names": "mesh.example.com",
    "rsaKeySize": 3072,
    "production": false
  }
}

Changes to config.json only take effect after a restart (docker compose restart meshcentral).

Let's Encrypt: staging first, then production

Too many failed requests against the production server lead to a ban for a longer period; the docs therefore require a successful staging certificate first (schema, Let's Encrypt section). Once the browser shows a certificate signed by the staging CA at https://mesh.example.com, switch over:

1. docker compose stop meshcentral
2. Remove the Let's Encrypt files in meshcentral-data. The docs call the folder letsencrypt; current versions store the files in meshcentral-data/letsencrypt-certs (letsencrypt.js).
3. Set "production": true in config.json.
4. docker compose start meshcentral

According to the docs, the production certificate arrives within a few minutes to a few hours. MeshCentral then checks the certificate every 24 hours and requests a new one as soon as less than 45 days remain (letsencrypt.js); certbot or a restart hook is not needed. Port 80 has to stay reachable for this. If the request fails, MeshCentral falls back to the self-signed certificate (Let's Encrypt section).

If the DNS zone runs through Cloudflare, the proxy mode must be off for the record; otherwise the remote desktop stays black (FAQ).

With a reverse proxy in front

If nginx, Traefik or HAProxy need to sit in front of MeshCentral, for example because other services on the same server use port 443, follow the official guide: nginx, Traefik, HAProxy. The proxy then terminates TLS, and config.json needs tlsOffload, aliasPort and certUrl (TLS offloading). Because agents keep long-lived WebSocket connections, the proxy needs long timeouts.

Rolling out agents

Agents are generated per device group in the web console: create a group, choose "Add Agent", select the operating system and installation type (background, interactive or both) (MeshCentral Guide).

• Windows: according to the docs, the downloaded .exe contains no sensitive data and can be reused on many machines. It installs unattended with -fullinstall (copies the agent to C:\Program Files\Mesh Agent, installs and starts the service; MeshAgent source). That makes it deployable through existing software distribution; the official docs do not describe a dedicated GPO or MSI path for the agent.
• Linux and BSD: instead of a binary, the console provides an installation script that picks the right agent variant itself.
• macOS: screen recording, file access and keyboard/mouse control must be granted manually under Privacy & Security (FAQ).

# Windows, as administrator; adjust the file name to your download
.\meshagent.exe -fullinstall

Antivirus products that submit unknown files for analysis sometimes run the agent in their sandbox; unknown devices then show up in the console (FAQ). agentAllowedIPNewAgents (since 1.2.6, PR #8140) restricts new agent enrollments to known address ranges.

Hardening

• No self-registration: newAccounts: false and create the first account immediately, see Installation.
• Enforce 2FA: MeshCentral supports TOTP apps, YubiKey OTP and Duo (two-step docs, Security); passwordRequirements.force2factor makes 2FA mandatory for all accounts. Note: after a password recovery via email, 2FA is turned off again, so the email account becomes part of the attack surface.
• Sign-in only from the VPN: userAllowedIP restricts user sign-in to address ranges, agentAllowedIP does the same for agents (schema). A proven pattern: agents connect over the internet, while the web console is only reachable from a mesh VPN such as NetBird. If a reverse proxy sits in front, tlsOffload must point to its IP so MeshCentral trusts the forwarded headers and sees the real source IP. NetBird basics: What is NetBird?.
• Login throttling: maxInvalidLogin blocks after 10 failed attempts in 10 minutes by default; since 1.2.6 also by IP range or username.
• Session recording: sessionRecording as above; recordings contain screen content and belong in a deletion and access concept. More in Privileged access management and session recording.
• Rights per device group: grant technicians access only to the groups they look after; keep server administrator rights to a few accounts.

Self-hosting alone does not make remote support GDPR-compliant. Legal basis, data processing agreements with service providers and rules on recording and logging remain the operator's responsibility, see Remote maintenance and GDPR. This section is general information, not legal advice.

Backup and updates

Backup. Back up meshcentral-data and meshcentral-files (backup docs). meshcentral-data contains the server certificates that installed agents are bound to: if the folder is lost, agents will not connect to a reinstalled server, even under the same name. Anyone holding a copy can impersonate the server, so the backup belongs encrypted in a second location. autoBackup creates a ZIP in meshcentral-backups every 24 hours by default and keeps 10 days; with zipPassword it is password-protected (schema). With MongoDB, add a mongodump.

Updates. In the container, do not use the built-in update function; replace the image instead (container docs): set the tag in compose.yaml to the new version, then

docker compose pull
docker compose up -d

Releases and changelogs are on GitHub. 1.2.6 included security fixes, among them enforcing the "no files" permission on the file download endpoint and verifying agent signatures even when ignoreAgentHashCheck is set (release notes). For air-gapped networks, pull the image outside and transfer it with docker save and docker load.

Maintenance status and risk

MeshCentral is actively developed: twelve releases have shipped in 2026 up to October, from 1.1.56 (21 Jan 2026) to 1.2.6 (24 Sep 2026) (releases). Development is now carried mainly by one person: of the 373 commits in 2026 (as of 14 Oct 2026), 188 come from community maintainer si458 and 13 from founder Ylian Saint-Hilaire, mostly version commits (commit history). There is no commercial vendor with a support contract behind it.

For operations this means: watch releases, apply updates promptly and know a fallback in case maintenance slows down. The Apache-2.0 licence allows forks; agents and server keep working without new releases but then receive no security fixes.

How WZ-IT approaches it

We install and operate MeshCentral as a managed platform: at WZ-IT, in your cloud, on-premises or hybrid, with monitoring, updates, backups of meshcentral-data and a planned recovery procedure. We prefer to put the web console behind a mesh VPN such as NetBird so it is not publicly reachable.

If a company needs more than remote control, for example remote maintenance of plants with roles, audit and tenants, we build it as a remote management platform or as remote maintenance software for machines and sites.

Further guides

• Self-hosted TeamViewer alternative - RustDesk, MeshCentral, Guacamole and NetBird compared
• What is NetBird? - mesh VPN to take the console off the internet
• Privileged access management and session recording
• Remote maintenance and GDPR - data processing in remote maintenance
• Remote maintenance without a VPN client

Setting up MeshCentral or handing over an existing installation? Get to know us or see MeshCentral managed hosting.