Skip to Content
🚀 We just launched! Please star us on Github!

Homey Self-Hosted Server

The Homey integration connects Smart Panel to a Homey Self-Hosted Server (SHS) over its local API. It imports logical devices already managed by Homey, lets an administrator review and adopt them, keeps their state synchronized, and sends supported controls back to Homey.

Local Homey SHS support is validated over HTTP port 4859. Basic reads and a passive SDK session were verified on SHS 13.4.0. The complete validation matrix passed on SHS 13.4.1, covering sanitized inventory, capability writes and ordered events, credential rotation and permission failures, startup/restart/network recovery, physical/Homey/Flow changes, concurrent commands, disposable-device lifecycle, thermostat setpoint and mode control, and clean plugin/backend shutdown. Homey Pro hardware and HTTPS were not validated, and physical availability manager events were not emitted by the disposable test driver. Periodic reconciliation remains the fallback for missed availability events.

Smart Panel does not pair, rename, move, or remove devices in Homey. The integration uses Homey’s local API and never asks a user to enter Homey account credentials.

Before You Start

For a local connection, you need:

  • a configured Homey Self-Hosted Server ;
  • network access from the Smart Panel backend to Homey’s local API;
  • the complete local API URL, including http:// or https:// and any non-standard port; and
  • a dedicated Homey API key with only the permissions Smart Panel needs.

SHS uses port 4859 for HTTP and 4860 for HTTPS by default. Those ports can be overridden in the SHS deployment. Use the address and port reachable from the machine or container running Smart Panel, which may differ from an address that works in your desktop browser.

Examples:

http://192.168.1.50:4859 https://homey.example.net

Do not put a username, password, API path, query string, or API key in the URL. Prefer HTTPS when the network endpoint has a certificate trusted by the Smart Panel host. Do not expose the local API directly to the public internet merely to connect Smart Panel; use a private network or a correctly secured reverse proxy when the services are on different networks.

For SHS installation and network settings, follow Homey’s platform-specific installation guide. Homey’s port-forwarding guide  documents the default HTTPS port, but port forwarding is not required when Smart Panel and Homey can communicate on the same private network.

TrueNAS requires specific host settings. Follow Homey’s TrueNAS installation guide : disable TrueNAS’s mDNS option, enable Host Network and Privileged for the trusted SHS app, and restart the app. If TrueNAS mDNS remains enabled, SHS can exit before ports 4859 and 4860 start listening.

Create a Least-Privilege API Key

In the Homey Web App , open Settings → API Keys, choose New API Key, give the key a name such as Smart Panel, and grant all four permissions:

PermissionWhy Smart Panel needs it
homey.system.readonlyTest the connection and identify the Homey instance
homey.zone.readonlyRead the zone hierarchy shown during adoption
homey.device.readonlyDiscover devices, read capabilities, and synchronize state
homey.device.controlSend commands to supported writable capabilities

homey.device.control is currently mandatory because adopted writable mappings remain visible as controls in Smart Panel. A scope-aware read-only presentation is not implemented, so omitting this permission would leave visible commands that fail authorization. Do not grant device-management, pairing, app, Flow, user, or administrator permissions. Smart Panel’s integration has no upstream create, rename, move, or delete operation.

Create the key, copy it immediately, and store a recovery copy in your password manager. Homey displays the key only once. You can revoke it later from the same API Keys page. See Homey’s API key guide  for the current Homey UI.

Configure a Local Connection

  1. In the Smart Panel Admin UI, open Config → Plugins → Homey.
  2. Enter the local API URL and the new API key.
  3. Leave the connection timeout and reconciliation interval at their defaults unless your network needs tuning.
  4. Choose Test entered URL and key. This test is available only when both fields contain a complete candidate connection.
  5. Save the form and enable the plugin.
  6. Confirm that Connection status changes to Connected and identifies the expected Homey.

After saving, the key field is empty by design. The configured indicator confirms that a key exists, but neither the Admin UI nor the configuration API can read it back. Leaving the replacement field untouched preserves the saved key; entering a new value replaces it, and the field’s explicit clear action removes it.

Use Test saved configuration to test the URL and key already stored by the backend. If you change the URL, Smart Panel requires a new key for the unsaved connection test; it never sends a stored key to an overridden address.

Manual Server Selection

Enter the Homey URL manually. Smart Panel does not currently offer automatic Homey server discovery. A Homey-specific advertisement remained stable across a controlled restart, but safe identity deduplication and spoof-resistant endpoint verification remain explicitly deferred from the local MVP. Manual configuration is the supported setup path, and device discovery begins only after a Homey connection has been configured.

Discover and Adopt Devices

  1. Open Devices in the Admin UI and choose Add device.
  2. Select Homey to open the Homey adoption wizard.
  3. Review the discovered Homey device name, identifier, class, model, zone, availability, capability count, and support status. Refresh the inventory if Homey changed while the wizard was open.
  4. Select supported devices and continue to the confirmation step.
  5. Review each suggested Smart Panel category, name, mapping summary, and any warnings.
  6. Confirm the batch. The results identify devices that were created, updated, skipped, or failed.

Adoption is idempotent: selecting the same Homey device again updates its mapping instead of creating a duplicate. Unsupported capabilities appear as warnings and do not prevent adoption when the device still has a complete supported mapping. Devices that cannot form a supported mapping remain visible in the inventory but cannot be adopted.

