Skip to content

Commit f00b5e4

Browse files
andloandlo
committed
Initial commit: MeshCentral Home Assistant add-on
0 parents  commit f00b5e4

9 files changed

Lines changed: 303 additions & 0 deletions

File tree

‎.github/workflows/build.yaml‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
name: Build and publish add-on
2+
3+
on:
4+
push:
5+
branches: [main]
6+
paths:
7+
- "meshcentral/**"
8+
release:
9+
types: [published]
10+
11+
jobs:
12+
build:
13+
name: Build ${{ matrix.arch }}
14+
runs-on: ubuntu-latest
15+
strategy:
16+
matrix:
17+
arch: [aarch64, amd64, armhf, armv7, i386]
18+
steps:
19+
- name: Checkout
20+
uses: actions/checkout@v4
21+
22+
- name: Login to GitHub Container Registry
23+
uses: docker/login-action@v3
24+
with:
25+
registry: ghcr.io
26+
username: ${{ github.actor }}
27+
password: ${{ secrets.GITHUB_TOKEN }}
28+
29+
- name: Build and push
30+
uses: home-assistant/builder@2024.03.5
31+
with:
32+
args: |
33+
--${{ matrix.arch }} \
34+
--target /data/meshcentral \
35+
--image "ha-meshcentral-addon/meshcentral" \
36+
--docker-hub "ghcr.io/andlo" \
37+
--version ${{ github.ref_name }}

