Self-Host OpenCCU on Proxmox VE with Localtonet

Understand the deployment architecture

OpenCCU, formerly known as RaspberryMatic, is a cloud-free smart-home platform compatible with eQ-3 Homematic IP and HomeMatic devices. It targets compatibility with the vendor's CCU3 platform while adding operating-system, WebUI, stability, connectivity, and management improvements. OpenCCU can run on supported physical devices, generic 64-bit hardware, container platforms, and hypervisors such as Proxmox VE.

In this design, Proxmox VE runs the OpenCCU virtual appliance. The guest connects to a LAN bridge, obtains an address through DHCP, and serves the CCU WebUI over HTTP. The unqualified address http://openccu/ uses HTTP's standard port 80 unless you have deliberately placed another proxy in front of OpenCCU or changed the working endpoint.

Homematic communication is a separate part of the design. OpenCCU can detect supported RF hardware such as an HmIP-RFUSB or other supported radio interfaces. A physical USB device connected to the Proxmox host must be assigned to the OpenCCU virtual machine before the guest can use it. Other radio designs can have different connection requirements, so confirm the selected device against OpenCCU's supported-device documentation.

Remote access should be added only after the WebUI and radio hardware work locally. For an HTTP tunnel, the Localtonet client runs on a separate supported machine that can reach the OpenCCU guest. The client establishes an outbound connection to our relay and forwards the public HTTPS address to the verified local HTTP target. The available OpenCCU evidence does not establish a supported method for installing the Localtonet client inside the appliance itself.

Requirements, architecture choice, and release verification

Supported platform and tutorial scope

OpenCCU lists Proxmox VE as a supported virtualized environment and publishes builds for x86_64 and aarch64 systems. This tutorial's reproducible import procedure covers an initial x86_64 Proxmox installation using the standalone OVA. That is the normal choice for an x86_64 Proxmox host.

The project also publishes a generic aarch64 appliance identified for Proxmox VE. It is a separate ZIP artifact and is not interchangeable with the x86_64 OVA. An aarch64 Proxmox installation must use the architecture-specific image procedure in the current OpenCCU Proxmox VE installation documentation. Do not boot the x86_64 OVA on an ARM host, and do not substitute a Raspberry Pi, OCI, LXC, or generic x86 image for the appliance procedure below.

You need administrative access to Proxmox VE, an unused VM ID, a storage target that supports virtual-machine disks, and a bridge connected to the intended LAN. The guest must be able to obtain an address through DHCP during initial startup. You also need enough available host resources for the appliance settings imported from the Open Virtualization Format descriptor.

Select the correct release asset

OpenCCU release filenames follow the pattern OpenCCU-X.XX.XX.YYYYMMDD-<TARGET>. For an initial x86_64 Proxmox installation, use the standalone file ending in .ova. The release may also contain a file ending in -ova.zip. These are different downloadable assets with different checksums.

As a dated example, the OpenCCU release published on September 19, 2026 is 3.89.11.20260919. It was identified as a security bugfix release. Its relevant assets are:

These values apply only to the named September 19, 2026 files. A newer release will have different filenames and checksum values. Check the current OpenCCU releases page before installation, read the release notes, and compare your download with the checksum published beside that exact asset.

Verify the file you actually downloaded

If you downloaded the standalone OVA on Linux, verify the OVA itself:

sha256sum OpenCCU-3.89.11.20260919.ova

If you downloaded the ZIP archive, verify the ZIP before extracting it:

sha256sum OpenCCU-3.89.11.20260919-ova.zip

On Windows PowerShell, use the corresponding filename:

Get-FileHash .\OpenCCU-3.89.11.20260919.ova -Algorithm SHA256
Get-FileHash .\OpenCCU-3.89.11.20260919-ova.zip -Algorithm SHA256

Do not compare the ZIP's digest with the standalone OVA checksum. Extracting an archive changes which file is being measured. If the result does not exactly match the checksum associated with that filename, stop and download the asset again.

Prepare the radio and local network

Confirm that the intended RF module is supported by OpenCCU and decide how it will connect to the guest. For a USB device, connect it to the Proxmox host and identify it by vendor and product identity before assigning it. Avoid selecting a device only by a temporarily assigned bus number if Proxmox offers a stable vendor/device selection.

The OpenCCU guest also needs a virtual network interface connected to the correct Proxmox bridge. DHCP should be available for first boot. If the automation environment uses VLANs or restrictive firewall rules, OpenCCU must still be able to communicate with the local clients, integrations, and hardware required by your design.

Prepare a separate Localtonet client

The optional remote-access phase requires a Localtonet account and a supported client device that can reach OpenCCU over the LAN. A small managed VM, server, or always-on device can perform this role. The device-specific authentication token is a secret and must be omitted from screenshots, shell history, issue reports, and shared notes.

Install OpenCCU on Proxmox VE

An OVA is a tar archive containing an OVF descriptor and one or more virtual disks. Proxmox imports the OVF definition into a new VM and places the disk on the storage you select. Perform the following work from a controlled administrative session on the Proxmox host.