Once adopted, devices use the normal Smart Panel device, space, dashboard, real-time state, and control paths. The panel display never receives the Homey URL or API key.

Supported Capability Families

Support depends on both Homey’s device class and its standardized capability IDs. The supported local integration includes:

FamilySupported state and controls
LightsPower, brightness, hue, saturation, and color temperature
Outlets and switchesPower; outlets can also expose instantaneous power and accumulated energy
Environmental sensorsTemperature, humidity, pressure, illuminance, and carbon dioxide
Safety and presence sensorsMotion, contact, smoke, and carbon monoxide alarms
ThermostatsCurrent temperature, shared target setpoint, and configured heat, cool, auto, and off modes
Window coveringsOpen, close, stop, position, and tilt when exposed by the device
LocksLocked/unlocked state and control
BatteryPercentage and low/OK status

Smart Panel preserves full suffixed Homey capability IDs, so independent repeated capabilities are not collapsed into one value. Vendor-specific classes or capabilities may be reported as unsupported or omitted from the mapping preview.

Homey exposes one shared thermostat target, which Smart Panel projects into its heating and cooling setpoints. Configured heat, cool, auto, and off modes are controllable. Smart Panel does not infer actual heating or cooling activity from the configured mode; activity is shown only when Homey provides a dedicated authoritative status signal.

Synchronization and Availability

The integration subscribes to Homey events for real-time updates. It also runs a bounded periodic reconciliation to populate initial values and repair events missed during a connection interruption. A reconnect is followed by a full reconciliation before the connection is considered healthy.

If event subscription is unavailable while reads still work, the connection reports Degraded polling and continues to reconcile. If an adopted device disappears from Homey, Smart Panel marks it unavailable/orphaned; it never deletes the Smart Panel device and never sends an unpair or delete request to Homey. An operator can later decide what to do with the local Smart Panel device.

Credentials and Backups

Treat a Smart Panel system backup as a credential. Configuration APIs and the Admin UI do not expose the local Homey key, but backups can still contain the key and other sensitive configuration. Smart Panel does not encrypt the complete backup.

  • Store and transfer backups only through trusted, access-controlled locations.
  • Do not attach a backup to an issue or support request.
  • After restoring onto a replacement host, retire or isolate the old host before enabling both copies.
  • If a backup or either host may have been exposed, revoke the Homey key, create a new least-privilege key, save it in Smart Panel, and test the connection again.

Write-only configuration prevents accidental disclosure through normal API reads; it is not a substitute for backup, host, and filesystem security.

Troubleshooting

The connection test cannot run

For Test entered URL and key, provide both a valid HTTP(S) URL and a new, non-blank key. To reuse the existing write-only key, save the URL first and use Test saved configuration.

Authentication failed

The key is missing, revoked, or invalid. Create or copy a new key, replace the saved value, and run the saved connection test. The integration avoids rapid reconnect attempts after an authentication failure.

Authorization failed

Review all four required permissions above. The current UI does not downgrade writable mappings when homey.device.control is absent. Do not solve authorization failures by granting broad device-management or administrator access.

Timeout or Homey unavailable

  • Verify the URL, scheme, and port from the Smart Panel backend host or container.
  • Check firewall, VLAN, guest-network, container, reverse-proxy, DNS, and certificate-trust rules.
  • Confirm that SHS is running and listening on the configured port.
  • Increase the connection timeout only after checking the network path.

Degraded polling or reconnecting

The event connection is unavailable or was interrupted. Smart Panel continues bounded reconciliation where possible and reconnects with bounded backoff. Check Homey and proxy support for long-lived Socket.IO/WebSocket connections. If the state does not recover, test the saved connection and inspect the sanitized backend logs.

A controlled 60-second interruption of only the Smart Panel-to-SHS API ports recovered the SDK session and subscription, then completed a fresh inventory read on SHS 13.4.1. A separate restart-spanning write flow proved matching capability events and authoritative read-backs before and after recovery. Periodic reconciliation remains the repair path for an event missed during an interruption. The disposable lifecycle driver did not emit create/update/availability manager events in repeated observation windows, so physical availability-event continuity is not claimed.

A device is missing or unsupported

Refresh the wizard inventory and verify that the device is available in Homey. Adoption is based on Homey’s logical device class and standardized capabilities, not only its product name. Vendor-specific capability sets may require a future mapping. A previously adopted device that disappeared upstream remains in Smart Panel as unavailable.

Current Limitations

  • Live local validation currently covers SHS over HTTP 4859, not Homey Pro hardware or HTTPS 4860.
  • Homey Cloud is not supported because Homey’s Web API authorization is partner-only and Smart Panel does not depend on a hosted bridge.
  • Manual Homey URL configuration; no automatic server discovery.
  • No pairing, commissioning, renaming, zone moves, removal, app, Flow, firmware, backup, or user administration in Homey.
  • No automatic deletion of Smart Panel devices that disappear from Homey.
  • No exhaustive mapping for vendor-specific capabilities.
  • Actual thermostat heating/cooling activity requires a dedicated authoritative Homey status capability; configured mode alone is never presented as activity.
Last updated on