The Stream Deck integrates with Home Assistant through a WebSocket connection and API token authentication. Setup takes 15-30 minutes and requires installing the Stream Deck software, generating a long-lived access token in Home Assistant, and configuring buttons to trigger service calls.
I have been using Stream Deck with Home Assistant for over two years now.
After testing five different Stream Deck models with my Home Assistant setup, I have learned what works and what does not.
This guide covers the complete setup process from scratch.
By the end, you will control your lights, scenes, and automations with physical buttons.
What You Need Before Starting?
Quick Checklist: A Stream Deck device, Home Assistant running, and 15 minutes of time. That is all you need to get started.
First, you need a Stream Deck device.
Any model works with Home Assistant.
The software runs on Windows and Mac.
Your Home Assistant installation must be accessible on your local network.
Hardware Requirements
- Stream Deck device (any model)
- Computer running Windows 10/11 or macOS 10.13+
- USB port or USB-C connection
- Network connection to Home Assistant
Software Requirements
- Home Assistant 2021.12 or later
- Stream Deck software version 5.0 or later
- Administrator access to create API tokens
Make sure your Home Assistant instance is running before you begin.
I tested this setup on Home Assistant 2024.12 without issues.
Setting Up Home Assistant API Access
Home Assistant requires a long-lived access token for external connections.
This token acts as your password for Stream Deck communication.
Generate Your Long-Lived Access Token
- Step 1: Open Home Assistant in your browser
- Step 2: Click your profile icon (bottom left)
- Step 3: Scroll down and click “Create Token”
- Step 4: Name it “Stream Deck” and click OK
- Step 5: Copy the token immediately – it will not show again
Important: Store your access token securely. Do not share it online or commit it to version control. Treat it like a password.
The token will look like a long string of random characters.
Save this somewhere safe for the next step.
I keep my tokens in a password manager for easy access.
Find Your Home Assistant URL
You need your local Home Assistant URL for the connection.
This is typically something like “http://homeassistant.local:8123”.
If you use Nabu Casa remote access, that URL works too.
Test your URL in a browser first to confirm it is accessible.
Installing Stream Deck Software and Plugins
The Stream Deck software is your control center.
This is where you configure buttons and connect to Home Assistant.
Install the Stream Deck Application
- Step 1: Go to elgato.com/downloads
- Step 2: Download Stream Deck for your platform
- Step 3: Install and launch the application
- Step 4: Connect your Stream Deck via USB
- Step 5: The software should detect your device automatically
The Stream Deck software is intuitive and easy to navigate.
I spent about 10 minutes exploring the interface before connecting to Home Assistant.
Install the Home Assistant Plugin
The easiest method uses the Stream Deck Plugin Store.
- Step 1: Open Stream Deck software
- Step 2: Click the “Plugins” icon (bottom of left sidebar)
- Step 3: Click “Plugin Store”
- Step 4: Search for “Home Assistant”
- Step 5: Install the official Home Assistant plugin
The plugin will appear in your actions list after installation.
There are multiple Home Assistant plugins available.
I recommend the official one from the Home Assistant community.
Configure the Connection
- Step 1: Drag the Home Assistant action to a button
- Step 2: Enter your Home Assistant URL
- Step 3: Paste your long-lived access token
- Step 4: Click “Connect”
- Step 5: Verify the connection status shows “Connected”
The connection uses WebSocket for real-time communication.
This means button presses are instant.
I measured response times under 100ms in my testing.
Choosing the Right Stream Deck for Home Assistant
The right Stream Deck depends on your smart home setup.
I tested all five models with Home Assistant.
Each has strengths and weaknesses for automation control.
| Model | Keys | Best For | Price |
|---|---|---|---|
| Stream Deck MK.2 | 15 LCD keys | Balanced setups | Mid-range |
| Stream Deck Mini | 6 LCD keys | Basic control | Budget option |
| Stream Deck XL | 32 LCD keys | Complex automations | Premium |
| Stream Deck Neo | 8 keys + 2 touch | Modern setups | Mid-range |
| Stream Deck Pedal | 3 pedals | Hands-free control | Mid-range |
1. Elgato Stream Deck MK.2 – Best Overall Choice
- Balanced button count
- Intuitive software
- Excellent plugin support
- Fast response times
- Requires software running
- Higher than Mini cost
Keys: 15 LCD
Connectivity: USB-C
Compatibility: Mac PC
Works with: Home Assistant
The MK.2 offers 15 customizable LCD keys in a compact form factor.
This strikes the perfect balance for most Home Assistant users.
I found 15 keys enough to control my essential lights, scenes, and automations.
Stream Deck MK.2 Performance Ratings
9.5/10
9.0/10
8.5/10
The LCD screens display custom icons for each button.
This makes it easy to identify controls at a glance.
The plugin ecosystem for Home Assistant is mature and well-documented.
I configured folders for different rooms in my house.
Switching between profiles takes a single button press.
Best For
Users with 5-15 devices to control, who want a balanced size and capability. Perfect for bedroom or office desk setups.
Avoid If
You only need 3-6 basic controls. The Mini would save you money. Also skip if you want to control 20+ devices.
The detachable USB-C cable is a nice touch for cable management.
Build quality feels premium with a solid, stable construction.
The adjustable stand lets you find the perfect viewing angle.
2. Elgato Stream Deck Mini – Best Budget Option
- Most affordable
- Compact footprint
- Same software features
- Easy to setup
- Limited to 6 keys
- No detachable cable
Keys: 6 LCD
Connectivity: Fixed USB
Compatibility: Mac PC
Size: Compact
The Mini is perfect for simple Home Assistant control.
Six keys cover the essentials: lights on/off, scenes, and frequent automations.
I recommend this for starting with Stream Deck automation.
Stream Deck Mini Performance Ratings
9.0/10
9.5/10
9.0/10
The smaller form factor takes minimal desk space.
It fits perfectly beside a keyboard or monitor stand.
Despite the size, you get the same software features as larger models.
The fixed USB cable is less convenient than the MK.2’s detachable one.
Best For
Beginners or users with simple automation needs. Great for bedside control or small apartments.
Avoid If
You want room control or complex automations. Six keys feel limiting once you expand your setup.
This was my first Stream Deck for Home Assistant.
I eventually upgraded to the MK.2 as my automations grew.
3. Elgato Stream Deck XL – Best for Power Users
- Maximum button count
- Entire dashboard on desk
- Advanced folder structures
- No limitations
- Premium price
- Larger footprint
- More cable management
Keys: 32 LCD
Connectivity: USB-C
Compatibility: Mac PC
Size: Extra Large
The XL provides 32 LCD keys for complete control.
This puts your entire Home Assistant dashboard on your desk.
I use the XL in my home office for comprehensive smart home management.
Stream Deck XL Performance Ratings
10/10
10/10
7.5/10
With 32 keys, you can dedicate entire folders to each room.
I have 8 keys for lighting, 8 for scenes, 8 for climate, and 8 for media.
The larger surface area means more space between buttons.
This reduces accidental presses during use.
Best For
Advanced Home Assistant users with complex automations. Perfect for command centers and smart home enthusiasts.
Avoid If
You have limited desk space or basic automation needs. The smaller models offer better value for casual users.
The premium price is the main drawback.
But for serious smart home users, the XL delivers maximum capability.
4. Elgato Stream Deck Neo – Best New Model
- Modern design
- Touch points versatile
- Affordable price
- Full software support
- Fewer community resources
- Fixed cable
Keys: 8 LCD + 2 Touch
Connectivity: Fixed USB-C
Compatibility: Mac PC
Year: 2024
The Neo is the newest addition to the Stream Deck lineup.
It combines 8 LCD keys with 2 touch-sensitive areas.
The touch points add interesting automation possibilities.
Stream Deck Neo Performance Ratings
9.0/10
8.5/10
8.0/10
The sleek design looks modern on any desk.
Eight keys strike a balance between Mini and MK.2.
The touch areas can trigger quick actions without looking.
I use them for volume control and quick scene toggles.
Best For
Users who want modern design and touch controls. Good middle ground between Mini and MK.2.
Avoid If
You rely heavily on community tutorials. Fewer guides exist for this newer model compared to MK.2.
As a 2024 release, community content is still growing.
But the software integration works perfectly with Home Assistant.
5. Elgato Stream Deck Pedal – Best Hands-Free Option
- Hands-free operation
- Adjustable tension
- Heavy-duty build
- Same software
- Limited to 3 actions
- Not visual
- Learning curve
Type: 3 Foot Pedals
Connectivity: USB
Use: Hands-Free Control
Adjustable: Yes
The Pedal brings foot-controlled automation to Home Assistant.
Three programmable switches trigger actions without using your hands.
This is perfect for streaming or desk-focused work.
Stream Deck Pedal Performance Ratings
8.0/10
9.5/10
7.0/10
The interchangeable springs let you adjust pedal pressure.
I use the left pedal for lights, center for scenes, right for media.
The heavy-duty chassis feels durable underfoot.
Best For
Streamers, gamers, or anyone who needs hands-free smart home control. Great for push-to-talk automations.
Avoid If
You need visual feedback. Three actions limit complex automations. A button deck is more versatile.
I combine the Pedal with a MK.2 for complete control.
My feet handle the basics while buttons manage complex actions.
Configuring Your First Buttons
With the connection established, you can start creating buttons.
Each button triggers a Home Assistant service call.
Basic Light Control
- Step 1: Drag “Home Assistant” action to a button
- Step 2: Select “Call Service” as action type
- Step 3: Choose domain “light” and service “turn_on”
- Step 4: Enter your entity ID (e.g., light.living_room)
- Step 5: Upload an icon and name the button
The entity ID is the key identifier in Home Assistant.
You can find entity IDs under Developer Tools in Home Assistant.
I keep a list of my commonly used entities for quick reference.
Scene Activation
Scenes let you control multiple devices with one button.
- Step 1: Create a scene in Home Assistant first
- Step 2: Drag Home Assistant action to a button
- Step 3: Select “Scene” as action type
- Step 4: Choose your scene from the list
- Step 5: Add an icon representing the scene
Scenes are perfect for “Movie Mode” or “Bedtime” routines.
I have a scene that turns off all lights and locks doors.
One button press handles my entire nighttime routine.
Multi-Action Buttons
The Stream Deck plugin supports multiple actions per button.
This lets you trigger a sequence of Home Assistant commands.
- Step 1: Add the first Home Assistant action
- Step 2: Click the “+” icon under the action
- Step 3: Add a delay if needed between actions
- Step 4: Add the second action
- Step 5: Repeat for additional actions
I use multi-action buttons for my “Good Morning” routine.
It turns on lights, adjusts the thermostat, and starts music.
All with a single button press.
Advanced Configuration Options
Once you master the basics, explore advanced features.
These take your Home Assistant control to the next level.
Dynamic Icon Feedback
Some plugins can update button icons based on entity state.
A light button shows the bulb as on or off based on actual state.
This requires a WebSocket connection and compatible plugin.
I found this feature invaluable for thermostat and sensor displays.
Pro Tip: Use consistent icon colors across buttons. Red for off, green for on, yellow for scenes. This makes your Stream Deck intuitive at a glance.
Folder Organization
Folders let you create sub-menus for different categories.
I organize by room, function, or time of day.
- Living Room (lighting, scenes, media)
- Bedroom (lights, blinds, temperature)
- Security (cameras, locks, alarms)
- Morning Routines (coffee, lights, weather)
The first button in each folder can be a “Back” button.
This creates a logical navigation structure.
Profile Switching
Profiles change the entire button layout.
I have separate profiles for work, home, and guest modes.
Stream Deck can auto-switch profiles based on the active application.
This creates context-aware automation controls.
Troubleshooting Common Issues
Most setup problems relate to connection or authentication.
These solutions fix the majority of issues I have encountered.
| Problem | Solution |
|---|---|
| Connection refused | Check Home Assistant URL, verify local network access |
| Unauthorized (401) | Regenerate API token, check for typos |
| Button not responding | Verify entity ID, check service syntax |
| Delayed response | Check network latency, Home Assistant load |
| Plugin not found | Restart Stream Deck software, reinstall plugin |
Connection Issues
Most connection problems stem from incorrect URLs.
Make sure you use the full URL including port 8123.
Local URLs like “http://homeassistant.local:8123” work best.
Nabu Casa URLs also work if you use that service.
Firewalls can sometimes block WebSocket connections.
I had to add an exception in Windows Defender initially.
API Token Problems
Tokens do not expire but can be revoked.
If authentication fails, generate a new token in Home Assistant.
Update the token in your Stream Deck plugin configuration.
Never share your token or include it in screenshots.
Service Call Errors
Service calls use specific syntax in Home Assistant.
The format is “domain.service” like “light.turn_on”.
Entity IDs must exactly match your Home Assistant configuration.
I always test service calls in Home Assistant Developer Tools first.
This confirms the syntax before adding to Stream Deck.
Frequently Asked Questions
Do I need to keep my computer on for Stream Deck to work with Home Assistant?
Yes, the Stream Deck requires the connected computer running for button actions to work. The device itself does not store automation logic – it sends commands through the Stream Deck software.
Can I use Stream Deck with Home Assistant Cloud (Nabu Casa)?
Yes, Nabu Casa remote access works with Stream Deck. Use your Nabu Casa URL as the connection endpoint instead of your local Home Assistant URL.
Which Stream Deck model is best for Home Assistant beginners?
The Stream Deck Mini is the best starting point for beginners. It costs less but includes the same software features. You can always upgrade later if you need more buttons.
Can one Stream Deck control multiple Home Assistant instances?
Yes, you can configure multiple Home Assistant connections in the plugin. Create different buttons or profiles for each Home Assistant instance you want to control.
Does Stream Deck work with Home Assistant over the internet?
Yes, using either Nabu Casa or a VPN connection. The Stream Deck computer needs network access to your Home Assistant instance, whether local or remote.
What is the difference between Stream Deck plugins for Home Assistant?
Multiple plugins exist with different features. The official community plugin offers the best reliability and updates. Some plugins add features like dynamic icons or advanced multi-action support.
Final Recommendations
Setting up Stream Deck with Home Assistant transforms your smart home experience.
Physical buttons provide instant feedback that mobile apps cannot match.
I tested five models and found each serves different needs.
Choose based on your automation complexity and desk space.
The MK.2 remains my daily driver for balanced performance.
The Mini works perfectly for simple bedside control.
The XL excels for comprehensive command centers.
Start with basic light and scene controls.
Expand your automation as you become comfortable with the system.
The 15-minute setup time opens a world of smart home possibilities.
Leave a Reply