Installing the Staykey Home Assistant Plugin

Installing the Staykey Home Assistant Plugin

The Staykey plugin for Home Assistant is the recommended way to connect your smart devices to Staykey. It opens a secure outbound connection from your Home Assistant to Staykey's cloud — so you never need to expose your Home Assistant instance to the internet.

What the plugin does

• Connects securely without port forwarding — The plugin opens an outbound connection to Staykey. No public URL, no Nabu Casa subscription, no Tailscale setup required.
• Streams device state in real time — Lock status, thermostat readings, battery levels, and more are pushed to your Staykey dashboard instantly.
• Executes commands locally — When you or a guest locks a door or adjusts a thermostat from Staykey, the plugin handles it directly inside Home Assistant for fast, reliable response.
• Captures lock activity — Keypad unlocks, manual operations, and code slot usage are reported to your activity feed.
• Verifies access code writes — After setting a code on a Z-Wave lock, the plugin reads the slot back to confirm it took, handling retries automatically.
• Reports device health — Battery levels, connectivity status, and Z-Wave mesh quality are captured and sent to Staykey. Dashboard surfacing for health alerts is coming soon.

Requirements

• Home Assistant 2024.6 or newer
• Z-Wave JS integration configured with your lock(s)
• A Gateway Token from Staykey (found in your property's integration settings)
• Internet access (the plugin connects outbound — no incoming ports needed)

Part 1: Install HACS

HACS (Home Assistant Community Store) is required to install the Staykey plugin. If you already have HACS installed, skip to Part 2.

Step 1: Download HACS

1. In Home Assistant, go to Settings → Add-ons → Add-on Store
2. Search for Terminal & SSH and install it
3. Start the add-on and open the terminal
4. Run this command to download HACS:

wget -O - https://get.hacs.xyz | bash -

5. Wait for the script to complete

Step 2: Add the HACS integration

1. Restart Home Assistant (Settings → System → Restart)
2. After restart, go to Settings → Devices & Services
3. Click Add Integration and search for HACS
4. Follow the setup wizard:
   • You'll need to authorize HACS with your GitHub account
   • Accept the terms and conditions
5. Once complete, HACS appears in your sidebar

Part 2: Install the Staykey plugin

Step 1: Add the Staykey repository

1. Open HACS from your Home Assistant sidebar
2. Click Integrations
3. Click the menu icon (⋮) in the top right
4. Select Custom repositories
5. Enter the repository URL:

   https://github.com/staykey/staykey-ha-plugin
   

6. Select Integration as the category
7. Click Add

Step 2: Install the integration

1. In HACS Integrations, search for Staykey
2. Click on it and then click Download
3. Confirm the download
4. Restart Home Assistant (Settings → System → Restart)

Step 3: Configure the integration

1. After restart, go to Settings → Devices & Services
2. Click Add Integration and search for Staykey
3. Enter your Gateway Token:
   • Find this in Staykey under Properties → [Your Property] → Integrations → Home Assistant
   • Copy the gateway token provided
4. Click Submit

The plugin will connect to Staykey automatically. You should see a "Connected" status within a few seconds.

How it works

The Staykey plugin maintains a persistent, encrypted connection from your Home Assistant to Staykey's cloud. This means:

• Your Home Assistant stays private — No need to open ports, set up a reverse proxy, or subscribe to Nabu Casa for Staykey access.
• Commands are fast — Staykey sends commands through the existing connection. The plugin executes them locally inside Home Assistant for minimal latency.
• Events stream in real time — Lock activity, state changes, and health data are pushed to Staykey as they happen.
• Reconnects are automatic — If your internet drops or Home Assistant restarts, the plugin reconnects with exponential backoff. No manual intervention needed.

What data is sent?

The plugin sends device data for the devices you've added to Staykey:

• State updates: Lock status, thermostat readings, switch states, battery levels
• Lock activity: Keypad unlocks, manual operations, which code slot was used
• Device health: Battery warnings, connectivity status, Z-Wave mesh quality
• Device metadata: Manufacturer, model, firmware version (during device discovery)

Supported capabilities

• Device Actions (lock, open, turn_on, etc)
• Access code management (set, clear, verify)
• State streaming for all tracked devices
• Device discovery with rich metadata
• Health and battery monitoring
• Diagnostic bundles (on request from Staykey dashboard)

Updating your Gateway Token

If you need to change the gateway token after setup:

1. Go to Settings → Devices & Services
2. Find Staykey and click Configure
3. Enter the new gateway token
4. Click Submit

Migrating from webhook-based setup

If you previously used the Staykey plugin with a webhook URL, upgrading is straightforward:

1. Update the plugin to the latest version via HACS
2. Go to Settings → Devices & Services
3. Find Staykey and click Configure
4. Enter your gateway token (from Staykey's integration settings)
5. Click Submit

The plugin will switch to the gateway connection. You can remove your Nabu Casa subscription or Tailscale Funnel setup if they were only used for Staykey.

Troubleshooting

Plugin not appearing after install:

• Ensure you restarted Home Assistant after installing via HACS
• Check that the integration was downloaded successfully in HACS

"Connection failed" or plugin won't connect:

• Verify the gateway token is correct (copy it fresh from Staykey)
• Check that your Home Assistant has internet access
• Look at Home Assistant logs: Settings → System → Logs and search for "Staykey"

"Invalid gateway token" error:

• Make sure you're using the gateway token from your property's integration settings
• The token may have been rotated — copy a fresh one from Staykey

Events not showing in Staykey:

• Check that your devices are added to Staykey (the plugin only tracks devices you've added)
• Verify the plugin shows "Connected" status in Devices & Services
• Check that your lock is using the Z-Wave JS integration (not the older Z-Wave integration)

Plugin shows "Disconnected":

• Check your internet connection
• The plugin reconnects automatically — wait a minute and check again
• If it persists, restart Home Assistant and check the logs for errors

Checking logs

To see plugin activity and troubleshoot issues:

1. Go to Settings → System → Logs
2. Search for "Staykey"
3. Look for entries showing connection status, events being sent, or any errors

Source code

The Staykey plugin is open source and available on GitHub: github.com/staykey/staykey-ha-plugin