‎.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
.git/
2+
*.log
3+
node_modules/
4+
meshcentral-data/

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 Andreas Lorensen
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
# MeshCentral Add-on for Home Assistant
2+
3+
[![GitHub Release](https://img.shields.io/github/release/andlo/ha-meshcentral-addon.svg)](https://github.com/andlo/ha-meshcentral-addon/releases)
4+
[![License](https://img.shields.io/github/license/andlo/ha-meshcentral-addon.svg)](LICENSE)
5+
6+
Run [MeshCentral](https://meshcentral.com) as a Home Assistant add-on — the free, open-source remote device management platform. Monitor and control all your Windows, Linux and macOS computers directly from Home Assistant.
7+
8+
## What is MeshCentral?
9+
10+
MeshCentral lets you remotely monitor, manage and control computers — think of it as your own private TeamViewer or AnyDesk, completely self-hosted, no subscriptions, no cloud dependency.
11+
12+
When combined with the [MeshCentral HA integration](https://github.com/andlo/ha-meshcentral), your PCs become first-class citizens in your smart home:
13+
14+
- See online/offline status in real-time
15+
- Wake, reboot, sleep, hibernate or shut down devices from HA
16+
- Automate based on PC state (turn on desk lamp when PC comes online, cut power when it shuts down)
17+
- Monitor Windows Defender, firewall and antivirus status
18+
- Hardware sensors: CPU, GPU, RAM, disk
19+
20+
## Installation
21+
22+
### Step 1 — Add this repository to HA
23+
24+
1. Go to **Settings → Add-ons → Add-on Store**
25+
2. Click ⋮ → **Repositories**
26+
3. Add: `https://github.com/andlo/ha-meshcentral-addon`
27+
4. Find and install **MeshCentral**
28+
29+
### Step 2 — First-time setup
30+
31+
Before starting the add-on for the first time, you need to allow account creation:
32+
33+
1. Go to the add-on **Configuration** tab
34+
2. Note the `data_path` (default: `/data/meshcentral-data`)
35+
3. Start the add-on
36+
4. Open the MeshCentral web interface (see **Network** below)
37+
5. Create your admin account
38+
6. **Important:** After creating your account, stop the add-on and edit `/data/meshcentral-data/config.json` — set `"newAccounts": false` to prevent others from registering
39+
40+
### Step 3 — Install the HA integration
41+
42+
Install the [MeshCentral integration](https://github.com/andlo/ha-meshcentral) via HACS to connect HA entities to your MeshCentral server.
43+
44+
Use these settings in the integration:
45+
- **Host:** `homeassistant.local` (or your HA IP)
46+
- **Port:** `4430`
47+
- **Use SSL:** off (the add-on uses tlsOffload — HA handles TLS)
48+
- **Verify SSL:** off
49+
50+
### Step 4 — Install agents on your computers
51+
52+
Download and install the MeshCentral agent on each computer you want to manage:
53+
54+
1. Log in to MeshCentral web interface
55+
2. Go to **My Devices → Add Device**
56+
3. Download and run the installer on each PC
57+
58+
## Network
59+
60+
### Local network only (simplest)
61+
62+
The add-on is accessible on your local network at:
63+
`http://homeassistant.local:4430`
64+
65+
Agents on the same network will connect automatically.
66+
67+
### External access via Nabu Casa (recommended)
68+
69+
If you have [Nabu Casa](https://www.nabucasa.com/) (Home Assistant Cloud):
70+
71+
1. Enable **Remote Access** in Nabu Casa
72+
2. Your MeshCentral will be accessible at your Nabu Casa URL
73+
3. Agents outside your home network can connect via the Nabu Casa URL
74+
75+
### External access via Cloudflare Tunnel (free, no port-forwarding)
76+
77+
1. Set up a [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) pointing to `http://homeassistant.local:4430`
78+
2. In MeshCentral's config.json, set your tunnel URL as the `hostname`
79+
3. Agents anywhere in the world can now connect
80+
81+
### Port forwarding (traditional)
82+
83+
Forward port `4430` on your router to your HA host IP.
84+
85+
## Configuration
86+
87+
| Option | Default | Description |
88+
|--------|---------|-------------|
89+
| `data_path` | `/data/meshcentral-data` | Where MeshCentral stores its data |
90+
| `hostname` | *(auto)* | Public hostname for agent connections — set this to your external URL (Cloudflare, Nabu Casa etc.) |
91+
| `allow_device_sharing` | `false` | Allow device sharing with other users |
92+
93+
## Ports
94+
95+
| Port | Description |
96+
|------|-------------|
97+
| `4430/tcp` | MeshCentral web interface |
98+
99+
## Updating MeshCentral
100+
101+
The add-on bundles a specific version of MeshCentral. When a new version of the add-on is released, update it via the HA add-on store. Your data and agent connections are preserved across updates.
102+
103+
## Backup
104+
105+
MeshCentral data is stored in `/data/meshcentral-data` which is included in HA's standard backup. All device connections, users, and settings are backed up automatically.
106+
107+
## Troubleshooting
108+
109+
**Agents can't connect from outside my network:**
110+
Set the `hostname` option to your external URL (Cloudflare tunnel, DuckDNS, Nabu Casa URL).
111+
112+
**Can't create account:**
113+
Temporarily set `"newAccounts": true` in `/data/meshcentral-data/config.json` and restart the add-on. Remember to set it back to `false` after.
114+
115+
**MeshCentral integration shows "invalid_auth":**
116+
If your account has 2FA enabled, create a Login Token in MeshCentral → My Account → Login Tokens and use those credentials in the HA integration.
117+
118+
## Related
119+
120+
- [MeshCentral HA Integration](https://github.com/andlo/ha-meshcentral) — HACS integration for HA entities
121+
- [MeshCentral](https://meshcentral.com) — Official MeshCentral website
122+
- [MeshCentral GitHub](https://github.com/Ylianst/MeshCentral) — MeshCentral source code
123+
124+
## License
125+
126+
MIT

‎meshcentral/DOCS.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# MeshCentral
2+
3+
Run MeshCentral as a Home Assistant add-on — the free, open-source remote device management platform.
4+
5+
MeshCentral lets you remotely monitor, manage and control computers (Windows, Linux, macOS) from a single interface. Combined with the [MeshCentral HA integration](https://github.com/andlo/ha-meshcentral), your PCs become smart home devices — online/offline sensors, Wake-on-LAN, power control, Windows security monitoring and more.
6+
7+
## Quick start
8+
9+
1. Install this add-on and start it
10+
2. Open the web interface and create your admin account
11+
3. Install the [MeshCentral HA integration](https://github.com/andlo/ha-meshcentral) via HACS
12+
4. Connect the integration to `homeassistant.local:4430` with SSL off
13+
5. Install MeshCentral agents on your computers
14+
15+
Full documentation: [GitHub](https://github.com/andlo/ha-meshcentral-addon)

‎meshcentral/Dockerfile‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
ARG BUILD_FROM
2+
FROM $BUILD_FROM
3+
4+
# Install Node.js (required for MeshCentral)
5+
RUN apk add --no-cache nodejs npm
6+
7+
# Install MeshCentral
8+
RUN npm install -g meshcentral
9+
10+
# Copy startup script
11+
COPY run.sh /run.sh
12+
RUN chmod +x /run.sh
13+
14+
CMD ["/run.sh"]

‎meshcentral/config.yaml‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
{
2+
"name": "MeshCentral",
3+
"version": "0.1.0",
4+
"slug": "meshcentral",
5+
"description": "Self-hosted remote device management — monitor and control your PCs from Home Assistant",
6+
"url": "https://github.com/andlo/ha-meshcentral-addon",
7+
"arch": ["aarch64", "amd64", "armhf", "armv7", "i386"],
8+
"startup": "application",
9+
"boot": "auto",
10+
"ports": {
11+
"443/tcp": 4430
12+
},
13+
"ports_description": {
14+
"443/tcp": "MeshCentral web interface (HTTPS)"
15+
},
16+
"options": {
17+
"data_path": "/data/meshcentral-data",
18+
"hostname": "",
19+
"allow_device_sharing": false
20+
},
21+
"schema": {
22+
"data_path": "str",
23+
"hostname": "str",
24+
"allow_device_sharing": "bool"
25+
},
26+
"map": [
27+
"data:rw"
28+
],
29+
"image": "ghcr.io/andlo/ha-meshcentral-addon/meshcentral",
30+
"homeassistant_api": false,
31+
"hassio_api": false
32+
}

‎meshcentral/run.sh‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
#!/usr/bin/with-contenv bashio
2+
3+
# Read config from HA add-on options
4+
HOSTNAME=$(bashio::config 'hostname')
5+
DATA_PATH=$(bashio::config 'data_path')
6+
ALLOW_SHARING=$(bashio::config 'allow_device_sharing')
7+
8+
# Use HA hostname if not set
9+
if [ -z "$HOSTNAME" ]; then
10+
HOSTNAME=$(bashio::info.hostname)
11+
fi
12+
13+
bashio::log.info "Starting MeshCentral..."
14+
bashio::log.info "Hostname: ${HOSTNAME}"
15+
bashio::log.info "Data path: ${DATA_PATH}"
16+
17+
# Create data directory
18+
mkdir -p "${DATA_PATH}"
19+
20+
# Generate config.json if it doesn't exist
21+
CONFIG_FILE="${DATA_PATH}/config.json"
22+
if [ ! -f "$CONFIG_FILE" ]; then
23+
bashio::log.info "Creating initial MeshCentral config..."
24+
cat > "$CONFIG_FILE" << EOF
25+
{
26+
"settings": {
27+
"port": 443,
28+
"redirPort": 80,
29+
"tlsOffload": true,
30+
"_comment_tlsOffload": "Set to true because HA handles TLS via Ingress/Nabu Casa",
31+
"selfUpdate": false,
32+
"cleanErrorLog": 5
33+
},
34+
"domains": {
35+
"": {
36+
"title": "MeshCentral",
37+
"title2": "Home Assistant",
38+
"newAccounts": false,
39+
"_comment_newAccounts": "Set to true only to create your first admin account, then set back to false",
40+
"mstsc": false
41+
}
42+
}
43+
}
44+
EOF
45+
bashio::log.info "Config created. NOTE: Set 'newAccounts: true' temporarily to create your first admin account!"
46+
fi
47+
48+
# Start MeshCentral
49+
exec node /usr/lib/node_modules/meshcentral --datapath "${DATA_PATH}"

‎repository.json‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
{
2+
"name": "MeshCentral",
3+
"url": "https://github.com/andlo/ha-meshcentral-addon",
4+
"maintainer": "Andreas Lorensen <andlo@outlook.dk>"
5+
}

0 commit comments

Comments
 (0)