Recommended Free Tools
Run Home Assistant Container and Eclipse Mosquitto as separate services in one Docker Compose project, attach both to the same Compose network, and use mosquitto as Home Assistant’s broker hostname. Persist Home Assistant’s /config directory and Mosquitto’s configuration, data, and log directories. Then add the MQTT integration at Settings > Devices & services, enter the broker credentials, and verify traffic with mosquitto_pub and mosquitto_sub.
Need a server to try this on? Antihost offers Linux VPS plans with NVMe storage, full root access and a 14-day free trial.
This arrangement avoids the most common Docker error: using localhost in Home Assistant. Inside the Home Assistant container, localhost means that container itself, not the Mosquitto container. Compose’s internal DNS resolves the Mosquitto service name on the shared network.
As an Amazon Associate I earn from qualifying purchases.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
What this setup contains
MQTT is a lightweight publish/subscribe protocol for machine-to-machine and Internet of Things messaging. Devices publish messages to topics; clients subscribe to the topics they need. Mosquitto is the broker that receives those messages and forwards them. Home Assistant is an MQTT client that subscribes to device state and publishes commands.
Docker Compose supplies the orchestration layer for the two containers. The official Compose documentation explains the multi-container model at https://docs.docker.com/compose/, and Home Assistant’s container installation documentation is at https://www.home-assistant.io/installation/.
#1 Best Overall
- Supports Multiple Industry-Standard Communication Protocols: Modbus TCP, SNMP, BACnet, and MQTT. Our system is compatible with all these protocols and can deliver data in multiple formats simultaneously. Comprehensive support for SNMP v1/v2/v3 and SNMP Trap v2c/v3 with high security level.
- Can be integrated to AWS/Azure/Tuya loT cloud directly with low cost. Can be directly integrated into Home Assistant
- Proactive Alerts – Instant email notifications when thresholds are exceeded (fully customizable triggers). IFTTT Automation – Trigger smart actions (e.g., activate HVAC, log to Google Sheets, or Telegram alerts) via Webhook integration.
- PoE power supply: Centralized power supply: Simply provide uninterrupted power supply at the PoE switch to ensure power supply to the sensor.
- Easy to use: A graphical interface configuration tool supporting Windows, Linux, and macOS platforms with online remote upgrade capability for simplified product deployment and maintenance.
The finished architecture is:
- A
homeassistantservice with its persistent configuration mounted at/config. - A
mosquittoservice with persistent configuration, message data, and logs. - A private Compose network shared by both services.
- MQTT on TCP port
1883, published to the host only when a host or LAN client needs to reach it. - Username/password authentication, with TLS added when traffic crosses an untrusted network.
Home Assistant requires an MQTT broker that supports protocol version 5. The official Mosquitto broker supports MQTT 5. Home Assistant’s integration documentation also states that ActiveMQ and the RabbitMQ MQTT Plugin are not supported and recommends a known working broker such as Mosquitto: https://www.home-assistant.io/integrations/mqtt.
Prerequisites and a safe layout
Install Docker Engine and the Docker Compose plugin on the host that will run the stack. Choose a directory that will survive container replacement and back it up regularly. The following layout keeps each service’s state separate:
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →ha-mqtt/
├── compose.yml
├── homeassistant/
└── mosquitto/
├── config/
├── data/
└── log/Create the directories before starting the containers:
mkdir -p ha-mqtt/homeassistant
mkdir -p ha-mqtt/mosquitto/config ha-mqtt/mosquitto/data ha-mqtt/mosquitto/log
cd ha-mqttDo not put passwords directly in a publicly shared Compose file. Restrict permissions on the Mosquitto configuration and password file, and include the Home Assistant configuration directory in your backup plan.
Create the Compose project
Save the following as compose.yml. The Home Assistant image uses the stable container channel, while Mosquitto uses the official broker image. Both services join the explicitly named ha-net network. The loopback binding on port 1883 lets tools on the Docker host test the broker without exposing it on every host interface.
services:
homeassistant:
image: ghcr.io/home-assistant/home-assistant:stable
container_name: homeassistant
restart: unless-stopped
depends_on:
- mosquitto
ports:
- "8123:8123"
volumes:
- ./homeassistant:/config
- /etc/localtime:/etc/localtime:ro
networks:
- ha-net
mosquitto:
image: eclipse-mosquitto:2
container_name: mosquitto
restart: unless-stopped
ports:
- "127.0.0.1:1883:1883"
volumes:
- ./mosquitto/config:/mosquitto/config
- ./mosquitto/data:/mosquitto/data
- ./mosquitto/log:/mosquitto/log
networks:
- ha-net
networks:
ha-net:
driver: bridgedepends_on controls startup order; it does not prove that the broker is ready to accept connections. Home Assistant can retry while Mosquitto finishes initializing. If devices on your LAN must connect directly, change the MQTT port mapping to a LAN-reachable address and enforce a firewall policy. If only the two containers need MQTT, remove the ports section entirely; the service remains reachable as mosquitto:1883 over ha-net.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Port 8123 is Home Assistant’s web interface mapping in this example. Keep it limited by your host firewall or bind it to a specific management interface if the interface should not be exposed broadly.
Rank #2
- Precision Monitoring for Critical Environments: The server room temperature monitor is a professional temperature and humidity monitor built for continuous reliability in data centers, network closets, and industrial environments. Featuring a Swiss-grade external probe with ±0.2 °C and ±2 %RH typical accuracy, it delivers precise real-time measurements of temperature, humidity, and dew point — ensuring sensitive equipment stays within safe operating conditions.
- Real-Time Local Display and Easy Setup: With its bright 3.5-inch TFT color screen, this server room temperature monitor lets users instantly view live values and alarm status directly on the device — no PC required. Configure thresholds, network settings, and relay actions using simple front-panel buttons or through the integrated web interface. Perfect for on-site checks in IT rooms, labs, cold storage, or pharmaceutical facilities.
- Multi-Channel Smart Alerts & Automated Response: Stay protected from sudden changes with multi-channel notifications. The server rack temperature monitor supports email alerts via SMTP, SNMP trap, and MQTT messages, as well as visual and audible alarms. Use the onboard relay output to automatically activate fans, AC units, dehumidifiers, or warning lights — enabling true automated environmental control for your server room or warehouse.
- Powerful Network Integration & Open Protocols: Engineered for seamless system compatibility, this PoE server room temperature monitor supports Ethernet 10/100M, Modbus TCP, SNMP v1/v2, UDP, MQTT, DHCP, and RS-485 to Ethernet bridging. It easily connects with BMS, SCADA, DCIM, or custom IoT dashboards for centralized visibility. View and adjust MAC address, IP, and protocol settings directly from its browser-based interface.
- Local Data Logging & No Subscription Fees: Unlike cloud-dependent devices, the server room temperature monitor stores up to 100,000 records locally with a customizable sampling interval as low as 2 minutes. Historical logs can be exported in CSV format for compliance, audits, or trend analysis. Data stays secure on-site — no monthly fees, no forced cloud account, and no risk of lost records during network downtime.
Configure Mosquitto authentication
Create a broker password file before starting Mosquitto. The command below runs Mosquitto’s password utility in a temporary container and prompts for the password without placing it in shell history:
docker run --rm -it
-v "$PWD/mosquitto/config:/mosquitto/config"
eclipse-mosquitto:2
mosquitto_passwd -c /mosquitto/config/passwd hauserAdd a minimal mosquitto.conf in mosquitto/config/:
listener 1883
allow_anonymous false
password_file /mosquitto/config/passwd
persistence true
persistence_location /mosquitto/data/
log_dest file /mosquitto/log/mosquitto.logThe listener accepts MQTT on the container’s port 1883, anonymous access is disabled, and retained broker state is stored under the mounted data directory. If your installation requires remote clients, expose the port only to the networks that need it. Add TLS when the broker is reached over an untrusted network; authentication alone does not encrypt MQTT traffic.
The Mosquitto app documentation describes creating MQTT users from Home Assistant’s Settings > People > Users page and notes that homeassistant and addons are reserved usernames. That workflow applies to the Home Assistant Mosquitto app. With a standalone Compose container, manage the password_file with mosquitto_passwd as shown above, and choose a different username such as hauser. The app documentation is at https://github.com/home-assistant/addons/blob/master/mosquitto/DOCS.md.
Save broker credentials and any app options before reinstalling. Home Assistant’s MQTT documentation warns that generated credentials are kept secret; losing them means you may need to recreate the account and update every client.
Start the containers and check their state
- From the directory containing
compose.yml, start the project in the background:docker compose up -d - Confirm both services are running:
docker compose ps - Inspect startup messages if either service is unhealthy or repeatedly restarting:
docker compose logs --tail=100 mosquitto docker compose logs --tail=100 homeassistant - Open Home Assistant at
http://<docker-host>:8123and complete its initial account setup.
A missing password file, a syntax error in mosquitto.conf, or a directory permission problem commonly causes Mosquitto to exit immediately. The logs identify which file or setting failed; correct it, then run docker compose up -d again.
Add the MQTT integration in Home Assistant
Home Assistant Container does not require a special broker hostname or a host-network mode. Add the integration through the web interface:
- Open Settings > Devices & services.
- Select Add Integration.
- Search for and select MQTT.
- For the broker address, enter
mosquitto, the Compose service name. Do not enterlocalhostor127.0.0.1from inside the Home Assistant container. - Enter port
1883, the username created in the password file, and its password. - Submit the form and check that the integration appears as configured.
Compose’s internal DNS maps the service name to the Mosquitto container on ha-net. If you rename the service, use the new service name as the hostname. If the broker is on a different machine instead, use that machine’s DNS name or IP address and ensure routing and firewall rules permit TCP 1883 (or the TLS listener you configured).
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Clear out junk files and repair common Windows errors3Scan for outdated or missing drivers - takes under a minuteRank #3
- Supports Multiple Industry-Standard Communication Protocols: Modbus TCP, SNMP, BACnet, and MQTT. Our system is compatible with all these protocols and can deliver data in multiple formats simultaneously. Comprehensive support for SNMP v1/v2/v3 and SNMP Trap v2c/v3 with high security level.
- A web service can be enabled to view sensor data directly through a browser. Support for the REST API protocol can also be enabled to return JSON data from the sensors. However, these two features are disabled by default for network security reasons, and can be enabled by configuration tool.
- Can be integrated to AWS/Azure/Tuya loT cloud directly with low cost. Can be directly integrated into Home Assistant.
- Wifi network. Provides reliable Wi-Fi connectivity with native support for WPA-Enterprise and 802.1X authentication, enabling seamless integration into enterprise-grade security architectures.
- Proactive Alerts – Instant email notifications when thresholds are exceeded (fully customizable triggers). IFTTT Automation – Trigger smart actions (e.g., activate HVAC, log to Google Sheets, or Telegram alerts) via Webhook integration.
Home Assistant’s MQTT integration documentation, including connection settings and supported behavior, is available at https://www.home-assistant.io/integrations/mqtt. The default keep-alive is 60 seconds; do not configure a value below 15 seconds.
Verify publish and subscribe before adding devices
Testing the broker independently separates Docker and authentication problems from device-specific problems. The official Home Assistant example publishes a message and then subscribes to the Home Assistant topic tree:
mosquitto_pub -h 127.0.0.1 -t homeassistant/switch/1/on -m "Switch is ON"
mosquitto_sub -h 127.0.0.1 -v -t "homeassistant/#"Because the Compose example binds port 1883 to the Docker host’s loopback interface, run those commands on the Docker host. Add the username and password options when anonymous access is disabled:
mosquitto_pub -h 127.0.0.1 -p 1883
-u hauser -P 'your-password'
-t homeassistant/switch/1/on -m "Switch is ON"
mosquitto_sub -h 127.0.0.1 -p 1883
-u hauser -P 'your-password'
-v -t 'homeassistant/#'When the MQTT client runs in another container on ha-net, replace 127.0.0.1 with mosquitto. When it runs on a different host, use the broker host’s address and the published port. A successful subscription prints the topic and payload; if it prints nothing, publish a message in a second terminal while the subscription remains active.
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallCrashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteHome Assistant also has built-in controls under the MQTT integration’s Configure screen for publishing a packet and listening to a topic. These controls are useful when the command-line MQTT clients are not installed on the host.
Use MQTT discovery to create entities automatically
MQTT discovery is enabled by default. Home Assistant uses the homeassistant discovery prefix unless you change it. A device first publishes a configuration payload to a discovery topic. Home Assistant reads the payload, then subscribes to the state topic and publishes commands to the command topic named by that payload.
A documented switch pattern is:
| Purpose | Topic |
|---|---|
| Discovery configuration | homeassistant/switch/irrigation/config |
| State published by the device | homeassistant/switch/irrigation/state |
| Command sent by Home Assistant | homeassistant/switch/irrigation/set |
The configuration payload identifies the entity and its state and command topics, plus the payload values that represent on and off. Publish that configuration to the /config topic, then publish the current state to the state topic. When Home Assistant sends a command, the device listens on the /set topic and updates its state topic after acting on the command.
Rank #4
- 4-in-1 Environmental Monitor (TVOC, CO₂,Temperature,Humidity). High accuracy:Temperature measurement accuracy: ± 0.3° C; Humidity measurement accuracy: ±3%;CO₂ measuring range: 0-2000ppm.
- Supports Multiple Industry-Standard Communication Protocols: Modbus TCP, SNMP, BACnet, and MQTT. Our system is compatible with all these protocols and can deliver data in multiple formats simultaneously. Comprehensive support for SNMP v1/v2/v3 and SNMP Trap v2c/v3 with high security level.
- Can be integrated to AWS/Azure/Tuya loT cloud directly with low cost. Can be directly integrated into Home Assistant
- Proactive Alerts – Instant email notifications when thresholds are exceeded (fully customizable triggers). IFTTT Automation – Trigger smart actions (e.g., activate HVAC, log to Google Sheets, or Telegram alerts) via Webhook integration.
- PoE power supply: Centralized power supply: Simply provide uninterrupted power supply at the PoE switch to ensure power supply to the sensor.
Retain the discovery configuration when the device must be reconstructed after a Home Assistant restart. A retained configuration remains available when Home Assistant reconnects. An alternative is to subscribe to Home Assistant’s birth message on homeassistant/status and republish discovery whenever the payload announces online. This is useful for devices that do not retain their configuration, but the device must implement the status subscription and republish logic.
Do not confuse retained discovery configuration with retained state. Retain the configuration deliberately; choose state-retention behavior according to the device’s safety requirements so a stale value cannot unexpectedly operate hardware.
Network exposure, TLS, and credentials
Keep the broker internal when possible
If every MQTT client is inside the Compose network, omit the Mosquitto ports mapping. Home Assistant still reaches mosquitto:1883, but the broker is not published on the host. This is the smallest exposure surface.
Publish only to required interfaces
For host-local administration, bind 127.0.0.1:1883:1883. For LAN devices, bind to the host’s LAN address or publish the port and restrict it with the host firewall. Do not assume that a Docker bridge network is an access-control policy for devices outside Docker.
Encrypt untrusted links
Use TLS when MQTT crosses an untrusted network, such as a routed network you do not control. Configure Mosquitto’s certificate and key settings, mount those files read-only where practical, and configure Home Assistant and every device with the broker’s TLS listener and certificate expectations. Keep port 1883 limited to trusted networks if you also provide a non-TLS listener.
Free tools Windows power users keep installed
One-click scans. No signup required.
Protect secrets operationally
Use unique credentials, avoid placing passwords in version control, and restrict access to mosquitto/config/passwd. Rotate a credential by creating or changing the account with mosquitto_passwd, updating Home Assistant’s MQTT integration, and then updating other clients. Keep a secure copy of the password-management procedure and certificate material; a backup of the Compose file alone is not sufficient.
Persistence, upgrades, and backups
The bind mounts in the Compose file are part of the design, not optional conveniences:
Best Value
- Smart WiFi Control: Monitor indoor thermometer data anytime, anywhere. The gateway can be connected through WiFi via the app, pairing up to 10 humidity temperature sensors. Boasts a 2-year battery life (Supports 2.4GHz Wifi networks only)
- High-Precision Readings: The Swiss-made WiFi temperature sensor provides precise readings, measuring temperatures with ±0.54°F / ±0.3℃ accuracy and humidity within ±3% RH. Data is refreshed every 2s, ideal for wine cellars.
- Remote Alarm: You can preset temperature and humidity values via the app. When the hygrometer thermometer sensor detects a change, you'll receive a notification via app and email, offering enough time to react through the alarm function.Only support gateway H5151/H5042.
- Data Storage & Export: This humidity monitor uploads data to the app via WiFi and Bluetooth. View the temperature and humidity trend chart from the past 20 days and export data from the past 2 years. Ideal for greenhouses, farms, etc.
- Compact & Portable Design: This indoor thermometer adopts a compact and stylish design equipped with a lanyard, suitable for any corner of the room, such as drawers, wine cabinets, guitar cases, etc.
./homeassistant:/configpreserves Home Assistant’s integrations, entities, automations, and settings../mosquitto/config:/mosquitto/configpreserves the broker configuration and password file../mosquitto/data:/mosquitto/datapreserves Mosquitto’s persistent session and retained-message data../mosquitto/log:/mosquitto/logpreserves broker logs for diagnosis and auditing.
Back up the project directory while the services are stopped or while you have a consistent application-level backup. At minimum, include Home Assistant’s /config, Mosquitto’s config and data, and the TLS files if you use TLS. Test restoration on a separate directory before an upgrade.
For an image update, pull the new images, recreate the containers, and verify the integration and discovery entities:
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=100 mosquittoBecause state is outside the containers, replacing an image should not erase configuration. Never delete the bind-mounted directories as part of routine cleanup.
Compose versus an external broker
A broker in the same Compose project is usually the simplest arrangement for a single Docker host. An external broker can be preferable when several Home Assistant instances, multiple hosts, or independently managed applications need one central MQTT service.
| Decision axis | Mosquitto in the same Compose project | Broker on another host |
|---|---|---|
| Broker hostname | mosquitto, resolved on the shared Compose network |
Broker DNS name or IP address; localhost refers to the client host, not the broker |
| Network exposure | Can remain internal by omitting ports; publish 1883 only when needed |
Requires routing, firewall rules, and a reachable listener between hosts |
| Authentication and TLS | Username/password on the local network; add TLS for untrusted links | Treat the connection as a network boundary and use authentication plus TLS where the path is untrusted |
| Persistence and backup | Back up the Compose bind mounts for both services | Broker storage and backup are owned by the separate host or service |
| Discovery behavior | Uses the same homeassistant prefix and retained or birth-triggered configuration |
Unchanged, provided Home Assistant can connect to the broker |
| Operational ownership | One Compose project controls upgrades, logs, and recovery | Broker lifecycle, monitoring, and upgrades are managed independently |
| Cost or benchmark | Not stated in the official documentation | Not stated in the official documentation |
Whichever location you choose, the MQTT integration settings remain the same except for the broker hostname, port, and security options.
Troubleshoot the failures that matter most
Home Assistant reports that the broker is unreachable
- Confirm both services are on the same Compose network:
docker compose configshould showha-netfor each service. - Use
mosquittoas the hostname from Home Assistant. Do not uselocalhostor the host’s published address for container-to-container traffic. - Check
docker compose logs mosquittofor a failed listener, missing password file, or invalid configuration. - Verify that the integration uses port
1883and the exact username and password in the broker password file.
Connection is refused on port 1883
Check whether the broker is listening inside the container and whether a host port was published. If you removed ports, a client on the Docker host cannot use 127.0.0.1:1883; use a client on the Compose network or add a restricted host binding. If remote devices cannot connect, inspect the host firewall and the interface address used by the port mapping.
Authentication fails
Make sure allow_anonymous false matches your intended policy and that password_file points to the mounted path. Recreate or change the account with mosquitto_passwd, then update Home Assistant’s integration. Check for shell quoting errors when a password contains special characters.
Messages publish but no entity appears
- Subscribe to
homeassistant/#and verify that the discovery configuration is published to the expectedhomeassistant/.../configtopic. - Ensure the configuration payload names valid state and command topics and that those topics receive messages.
- Retain the configuration or implement the
homeassistant/statusbirth-message republish path. - Check the MQTT integration’s device and entity list after correcting the payload.
Entities disappear after a restart
The broker may have lost its data directory, or the discovery configuration was not retained and the device did not republish it after Home Assistant announced online. Verify the ./mosquitto/data mount, preserve retained discovery messages, and implement birth-message handling for non-retaining devices.
Messages appear delayed or clients disconnect
Check the keep-alive setting and network stability. Home Assistant’s default is 60 seconds, and the value should not be below 15 seconds. Review Mosquitto logs for repeated authentication failures or connection churn before changing timeouts.
Quick Recap
Operational checklist
- Home Assistant and Mosquitto run as separate Compose services.
- Both services share a Compose network, and Home Assistant uses
mosquittoas the broker hostname. - Home Assistant’s
/configand Mosquitto’s configuration, data, and logs are persistent mounts. - Mosquitto uses a username/password and MQTT protocol version 5 support.
- Port 1883 is internal or narrowly published, rather than exposed unnecessarily.
- TLS protects any MQTT connection that crosses an untrusted network.
- The MQTT integration is configured under Settings > Devices & services.
mosquitto_pubandmosquitto_subcan exchange a test message.- Discovery configuration is retained or republished after
homeassistant/statusannouncesonline. - Credentials, configuration, retained data, and certificates are included in tested backups.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