The exact shell syntax for the OVF import depends on your VM ID, extracted descriptor filename, and Proxmox storage name. Those are local administrative values, not universal OpenCCU defaults. The current OpenCCU Proxmox guide is authoritative if its import method or required appliance settings change.

Verify OpenCCU locally before remote access

A green Proxmox running state proves only that the virtual machine process started. It does not prove that OpenCCU completed initialization, received an address, serves the correct page, retained its configuration, or detected the radio.

Confirm the DHCP address and WebUI

Find the guest's address through the authoritative DHCP server, router, appliance console, or available Proxmox guest information. Record it and confirm that it belongs to the intended network. Then test both forms separately:

http://openccu/
http://<openccu-dhcp-address>/

The hostname can fail even when the appliance is healthy because local name resolution differs between networks. If the IP address works and the hostname does not, continue with the IP address while resolving the naming issue.

Verify the content, not only the status code

The browser must display the OpenCCU CCU WebUI, not a Proxmox login, router page, another server, or a generic proxy response. Complete the current first-use administration prompts presented by your installed release. Configure a strong administrative credential before considering any external access.

Verify radio detection separately

Check that OpenCCU recognizes the expected radio interface. A missing radio with a working WebUI usually points to physical connectivity, device support, or Proxmox assignment rather than an HTTP problem. Confirm that the USB device still appears under the VM hardware and has not been attached to another guest.

Test from the future Localtonet client host

The machine that will run Localtonet must reach the exact OpenCCU target. From that machine, request the local WebUI at the private address. A standard HTTP request can confirm the endpoint without exposing credentials:

curl -I http://<openccu-dhcp-address>/

A valid HTTP response establishes transport reachability, but also use a browser to verify that the page and login workflow function correctly. If the browser address is simply http://192.0.2.10/, for example, the Localtonet target port is 80. Use another port only when the tested local URL explicitly contains one, such as http://192.0.2.10:8080/.

Restart and repeat the checks

Perform one controlled restart. Verify that the VM boots, receives the expected address, displays the WebUI, retains its administration settings, and detects the radio again. If a stable management address is required, create a DHCP reservation using your DHCP server's documented process.

Configure, migrate, back up, and update OpenCCU

Complete local administration first

Finish the administration and security configuration shown by the installed WebUI before pairing production devices or enabling remote access. Use only the accounts, permissions, add-ons, and integrations required by the deployment. Do not rely on assumed default credentials or screen labels from an older release.

The official OpenCCU administration documentation covers ongoing WebUI administration. Record the installed release, Proxmox VM ID, storage, bridge, DHCP reservation, radio model, assigned USB identity, installed add-ons, and backup location in your operating notes.

Restore an existing CCU deployment carefully

OpenCCU documents backup interchangeability with the vendor CCU firmware and supports restoring an existing CCU backup as a migration path. Preserve an untouched copy of the original backup outside the appliance. Confirm that required add-ons and integrations are suitable for the destination release before restoration.

After restoring, verify devices, programs, system variables, add-ons, radio communication, and external integrations while the original controller remains recoverable. Do not run two controllers in a way that creates conflicting radio or integration behavior.

Consult the official OpenCCU backup and restore documentation for the current WebUI sequence and migration limitations.

Use both application and hypervisor recovery

An OpenCCU backup protects the smart-home configuration in a portable form. A Proxmox backup or snapshot protects a VM state tied to the virtualized deployment. A snapshot is not a substitute for exporting a current OpenCCU backup, and an application backup does not preserve every hypervisor setting.

Before an upgrade, restore, add-on change, or major radio reconfiguration, create an OpenCCU backup and an appropriate Proxmox recovery point. Store important backups outside the guest so a failed virtual disk does not remove both the service and its only recovery copy.

Update using the correct release type

Review release notes before updating, especially when a release contains security fixes. Use the update asset and mechanism documented for an existing OpenCCU appliance. The standalone OVA is intended for initial installation and should not be treated automatically as an in-place update package.

Follow the OpenCCU firmware update documentation, then repeat the installation verification checklist: boot, private address, WebUI, authentication, radio detection, devices, automations, integrations, and remote access if enabled.

Configure remote access with Localtonet

Localtonet can expose a reachable local service without inbound router port forwarding, firewall changes, a public IP address, or a separate public-facing reverse proxy. For OpenCCU, our client should run on another managed device that can reach the appliance at its tested private address.

The normal target is the OpenCCU private IP address on port 80 because http://openccu/ is an unqualified HTTP URI. If your verified deployment uses an explicit different port, enter that tested port instead. Do not point the tunnel at the Proxmox interface or router.

See the Localtonet HTTP tunnel documentation for the current interface. The dashboard is authoritative for field names, available relay servers, process types, and account-specific options.

External acceptance criteria

Treat the tunnel as verified only when all of the following are true:

• The test uses a network outside the OpenCCU LAN.
• The public URL uses HTTPS and loads the expected OpenCCU interface.
• Anonymous visitors cannot administer the system.
• The intended OpenCCU account can authenticate and navigate normally.
• The URL does not expose Proxmox, a router, or another local service.
• Stopping the tunnel makes the public endpoint unavailable.
• Local OpenCCU access remains available for recovery.

