Skip to content

Commit a3f2258

Browse files
andloandlo
committed
feat: add full HA addon UI configuration
All MeshCentral settings are now configurable directly from the Home Assistant add-on Configuration tab — no manual JSON editing needed. New options: server_mode (lan/wan/hybrid), domain_title, domain_title2, new_accounts, session_key, session_time, tls_offload, trusted_proxy, user_allowed_ip, user_blocked_ip, agent_allowed_ip, agent_blocked_ip, web_rtc, compression, self_update, maintenance_mode, smtp_enabled + full SMTP configuration (host, port, from, user, pass, tls). run.sh now regenerates config.json on every start from HA options. README updated with full configuration reference tables.
1 parent 824f020 commit a3f2258

3 files changed

Lines changed: 274 additions & 94 deletions

File tree

‎README.md‎

Lines changed: 92 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -26,18 +26,20 @@ When combined with the [MeshCentral HA integration](https://github.com/andlo/ha-
2626
3. Add: `https://github.com/andlo/ha-meshcentral-addon`
2727
4. Find and install **MeshCentral**
2828

29-
### Step 2 — First-time setup
29+
### Step 2 — Configure the add-on
3030

31-
Before starting the add-on for the first time, you need to allow account creation:
31+
All MeshCentral settings are available directly in the add-on **Configuration** tab in Home Assistant — no need to edit any JSON files manually.
3232

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
33+
See the full [Configuration reference](#configuration) below.
3934

40-
### Step 3 — Install the HA integration
35+
### Step 3 — Create your admin account
36+
37+
1. In the add-on **Configuration** tab, temporarily set `new_accounts` to `true`
38+
2. Start the add-on
39+
3. Open the MeshCentral web interface and create your admin account
40+
4. **Important:** Set `new_accounts` back to `false` and restart the add-on
41+
42+
### Step 4 — Install the HA integration
4143

4244
Install the [MeshCentral integration](https://github.com/andlo/ha-meshcentral) via HACS to connect HA entities to your MeshCentral server.
4345

@@ -47,9 +49,7 @@ Use these settings in the integration:
4749
- **Use SSL:** off (the add-on uses tlsOffload — HA handles TLS)
4850
- **Verify SSL:** off
4951

50-
### Step 4 — Install agents on your computers
51-
52-
Download and install the MeshCentral agent on each computer you want to manage:
52+
### Step 5 — Install agents on your computers
5353

5454
1. Log in to MeshCentral web interface
5555
2. Go to **My Devices → Add Device**
@@ -59,67 +59,122 @@ Download and install the MeshCentral agent on each computer you want to manage:
5959

6060
### Local network only (simplest)
6161

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.
62+
The add-on is accessible on your local network at `http://homeassistant.local:4430`. Set `server_mode` to `lan`.
6663

6764
### External access via Nabu Casa (recommended)
6865

6966
If you have [Nabu Casa](https://www.nabucasa.com/) (Home Assistant Cloud):
7067

7168
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
69+
2. Set `cert_url` to your Nabu Casa URL
70+
3. Agents outside your home network can now connect
7471

7572
### External access via Cloudflare Tunnel (free, no port-forwarding)
7673

7774
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`
75+
2. Set `server_mode` to `wan` and `cert_url` to your tunnel URL
7976
3. Agents anywhere in the world can now connect
8077

8178
### Port forwarding (traditional)
8279

83-
Forward port `4430` on your router to your HA host IP.
80+
Forward port `4430` on your router to your HA host IP. Set `server_mode` to `wan` and `cert_url` to your external URL.
8481

85-
## Data storage
82+
## Configuration
8683

87-
All MeshCentral data is kept under the configured `data_path`:
84+
All settings are configured via the add-on **Configuration** tab in Home Assistant. The add-on generates MeshCentral's `config.json` automatically on every start based on these settings.
85+
86+
### General
87+
88+
| Option | Default | Description |
89+
|--------|---------|-------------|
90+
| `data_path` | `/data/meshcentral-data` | Where MeshCentral stores its database, files and backups |
91+
| `hostname` | *(auto)* | Public hostname for agent connections. Leave empty to use the HA hostname |
92+
| `cert_url` | *(empty)* | **Required for external agent connections.** Full external URL, e.g. `https://mesh.yourdomain.com` |
93+
| `server_mode` | `lan` | Network mode: `lan` (local only), `wan` (internet, requires DNS), `hybrid` (both) |
94+
95+
### Domain / appearance
96+
97+
| Option | Default | Description |
98+
|--------|---------|-------------|
99+
| `domain_title` | `MeshCentral` | Title shown on the login page |
100+
| `domain_title2` | `Home Assistant` | Subtitle shown below the title |
101+
| `new_accounts` | `false` | Allow users to self-register. Enable temporarily to create your first admin account |
102+
| `allow_device_sharing` | `false` | Allow device sharing with other users |
103+
104+
### Security
105+
106+
| Option | Default | Description |
107+
|--------|---------|-------------|
108+
| `session_key` | *(auto)* | Secret key for encrypting session cookies. Leave empty to auto-generate on each start |
109+
| `session_time` | `60` | Session duration in minutes |
110+
| `tls_offload` | `true` | Set to `true` when a reverse proxy (e.g. HA's NGINX) handles TLS in front of MeshCentral |
111+
| `trusted_proxy` | *(empty)* | IP addresses allowed to forward headers (X-Forwarded-For). Use `CloudFlare` for automatic CloudFlare IP list |
112+
| `user_allowed_ip` | *(empty)* | Only these IPs can log in. Comma-separated, e.g. `192.168.1.0/24,10.0.0.1`. Empty = all allowed |
113+
| `user_blocked_ip` | *(empty)* | Block these IPs from logging in |
114+
| `agent_allowed_ip` | *(empty)* | Only accept agents from these IPs |
115+
| `agent_blocked_ip` | *(empty)* | Reject agents from these IPs |
116+
117+
### Network features
118+
119+
| Option | Default | Description |
120+
|--------|---------|-------------|
121+
| `web_rtc` | `false` | Enable WebRTC for direct peer-to-peer browser ↔ agent connections |
122+
| `compression` | `false` | Enable GZIP compression for HTTP responses |
123+
| `self_update` | `false` | Allow MeshCentral to update itself automatically |
124+
| `maintenance_mode` | `false` | When enabled, only administrators can log in |
125+
126+
### Email (SMTP)
127+
128+
| Option | Default | Description |
129+
|--------|---------|-------------|
130+
| `smtp_enabled` | `false` | Enable SMTP to send emails (account confirmation, password reset) |
131+
| `smtp_host` | *(empty)* | SMTP server hostname, e.g. `smtp.gmail.com` |
132+
| `smtp_port` | `587` | SMTP port. Use `587` for STARTTLS or `465` for SSL |
133+
| `smtp_from` | *(empty)* | Sender email address |
134+
| `smtp_user` | *(empty)* | SMTP username |
135+
| `smtp_pass` | *(empty)* | SMTP password |
136+
| `smtp_tls` | `true` | Enable TLS for the SMTP connection |
88137

89-
FolderContents`data_path/`MeshCentral database and config`data_path/meshcentral-files/`Device files`data_path/meshcentral-backups/`Automatic backups`data_path/meshcentral-recordings/`Session recordings
138+
## Ports
90139

91-
All folders are included in HA's standard backup.
140+
| Port | Description |
141+
|------|-------------|
142+
| `4430/tcp` | MeshCentral web interface (HTTPS) |
143+
| `4433/tcp` | Intel AMT / MPS port |
92144

93-
> **Note:** The `meshcentral-web` folder cannot be redirected (MeshCentral limitation) and will be created next to the add-on installation.
145+
## Data storage
94146

95-
## Configuration
147+
All MeshCentral data is kept under `data_path`:
96148

97-
OptionDefaultDescription`data_path/data/meshcentral-data`Where MeshCentral stores its data`hostname`*(auto*)Public hostname for agent connections — set this to your external URL`cert_url`*(empty*)**Required for external agent connections** — set to your full external URL (e.g. `https://mesh.yourdomain.com`). MeshCentral uses this to verify agent connections. Without this, agents outside your local network cannot connect.`allow_device_sharingfalse`Allow device sharing with other users
149+
| Folder | Contents |
150+
|--------|----------|
151+
| `data_path/` | MeshCentral database and config |
152+
| `data_path/meshcentral-files/` | Device files |
153+
| `data_path/meshcentral-backups/` | Automatic backups |
154+
| `data_path/meshcentral-recordings/` | Session recordings |
98155

99-
## Ports
100-
| Port | Description |
101-
|------|-------------|
102-
| `4430/tcp` | MeshCentral web interface |
156+
All folders are included in HA's standard backup.
157+
158+
> **Note:** The `meshcentral-web` folder cannot be redirected (MeshCentral limitation) and will be created next to the add-on installation.
103159
104160
## Updating MeshCentral
105161

106162
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.
107163

108-
## Backup
109-
110-
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.
111-
112164
## Troubleshooting
113165

114166
**Agents can't connect from outside my network:**
115-
Set the `hostname` option to your external URL (Cloudflare tunnel, DuckDNS, Nabu Casa URL).
167+
Set `server_mode` to `wan` or `hybrid`, and set `cert_url` to your external URL (Cloudflare tunnel, DuckDNS, Nabu Casa URL).
116168

117169
**Can't create account:**
118-
Temporarily set `"newAccounts": true` in `/data/meshcentral-data/config.json` and restart the add-on. Remember to set it back to `false` after.
170+
Temporarily set `new_accounts` to `true` in the add-on configuration and restart. Remember to set it back to `false` after creating your account.
119171

120172
**MeshCentral integration shows "invalid_auth":**
121173
If your account has 2FA enabled, create a Login Token in MeshCentral → My Account → Login Tokens and use those credentials in the HA integration.
122174

175+
**Settings not taking effect:**
176+
The add-on regenerates `config.json` on every start from the HA configuration. Restart the add-on after changing any setting.
177+
123178
## Related
124179

125180
- [MeshCentral HA Integration](https://github.com/andlo/ha-meshcentral) — HACS integration for HA entities

‎meshcentral/config.yaml‎

Lines changed: 53 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,29 +1,77 @@
11
{
22
"name": "MeshCentral",
3-
"version": "0.1.0",
3+
"version": "0.2.0",
44
"slug": "meshcentral",
55
"description": "Self-hosted remote device management — monitor and control your PCs from Home Assistant",
66
"url": "https://github.com/andlo/ha-meshcentral-addon",
77
"arch": ["aarch64", "amd64", "armhf", "armv7", "i386"],
88
"startup": "application",
99
"boot": "auto",
1010
"ports": {
11-
"443/tcp": 4430
11+
"443/tcp": 4430,
12+
"4433/tcp": 4433
1213
},
1314
"ports_description": {
14-
"443/tcp": "MeshCentral web interface (HTTPS)"
15+
"443/tcp": "MeshCentral web interface (HTTPS)",
16+
"4433/tcp": "Intel AMT / MPS port"
1517
},
1618
"options": {
1719
"data_path": "/data/meshcentral-data",
1820
"hostname": "",
1921
"cert_url": "",
20-
"allow_device_sharing": false
22+
"allow_device_sharing": false,
23+
"server_mode": "lan",
24+
"new_accounts": false,
25+
"domain_title": "MeshCentral",
26+
"domain_title2": "Home Assistant",
27+
"session_key": "",
28+
"session_time": 60,
29+
"tls_offload": true,
30+
"trusted_proxy": "",
31+
"user_allowed_ip": "",
32+
"user_blocked_ip": "",
33+
"agent_allowed_ip": "",
34+
"agent_blocked_ip": "",
35+
"web_rtc": false,
36+
"compression": false,
37+
"self_update": false,
38+
"maintenance_mode": false,
39+
"smtp_enabled": false,
40+
"smtp_host": "",
41+
"smtp_port": 587,
42+
"smtp_from": "",
43+
"smtp_user": "",
44+
"smtp_pass": "",
45+
"smtp_tls": true
2146
},
2247
"schema": {
2348
"data_path": "str",
2449
"hostname": "str",
2550
"cert_url": "str",
26-
"allow_device_sharing": "bool"
51+
"allow_device_sharing": "bool",
52+
"server_mode": "list(lan|wan|hybrid)",
53+
"new_accounts": "bool",
54+
"domain_title": "str",
55+
"domain_title2": "str",
56+
"session_key": "password?",
57+
"session_time": "int",
58+
"tls_offload": "bool",
59+
"trusted_proxy": "str?",
60+
"user_allowed_ip": "str?",
61+
"user_blocked_ip": "str?",
62+
"agent_allowed_ip": "str?",
63+
"agent_blocked_ip": "str?",
64+
"web_rtc": "bool",
65+
"compression": "bool",
66+
"self_update": "bool",
67+
"maintenance_mode": "bool",
68+
"smtp_enabled": "bool",
69+
"smtp_host": "str?",
70+
"smtp_port": "int?",
71+
"smtp_from": "str?",
72+
"smtp_user": "str?",
73+
"smtp_pass": "password?",
74+
"smtp_tls": "bool?"
2775
},
2876
"map": [
2977
"data:rw"

0 commit comments

Comments
 (0)