Run Node-RED on your Homematic controller, verify it locally, and add remote access only when it is ready
RedMatic packages Node-RED as add-on software for compatible Homematic CCU3, piVCCU3, and OpenCCU systems. This guide covers compatibility checks, release selection, installation through the Homematic WebUI, the required reboot, and local verification at the documented RedMatic path. After the local service works, we show how to publish it through a Localtonet HTTP tunnel running on a compatible device that can reach the CCU over the local network. Because Node-RED can control automations and connected devices, the guide also explains the security boundary created by remote access and the precautions to take before starting a tunnel.
📋 What's in this guide
How RedMatic and Localtonet fit together
RedMatic is a packaged version of Node-RED designed to run as add-on software on a compatible Homematic controller. Node-RED provides a visual, flow-based environment for connecting events, devices, services, and automation logic. RedMatic adds the CCU-related nodes needed to integrate that environment with Homematic.
The installation and remote-access portions of this workflow are separate. First, RedMatic must be installed and working on the CCU. Its documented local address is:
http://<ccu-address>/addons/redThe placeholder represents the hostname or LAN address already used to reach the Homematic WebUI. RedMatic does not document a separate Node-RED port in this quick-start endpoint. The URL uses ordinary HTTP without an explicit port, so clients normally use the standard HTTP port. If your controller is behind a reverse proxy, uses a customized listener, or redirects requests, identify the address and port that actually work from another device on the same LAN before configuring a tunnel.
Once that local endpoint works, the Localtonet client establishes an outbound connection to one of our relay servers. An HTTP tunnel can then forward public requests to the CCU address and HTTP listener reachable from the client device. This avoids configuring inbound router port forwarding, making firewall changes for an incoming connection, setting up a conventional VPN, or requiring a public IP address.
/addons/red path.
An HTTP tunnel targets an HTTP service at an IP address and port. If the CCU serves Homematic WebUI and RedMatic from the same listener, other paths on that listener may also be reachable through the public hostname. The documented RedMatic path is not, by itself, an access-control boundary. Review the entire HTTP service, apply authentication, and test which routes are reachable before treating the tunnel as safe for ongoing use.
Compatibility and prerequisites
Check platform compatibility before downloading a release package. The RedMatic project identifies CCU3, piVCCU3, and OpenCCU, formerly known as RaspberryMatic, as supported environments. Supported processor architectures include armv7l, aarch64, and x86_64 on the corresponding supported installations.
RedMatic is not intended for CCU1, CCU2, Raspberry Pi 1, Raspberry Pi Zero, or other armv6l systems. A package upload cannot turn an unsupported hardware generation into a supported one. Confirm both the controller type and architecture rather than relying only on a device label such as “Raspberry Pi.”
| Environment | Compatibility status | What to verify |
|---|---|---|
| Homematic CCU3 | Supported by RedMatic | Choose a release asset intended for the CCU3 architecture and installed firmware environment. |
| piVCCU3 | Supported by RedMatic | Confirm the architecture reported by the host and use the matching package. |
| OpenCCU on armv7l | Supported architecture | This category includes supported armv7l environments such as certain Raspberry Pi 2 installations. |
| OpenCCU on aarch64 | Supported architecture | This category includes compatible 64-bit ARM installations, including supported Raspberry Pi 3 or 4 setups. |
| OpenCCU on x86_64 | Supported architecture | This can include compatible virtual appliance, Intel NUC, or container variants. |
| CCU1 or CCU2 | Not supported | Do not attempt this installation workflow on these controller generations. |
| armv6l systems | Not supported | Raspberry Pi 1 and Raspberry Pi Zero are specifically outside the supported architecture list. |
What you need before installation
Prepare the following items before changing the controller:
- Administrative access to the Homematic WebUI.
- A supported CCU3, piVCCU3, or OpenCCU environment and knowledge of its architecture.
- The current RedMatic release archive that matches the environment.
- Enough time for the installation and mandatory controller reboot.
- A record of the CCU hostname or LAN address used to open Homematic WebUI.
- A current controller backup created through the backup facilities appropriate to your CCU or OpenCCU version.
- For remote access, a separate Localtonet-capable computer or device on the same network if the client cannot run directly on the controller.
The RedMatic quick-start process is designed to avoid Linux command-line work and manual configuration-file editing. Installation is performed through Homematic WebUI under Systemsteuerung > Zusatzsoftware. Depending on the language configured in your controller, the labels may be localized, but the function is the add-on software management page.
Select the right RedMatic release
Download the redmatic-<version>.tar.gz package from the project’s release page. Use the asset that corresponds to the controller architecture and firmware environment. Do not unpack or rename the archive unless the release instructions for the selected version explicitly tell you to do so.
RedMatic is under active development, and major versions can differ substantially. The project has announced that RedMatic 9 is being modernized around newer Node.js and Node-RED versions. Its stated direction is a slimmer default installation in which only node-red-contrib-ccu is preinstalled, with other nodes added as needed through the Node-RED palette manager. The earlier RedMatic package manager and RedMatic WebApp are deprecated in that development line.
This means a historical release page should not automatically be treated as the correct download for every current system. Older releases may bundle modules and user-interface components that newer releases no longer include. Conversely, a development announcement is not proof that a stable build is suitable for production. Review the current release label, compatibility notes, and asset names on the official RedMatic releases page at installation time.
Add-on installation changes software on the controller and requires a reboot. Create a current CCU or OpenCCU backup using the procedure appropriate to your installed platform before proceeding. The supplied evidence does not establish one universal backup command or file path across all supported variants, so this guide does not invent one.
Install RedMatic through Homematic WebUI
The official quick-start workflow has four essential actions: download the release archive, install it through the add-on management page, reboot the controller, and open the documented Node-RED endpoint. Installation can take several minutes, so avoid interrupting the controller merely because the page does not respond immediately.
Download the matching RedMatic archive
Open the official RedMatic releases page and download the redmatic-<version>.tar.gz asset intended for your supported CCU3, piVCCU3, or OpenCCU architecture. Keep the archive in its distributed form unless that release explicitly says otherwise.
Install the archive as add-on software
Sign in to Homematic WebUI and navigate to Systemsteuerung > Zusatzsoftware. Use the add-on installation function to select and upload the downloaded RedMatic archive. Allow several minutes for processing and do not power off the controller during installation.
Reboot the CCU
Reboot the controller after the add-on installation finishes. The reboot is part of the documented installation process, not an optional troubleshooting step. Wait for Homematic WebUI and the controller’s normal services to become available again.
Open the RedMatic Node-RED path
From a browser on the local network, open http://<ccu-address>/addons/red. Replace the placeholder with the same local hostname or address used for your controller. Confirm that the Node-RED editor loads before making any remote-access changes.
Be patient during installation and reboot
RedMatic’s installation documentation explicitly notes that the process can take several minutes. A temporary loss of the WebUI during reboot is expected. Repeated refreshes do not make the process finish sooner, and interrupting power can create a more serious recovery problem.
First wait for the controller’s usual Homematic WebUI to return. Then test the RedMatic path. If the main WebUI is still unavailable, diagnose the controller startup before troubleshooting Node-RED. If Homematic WebUI works but /addons/red does not, focus on add-on compatibility, the selected release asset, and installation completion.
Verify RedMatic locally before exposing it
Local verification separates RedMatic problems from tunnel problems. A Localtonet tunnel cannot repair an add-on that failed to install, a controller that has not completed its reboot, or a LAN address that is unreachable from the client device.
Test from a normal LAN device
Use a computer or mobile device connected to the same local network as the CCU. Open the exact local endpoint:
http://<ccu-address>/addons/redA successful check means the browser can reach the controller and the Node-RED interface loads at that path. Save the exact working hostname or IP address. If the browser redirects to another scheme, hostname, or port, record the final working address because the effective local target may differ from the simple quick-start example.
Test from the future tunnel device
Repeat the same test from the computer that will run the Localtonet client. This check matters when network segmentation, guest Wi-Fi, container networking, VLAN rules, or host firewalls permit access from one device but not another.
The tunnel’s local target must be reachable from the Localtonet client device. If your laptop can open RedMatic but the always-on server selected for the tunnel cannot, the server is not yet a valid forwarding point. Resolve local routing and policy issues before creating the tunnel.
Perform a minimal Node-RED functional check
Confirm more than the presence of an HTML page. Verify that the editor loads completely, that the expected CCU nodes are available for the installed release, and that the browser does not report continuous connection failures. If you create a small test flow, choose one that does not unlock doors, trigger alarms, switch safety-critical devices, or change production automation.
Avoid assuming that every node shown in an old RedMatic tutorial is preinstalled. Older versions bundled a broader collection of modules. The announced RedMatic 9 direction installs only the CCU integration by default, with additional nodes obtained through the Node-RED palette manager.
The RedMatic project notes that packages or nodes with binary native dependencies cannot be installed on the CCU in the modernized RedMatic 9 model because the controller has no compiler toolchain and precompiled binaries are not supplied. Check a node’s dependency requirements before designing an automation around it.
Secure Node-RED before creating public connectivity
Node-RED is an administrative automation interface. Depending on the installed flows and nodes, access can allow a user to inspect automation logic, change flows, communicate with Homematic devices, call other services, or obtain configuration details. Treat it with the same care as the Homematic administration interface.
RedMatic’s documentation includes guidance for configuring password protection and security, but the supplied evidence does not establish one exact configuration procedure that is correct across every RedMatic generation. Authentication details can change with the bundled Node-RED version and with the removal of legacy RedMatic components. For that reason, we do not provide guessed file paths, configuration keys, password commands, or restart procedures.
Before starting the public tunnel, follow the security instructions for the exact RedMatic version you installed and verify authentication from a private browser session. A login screen alone is not enough. Confirm that an unauthenticated visitor cannot open the editor, inspect flows, deploy changes, or access sensitive HTTP endpoints created by your flows.
/addons/red because the same CCU HTTP listener may serve other routes.
Also inspect the flows themselves. Remove unused HTTP input nodes, debug endpoints, test dashboards, default credentials, and hard-coded secrets. A protected editor does not necessarily protect every endpoint created by a flow. Each flow-provided HTTP route needs its own security review.
Keep the CCU and RedMatic release within the compatibility guidance of their maintainers. Before upgrading, back up the controller and export important flows using the facilities available in your installed Node-RED version. Do not expose an unmaintained test installation simply because the tunnel makes it convenient to reach.
Create a Localtonet HTTP tunnel for RedMatic
Only begin this section after http://<ccu-address>/addons/red works from the intended Localtonet client device. Our client makes an outbound connection to a Localtonet relay, so the router does not need an inbound port-forwarding rule and the internet connection does not need a public IP address.
The supplied RedMatic evidence does not establish that the Localtonet client can run directly on the constrained CCU platform. Do not assume that it can. A practical topology is to run our client on a compatible, always-on computer elsewhere on the same LAN, such as a workstation, home server, or other supported device. That device must be able to reach the CCU address and HTTP listener.
Configure the HTTP tunnel for the CCU’s reachable local address and effective HTTP port. After Localtonet assigns the public HTTPS address, append /addons/red to reach RedMatic. The project’s quick-start URL does not state a separate port. If the plain local HTTP URL works without an explicit port, standard HTTP URI behavior normally means port 80. If your environment redirects or uses a customized port, use the actual locally verified listener instead of assuming.
Current relay server or region choices must be taken from the Localtonet dashboard. Availability can vary, so this guide does not hardcode a server code. Device authentication tokens are specific to the client device and must never be copied into screenshots, public documentation, flow exports, or support posts.
Install and run the Localtonet client
Install our client on a compatible device that can reach the working RedMatic URL over the local network. Keep the device powered on and connected for as long as remote access is required. The product context supplied for this guide does not include current operating-system-specific installation commands, so obtain the current installer and instructions from our platform rather than using an unverified command.
Authenticate or select the client device
Use the device-specific authentication token assigned through Localtonet and select the client that will run the tunnel. Keep the token private. It identifies the device and must not be embedded in a Node-RED flow or shared with the public URL.
Select an available relay server
Choose an available server or region shown in the current Localtonet dashboard. Do not copy a server code from an old tutorial because available values can change by product configuration, client version, region, or plan.
Create the HTTP tunnel
Create an HTTP tunnel and point its local target to the CCU hostname or LAN address and the HTTP port that worked from the client device. HTTP tunnels may use a generated subdomain, a selected subdomain where supported, or a custom domain. Because exact custom-domain DNS requirements are not established in the supplied evidence, follow the current dashboard guidance if you choose that option.
Start the tunnel
Use the Start control after reviewing the target. Creating a tunnel does not mean it is running. The selected Localtonet client must also remain connected for the public address to be available.
Open and test the assigned public address
Take the public HTTPS address assigned to the tunnel and append /addons/red. Test it from a network that is not the CCU’s LAN, confirm that authentication is required, and verify that only the intended functionality is accessible. Stop the tunnel immediately if unexpected CCU pages or unauthenticated controls are reachable.
For the current dashboard sequence and field definitions, consult our HTTP tunnel documentation. Use it to confirm current options rather than relying on screenshots or field names from an older client version.
Understand the resulting public URL
Suppose Localtonet assigns a public HTTPS base address to the HTTP tunnel. The RedMatic editor remains under the same application path:
https://<assigned-public-host>/addons/redThis example shows the URL structure only. It is not a real endpoint, and you should never publish your actual private administration address in documentation or support requests. The assigned host remains available only while the selected client is connected and the tunnel is running.
Test from outside the home network
A phone using cellular data is often a convenient way to perform an external connectivity check. Disable Wi-Fi so the request does not silently remain on the local network. Verify the following:
- The public HTTPS address resolves and opens only while the tunnel is running.
- The
/addons/redpath reaches the expected Node-RED installation. - An unauthenticated private browser session cannot enter the editor.
- Deploying or viewing flows works only for an authorized user.
- Other CCU paths do not create an unacceptable exposure.
- Stopping the tunnel makes the public address unavailable.
Do not depend on the assigned hostname or the /addons/red path remaining unknown. Protect Node-RED with appropriate application-level authentication, review flow-created endpoints, keep credentials private, and stop the tunnel when remote administration is not needed.
Operate and maintain the setup safely
Know which component controls availability
The remote path depends on several independent components: the CCU, RedMatic, the local network, the Localtonet client device, the client’s outbound internet connection, and the running tunnel. A failure in any one of them can interrupt remote access.
Creating the tunnel is only configuration. It must be started, and the selected client must remain connected. If you stop the tunnel, shut down the client device, or disconnect that device from the network, the public endpoint stops forwarding even if RedMatic remains healthy on the LAN.
Use a stable local target
If the CCU’s LAN address changes, the tunnel may continue trying to reach an obsolete address. Use a stable local hostname that resolves consistently from the client device, or manage address assignment through the networking facilities appropriate to your router and environment. This guide does not prescribe a router-specific reservation procedure because interfaces and terminology vary.
Test name resolution from the Localtonet client itself. A hostname that works only because a laptop has a special search domain or cached record is not a reliable target for an always-on client elsewhere on the network.
Separate installation changes from connectivity changes
When upgrading RedMatic, first stop the public tunnel. Back up the controller and export important flows using the capabilities of the installed RedMatic and Node-RED versions. Complete the upgrade and reboot, verify the local endpoint, review authentication, and only then restart remote access.
Major RedMatic generations can change bundled nodes and management components. In particular, do not expect the deprecated RedMatic package manager or RedMatic WebApp to remain present in the newer streamlined architecture. If a flow depends on an additional palette node, confirm that the node is compatible with the controller architecture and does not require unsupported native compilation.
Keep credentials and exports private
Flow exports can contain hostnames, usernames, service configuration, and sometimes credentials or tokens depending on the nodes involved. Review exports before sharing them. Never include the Localtonet device token in Node-RED, a flow export, a screenshot, or a public issue.
If a device token is accidentally disclosed, treat that event as a credential incident and replace or revoke the affected credential through the current Localtonet account controls. Do not attempt to conceal a leaked token merely by deleting a forum post after others may have seen it.
Stop or delete access that is no longer required
Use the tunnel lifecycle deliberately. Stop the tunnel when you expect to use it again but do not currently need remote access. Delete it when the configuration is obsolete or the target has been retired. Stopping the tunnel does not uninstall RedMatic and does not affect local access to Node-RED.
Troubleshoot RedMatic and tunnel problems
Start troubleshooting at the local service and move outward. This order prevents a tunnel symptom from hiding the underlying CCU or RedMatic problem.
| Symptom | Likely area | Checks and corrective action |
|---|---|---|
| Homematic WebUI does not return after installation | Controller reboot or installation | Allow several minutes for installation and reboot. Check the controller locally before diagnosing RedMatic or Localtonet. Avoid repeated power interruption. |
Homematic WebUI works, but /addons/red does not |
RedMatic package or compatibility | Confirm that the archive matched the architecture, that the add-on installation completed, and that the required reboot occurred. Verify that the platform is not CCU1, CCU2, or armv6l. |
| RedMatic works from one LAN device but not the tunnel device | Local routing or policy | Test the exact URL from the Localtonet client device. Check guest-network isolation, VLAN policy, local DNS, host firewalls, and whether the target hostname resolves there. |
| The tunnel exists but the public address is unavailable | Tunnel lifecycle | Confirm that the correct client device is connected and that the tunnel was explicitly started. A saved tunnel configuration is not automatically active. |
| The public host opens, but RedMatic returns a missing page | URL path | Append /addons/red to the assigned public base address. Confirm that the same path works locally. |
| The tunnel returns a gateway or connection error | Local target address or port | Recheck the effective listener from the client device. If local HTTP redirects or uses a custom port, configure the verified target rather than assuming the quick-start URL describes your customized environment. |
| Node-RED loads but an added node fails to install | Node compatibility | Check whether the node has native binary dependencies. Modern RedMatic development identifies the lack of a compiler toolchain and precompiled binaries on the CCU as a known limitation. |
| The public URL exposes more than the editor | Shared CCU HTTP listener | Stop the tunnel immediately. Review every route served by the target listener, strengthen application authentication, and do not assume the RedMatic path limits access to other routes. |
| The local target worked previously but stopped | Address or service change | Check whether the CCU address changed, whether RedMatic is running after a reboot, and whether the client can still resolve and connect to the target. |
Use a layered diagnostic sequence
- Confirm that the CCU is powered on and Homematic WebUI is available locally.
- Open the local RedMatic path from a normal LAN device.
- Open the same path from the device running the Localtonet client.
- Confirm that the intended client is authenticated and connected.
- Confirm that the HTTP tunnel is started.
- Check that the configured local IP address and port match the working local listener.
- Test the public base address and then the
/addons/redpath. - Use a private browser session to verify the authentication boundary.
Record exactly which layer fails. “Remote access is broken” is less useful than “the CCU page opens from my laptop, but the Localtonet client host cannot resolve the CCU hostname.” The second description identifies a local DNS or network issue before any public forwarding occurs.
Frequently asked questions
Can I install RedMatic on a CCU2?
No. The RedMatic project identifies CCU1, CCU2, and armv6l systems such as Raspberry Pi 1 and Raspberry Pi Zero as unsupported. The documented targets are CCU3, piVCCU3, and supported OpenCCU installations on armv7l, aarch64, or x86_64.
What is the local RedMatic URL?
The documented endpoint after installation and reboot is http://<ccu-address>/addons/red. Replace the placeholder with the local address used to reach your controller. Verify that exact URL from the future tunnel device before configuring remote access.
Which port does RedMatic use?
The RedMatic quick-start endpoint does not specify a separate port. Because it is an HTTP URL without an explicit port, normal URI behavior uses the standard HTTP port, ordinarily 80. However, a reverse proxy, redirect, or customized controller setup may alter the effective target. Use the address and port that you have verified from the Localtonet client device.
Can the Localtonet client run directly on the CCU?
This guide does not claim direct CCU client support because the supplied evidence does not establish it. Run our client on a compatible device elsewhere on the same LAN when necessary. That device only needs reliable network access to the CCU’s working local HTTP endpoint.
Does Localtonet require router port forwarding or a public IP address?
No. Our client establishes an outbound connection to a Localtonet relay server. This allows the tunnel to provide a public URL without configuring an inbound router port-forwarding rule, requiring a public IP address, changing the firewall for inbound traffic, or setting up a conventional VPN.
Is the Node-RED editor automatically protected when I create the tunnel?
No. The tunnel provides connectivity to the configured HTTP target. Configure and test application-level protection for the exact RedMatic and Node-RED version you installed. Also review HTTP endpoints created by flows and other CCU routes served by the same listener.
Why does the public URL need the /addons/red path?
The HTTP tunnel forwards to the CCU’s HTTP service, while RedMatic is mounted under the application path /addons/red. The assigned public hostname is the new entry point, but the application path normally remains the same.
Will every Node-RED node install successfully on RedMatic?
No. Compatibility depends on the RedMatic generation, Node.js version, Node-RED version, controller architecture, and the node’s dependencies. The project specifically identifies native binary dependencies as a limitation in its modernized RedMatic 9 direction because the CCU has no compiler toolchain and precompiled binaries are not supplied.
Does creating a Localtonet tunnel start it automatically?
No. Tunnel creation and tunnel operation are separate lifecycle states. Use the Start control when you are ready, and keep the selected client connected. You can later stop the tunnel without deleting its configuration, or delete it when it is no longer needed.
Connect to your verified RedMatic installation with Localtonet
Install RedMatic, confirm the Node-RED interface from the intended client device, secure the administrative surface, and then create an HTTP tunnel without opening an inbound router port.
Get Started Free →