Choose between a public HTTP endpoint and private VPN access

OpenCCU controls a sensitive smart-home environment. A Localtonet HTTP tunnel encrypts the public browser connection at the tunnel edge and forwards it to the configured local target, but transport exposure and application authentication are different controls. A public HTTPS address does not create OpenCCU users, strengthen their passwords, or decide what an authenticated administrator may change.

Review the current OpenCCU security advice before remote exposure. Keep the appliance current, configure strong WebUI authentication, remove unused accounts, apply least privilege where the installed release supports it, and avoid weakening OpenCCU firewall or API restrictions merely to make a proxy test pass.

When an HTTP tunnel is appropriate

An HTTP tunnel can be practical when an authorized administrator needs temporary browser access and installing a private-network client on the remote device is not suitable. It publishes one web target and can be started only for the maintenance window.

Use this design only after confirming that OpenCCU itself requires authentication. Treat the public URL as discoverable, even if its hostname is difficult to guess. Do not use obscurity as the access-control layer.

When VPN Manager is preferable

Localtonet VPN Manager is a private mesh VPN with granular firewall rules. It is preferable when OpenCCU is used only by known administrators, when long-lived access is required, or when the WebUI should not exist at a public URL at all. Authorized devices join the private network and reach OpenCCU through allowed private routes.

VPN Manager is the VPN option in our platform. An ordinary HTTP tunnel is not a VPN and should not be described as one. The two approaches solve different access problems.

Reverse-proxy behavior and recovery access

A tunnel or reverse proxy can change the public hostname and external scheme seen by the browser. Test login, navigation, redirects, cookies, and logout from the public URL. If OpenCCU redirects to a private hostname, generates an unusable absolute URL, or requires custom certificate behavior, stop the public deployment and follow the OpenCCU guidance for remote access and custom HTTPS certificates. Do not add unverified forwarded headers or mark arbitrary internet addresses as trusted networks.

Keep a working local recovery path. Do not perform a remote network, firewall, certificate, radio, or authentication change that could lock you out unless someone can recover the system locally. Create a current backup before material changes.

Minimum security checklist

• Install a current OpenCCU release and review security-related release notes.
• Require OpenCCU application authentication before creating a public tunnel.
• Use separate credentials for OpenCCU, Proxmox, and Localtonet administration.
• Grant only the access needed for the remote task.
• Protect the Localtonet device token as a secret.
• Expose only the OpenCCU WebUI target.
• Keep local recovery access and a current backup.
• Stop or delete unused HTTP tunnels.
• Prefer VPN Manager when only known devices need continuing access.

Troubleshoot OpenCCU and Localtonet by layer

The OpenCCU VM does not boot

Confirm that the asset matches the host architecture and that its checksum is correct. Verify that the OVF import completed, the imported disk exists, the disk is on available storage, and the expected boot device remains selected. Read the Proxmox task output and guest console before changing virtual hardware.

The VM starts but has no reachable WebUI

Confirm that the virtual network interface is connected to the intended bridge and that DHCP issued an address. Try the private IP instead of http://openccu/. If the IP works, investigate local name resolution rather than reinstalling OpenCCU.

If neither address works, check VLAN membership, bridge configuration, DHCP, guest startup, and local firewall policy. Do not create a tunnel until the private IP works from the Localtonet client host.

The WebUI works but the radio is missing

Verify the exact radio model against OpenCCU's supported-device information. Confirm that the USB device is physically connected and listed in the VM hardware. Shut down the VM before correcting the assignment. Check whether another VM or host process owns the device and whether its USB identity changed after reconnecting it.

The OpenCCU address changes

Create a DHCP reservation using the authoritative procedure for your router or DHCP server. After an address change, retest the new target from the Localtonet client and update the tunnel configuration only after confirming that the new address displays OpenCCU.

The Localtonet tunnel exists but is unavailable

A created tunnel is not necessarily running. Confirm that the selected Localtonet client is connected, the correct AuthToken device is selected, the relay server is currently valid, and the tunnel has been started. Verify that the client machine remains powered on and has outbound connectivity.

The public URL shows the wrong page

Stop the tunnel immediately and check the local IP address and port. The target must be the OpenCCU guest, not the Proxmox host, router, Localtonet client, or another application. Open the identical target locally from the Localtonet client machine before restarting the tunnel.

The local page works but the public login fails

Test from a genuinely external network and record redirects without sharing private or public identifiers. Confirm that OpenCCU authentication works locally with the same account. If the external browser is redirected to openccu or a private address, review the current OpenCCU reverse-proxy, remote-access, and certificate guidance rather than disabling authentication or broadening trusted networks.

An update breaks access

First determine whether the failure exists locally. If the private WebUI is unavailable, troubleshoot OpenCCU, the VM, and networking before touching Localtonet. If local access works, check whether the address, port, authentication behavior, or redirect behavior changed. Restore only from a recovery point whose consequences you understand.

Frequently asked questions