Hardware FixRecommendedDevice not working? Your driver may be the problemCheck updates for common hardware issues.Fix DriversHalloween DealsAmazon USHalloween week deals: useful picks before month-endAmazon US: current deals, useful picks and tech finds.Check DealsClean PCRecommendedOne scan can reveal what keeps slowing WindowsLook for cleanup and repair opportunities.Run Scan×
FREEDOM251

Freedom251 › Blog › apps

How to Run Home Assistant Add-ons in a Docker Compose Setup

By Freedom251 Team · · 10 min read

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

You cannot install native Home Assistant Add-ons (now called Apps) in a Home Assistant Container deployment managed by Docker Compose. Apps are installed and operated by the Home Assistant Supervisor, and the Container installation has no Supervisor. The Compose alternative is to run the underlying service as its own container next to Home Assistant, then connect it through Home Assistant’s supported integration or protocol.

If you specifically want the built-in Apps store, Supervisor-managed backups, and integrated lifecycle controls, use Home Assistant OS. Choose Home Assistant Container plus Compose when you are prepared to maintain the Linux host, images, networks, storage, credentials, backups, and updates yourself.

As an Amazon Associate I earn from qualifying purchases.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Home Assistant Add-ons versus Apps in Docker Compose

Home Assistant renamed add-ons to Apps, but the installation model did not change: Apps are containerized services configured and supervised by the Supervisor. The Supervisor also runs Home Assistant Core, manages backups, and controls App installation and lifecycle operations.

A Home Assistant Container installation is different. It runs Home Assistant Core in a container on a Linux system that you provide and maintain. The official Home Assistant FAQ states: “Home Assistant Container does not support apps, and you are responsible for updates and the host operating system.” Docker Compose can orchestrate Home Assistant and additional containers, but it does not add the Supervisor or recreate the Apps store.

#1 Best Overall
Sale
TOZO A1 Wireless Earbuds Bluetooth 5.3 Light Weight in Ear Headphones | IPX5 Waterproof,2 Mics for AI Calls,Immersive Premium Sound Bass Headset with Charging Case,32 EQ via App Black
  • [Ultra-Lightweight Ear Buds Designed for Small Ears] Each earbud weighs only 3.7g and features a compact, ergonomic in-ear design made especially for small ears. Secure, low-profile, and comfortable for workouts, all-day wear or overnight sleeping.The ultra-slim profile sits flush in your ear with no hard edges poking or rubbing, so you can even sleep on your side without discomfort.
  • [Immersive Stereo Sound with TOZO OrigX Technology] TOZO OrigX tuning delivers clear vocals, balanced mids, and natural stereo sound for music, podcasts, and videos.
  • [Long Battery Life for Daily Use] Get up to 7 hours of playtime on a single charge, with up to 32 hours total using the charging case—ideal for workdays, commuting, and extended listening sessions.
  • [Bluetooth 5.3 & Stable Connection] Bluetooth 5.3 provides fast pairing, stable wireless performance, and reduced dropouts as you move around home or office.
  • [Deep Bass with Clear Vocals] High-performance drivers produce punchy bass while keeping vocals clean and detailed for everyday listening.

Choose the installation that matches your goal

Capability Home Assistant OS Home Assistant Container with Compose
Native Apps/Add-ons store Supported through Supervisor Not supported
Supervisor-managed backups and lifecycle Supported Not available; you operate each container and its data
Host operating system Managed as part of the appliance-style installation You supply, secure, patch, and troubleshoot the Linux host
Service deployment Install compatible Apps from the Supervisor interface Run each required service as an independent container
Control over images, networks, and ports Abstracted by Supervisor Explicit Compose configuration and your responsibility
Hardware and privileged access Integrated where supported by Home Assistant OS and the App You must map devices, permissions, and host services yourself
Operational complexity Lower for users who want a managed appliance Higher, but with more direct Docker and Linux control

Home Assistant’s installation guidance recommends Home Assistant OS for most users, including people who want the integrated Apps experience. Container is aimed at people who already run Docker or who deliberately want to manage the host and all containers themselves.

What the Compose replacement actually looks like

Do not try to copy an App entry from the Home Assistant interface into a Compose file. Instead, translate the function into a normal service deployment:

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
  1. Identify the underlying service. An MQTT App is an MQTT broker; a file-sharing App provides file-sharing services; an editor App provides an editor process.
  2. Find a maintained container image. Use the service project’s own documentation for its image name, supported CPU architectures, configuration variables, and security requirements.
  3. Define persistent storage. Map a host directory or named volume for the service’s data and configuration. Without persistent storage, recreating a container can discard its state.
  4. Expose only required ports. Publish a port to the LAN only when clients outside the Compose network need it. Keep Home Assistant-to-service traffic internal whenever the service supports that arrangement.
  5. Join an intentional network. Put Home Assistant and related services on a Compose network. Inside that network, use the Compose service name as the hostname when the service documentation supports it.
  6. Configure the Home Assistant integration. Once the service is reachable, add its corresponding integration in Home Assistant and supply the hostname, port, credentials, and protocol required by that integration.

This is a functional replacement, not a conversion of the original App. Every service has its own image, volume layout, permissions, upgrade process, and security model.

Prepare the Compose project

Keep Home Assistant Core in its own Compose service and place auxiliary services in the same project only when that arrangement is useful for your operations. A clear directory layout makes backups and troubleshooting easier:

  • A dedicated directory for the Home Assistant /config bind mount or volume.
  • A separate data directory or named volume for every auxiliary service.
  • A Compose file whose image tags, ports, networks, environment variables, and restart policy are documented.
  • A written record of credentials, device mappings, ownership, and the procedure used to upgrade each image.

Use explicit paths rather than broad host mounts. A file-sharing or editing service that can write to the entire host is a much larger risk than one restricted to the Home Assistant configuration directory.

Step-by-step: run a former App beside Home Assistant

1. Verify that you are using Home Assistant Container

Apps require Supervisor. If your installation is Home Assistant OS or another Supervisor-based method, use its native Apps interface. If Home Assistant is a normal container started by Compose, plan for an independent service instead.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
Rank #2
Sale
Smart Watch for Men Women Compatible with iPhone Samsung Android Phone 1.69 inch Full Touch Screen IP68 Waterproof Bluetooh Fitness Tracker Heart Rate/Sleep Monitor (Black)
  • 【IP68 Waterproof Multifunctinal Smart Watch】Torjalph fitness activity tracker smart watch is IP68 waterproof technology ,you can wear it when swimming,handwashing,it's rain-proof which means that you perform multiple exercise modes outside without worrying about sweat or rain corroding your fitness smart watch,and this watch equipped with a 230 mAh large capacity battery magnetic charging ,and this sports activity tracker watch can be used 5-7 days If fully charged.
  • 【Larger 1.83'' Full Screen Watch & Multi-dial Selection】1.83 inch full HD color touch screen smart watch for men / women provides excellent 240*284 resolution image quality ,This Bluetooth smart watch offers a better touch experience and remarkable immersion and ,more than 200 watch faces for you to choose from App"Da Fit ", you can change the dial style according to your mood to wear keeping the world on your wrist
  • 【Accurate Activity Tracker Smart Watch 】sports watch activity tracker uses sweat and dust resistant breathable silicone strap, our Fitness Tracker Smart Watch for Android iOS Phones supports 12 sports modes,walking,running,bicycle,swimming,badminton,basketball,football,rope skipping. This bluetooth calls smart watch for men women is lightweight and stylish, bringing more convenient and relaxing sports experience while also providing more protection.
  • 【Your 24 Hour Personal Daily Health Monitor】Fitness watch for women men full touch screen IP67 waterproof bluetooth smartwatch for Android iOS Phones with heart rate blood pressure monitor multifunction Andriod smart watch with steps counter sleep monitor sports fitness watch, monitoring blood oxygen saturation allows you to understand your physical condition in real time to track fitness progress ,to know your health status in time.
  • 【More Functions Bluetooth Call Smart Watch】This fitness activity smart watch full screen for iPhone and Android phones includes a bunch of new features including:The bluetooth smart watch can hang up the phone, receive and display WhatsAPP /Text /Facebook /Twitter /Messenger reminder.Support sedentary reminder, alarm clock, stopwatch, timer,weather information,music control, remote camera control compatible with Android 5.0 and above or iOS 9.0 and above smartphones.

2. Define the service requirements

Read the service project’s documentation before writing Compose configuration. Record the required image, supported architecture, environment variables, configuration files, ports, persistent directories, user and group IDs, capabilities, devices, and any host-level dependencies. Do not assume that an image used by a Supervisor App can be dropped into Compose unchanged.

3. Create persistent storage

Give the service its own data location. Check the container’s expected ownership and permissions, then set the host directory accordingly. For Home Assistant itself, protect the directory mounted as /config; for each auxiliary service, back up its data directory or volume separately.

4. Add networking deliberately

Attach related services to an intentional Compose network. If Home Assistant connects to a broker or database over that network, configure the integration with the Compose service name instead of an address that can change when containers are recreated. Publish a host port only for clients that truly need LAN or internet access.

5. Set restart and lifecycle behavior

Choose a restart policy appropriate for your host and document whether the service should come back after a reboot. Record the image tag you selected. A deliberately pinned tag makes upgrades predictable; a floating tag reduces editing but can introduce an unplanned change during a pull.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

6. Start and verify the containers

From the directory containing your Compose file, start the project with the normal Compose command used by your installation. Confirm that Home Assistant and the auxiliary service are running, inspect logs for startup errors, and test the service directly on its documented port before configuring Home Assistant.

7. Add the Home Assistant integration

In Home Assistant, open the integration flow for the service you deployed. Enter the Compose service hostname or LAN address, the documented port, and credentials created for the service. Complete a functional test, such as publishing and receiving a test MQTT message, before relying on automations.

Rank #3
New Bee Guitar Cable 10ft Electric Instrument Bass AMP Cord | 6.35mm Jack, Durable Design, Stage and Home Studio Use, Low Noise Shielded Electric Cord for Bass, Keyboard, Amp, Mixer
  • [Low Noise High Fidelity] New bee guitar cord with 22AWG oxygen-free-copper center conductors provides enhanced signal transfer, the PVC insulation material and the high-density stranded copper double shield provide noise rejection for quiet operation
  • [Ideal for Choice] New bee 1/4 straight and right angle metal connectors, ensures a secure connection in any instrument, pedal, or amp jack. L shape great fro on stage guitar stands
  • [Wide Compatible] Suitable for mixer, power amplifier, microphone, effector, decoder, equalizer, electoronic organ, electric guitar, electric bass and other electronic equipments. Widely used in the installation of smart home, karaoke speaker, professional stage audio, etc
  • [Easy Disassemble] Making incidental repairs quick and easy! Very nice, flexible cable
  • [Dont Hesite to Order] 24 hours customer services and professional technology team are standing by

8. Record recovery instructions

Write down the image tag, data paths, credentials location, port assignments, network name, device mappings, and upgrade commands. Someone restoring the system should be able to rebuild the containers without guessing which host directory contains each service’s state.

Updating Home Assistant and the auxiliary services

Container users own the update process. The official Home Assistant Container flow is:

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
docker compose pull homeassistant
docker compose up -d

The first command retrieves the selected Home Assistant image; the second recreates the service with the new image while retaining the Compose configuration and mounted data. Apply the same disciplined approach to auxiliary services: read release notes, back up data, pull the intended image, recreate the container, and verify the Home Assistant integration afterward.

Do not treat an image pull as a backup. A backup must include Home Assistant’s /config and the persistent data for every auxiliary service. If a service stores important state in a database, use that database’s documented export or dump procedure in addition to copying its files.

Worked mapping: MQTT App to an MQTT broker container

The direct replacement for the MQTT App is an MQTT broker container. The broker is a separate service; Home Assistant connects to it through the MQTT integration.

  1. Choose a maintained broker image and follow its documentation for configuration and supported architectures.
  2. Persist the broker’s configuration, retained messages, authentication database, and other state in a dedicated volume or host directory.
  3. Place the broker and Home Assistant on the same Compose network when possible.
  4. Publish the broker’s MQTT port to the LAN only if physical devices or other clients connect from outside Docker. Keep administration interfaces private.
  5. Create broker credentials with only the permissions required by your devices and Home Assistant.
  6. Start the broker, inspect its logs, and test a publish/subscribe operation.
  7. In Home Assistant, add or configure the MQTT integration with the broker’s Compose service name, port, and credentials.

The service documentation controls the exact image name, file paths, authentication settings, and port numbers. The conceptual mapping is stable even though those implementation details differ between broker projects.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
Rank #4
BSIMB 15.6" Digital Family Calendar & Chore Chart, No Subscription Fees
  • Digital Family Calendar: BSIMB digital calendar wall touch screen puts an end to your chaotic life. Designed for busy families, the digital calendar keeps you organised and in step with your family. Assign different colours and tasks to each family member to make family scheduling easier and more intuitive.
  • Easy Setup and Auto-Sync: Plug in, connect to WLAN and auto-syn your electric calendar in minutes. Digital wall calendar compatible with Google calendar, iCloud calendar, Outlook calendar, Cozi calendar and Yahoo calendar. Add events directly on the device or through the ecalendar app. Electronic calendar stays current whether you're at work or traveling—no manual updates needed.
  • All-In-One Home Assistant: Smart calendar builds habits and encourage independence with personalised chores. Display daily meal plan to reduce the daily ‘What's for dinner?’ stress. To-do lists keep track of everything you want. Turning chores into valuable achievements with stars and rewards, making life easier and more enjoyable.
  • Manage Anytime Anywhere: BSIMB electronic calendar for family stay connected with the powerful ecalendar app. Access and manage your digital wall calendar anytime, anywhere with free features like stars & rewards, photo screensaver, chore charts, meals plans, to-do lists etc. Electronic planner paid features like Magic Import tailor advanced tools for users with special needs.
  • Stay in Touch with Loved Ones: Share photos or videos from your phone to electronic wall calendar with app, instantly update your life moment, and keep in touch with your family, especially those who are far away; you can also surprise your smart calendar digital wall by sending him a wish card; it's also great for keeping tech-illiterate elders in touch with the youngsters.

File sharing and configuration editors require extra caution

A file-sharing or editor App can be replaced by a separately managed service, but its access should be narrowly scoped. Mount only the Home Assistant configuration directory that the service must read or edit, preferably with the least write access compatible with the task. Do not expose an editor or file share directly to the internet. Protect it with authentication, restrict its network reachability, and review its logs.

Before changing configuration files through an external service, create a Home Assistant backup and preserve a known-good copy. A syntax error in a YAML file or an accidental permission change can prevent Home Assistant from starting even though the editor container itself appears healthy.

Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Support on Ko-Fi

Which Apps do not port cleanly?

Many Apps are ordinary network services and can be replaced with containers. Others depend on Supervisor APIs, host devices, D-Bus, privileged operations, or operating-system services. Those dependencies are the boundary of the Compose approach.

  • Supervisor-dependent behavior: a service may expect Supervisor-provided APIs or lifecycle callbacks that do not exist in Container.
  • D-Bus and host integration: an App may need system services or a host bus that is not available inside an ordinary container.
  • USB and other hardware: radios, serial adapters, storage devices, and cameras require explicit device mappings and host permissions. Recheck those mappings after Docker or host changes.
  • Privileged access: granting broad capabilities can make a service work, but increases the impact of a compromise. Confirm exactly which capability or device the project documents.
  • OS-level services: an App that configures the underlying operating system may require Home Assistant OS or a separately engineered host setup rather than a second container.

If the service cannot run without those Supervisor or host facilities, Home Assistant OS is usually the simpler and safer installation.

Free tools Windows power users keep installed

One-click scans. No signup required.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Networking, ports, and security decisions

Compose gives you control, but every exposed surface becomes your responsibility. Use the following rules when designing the project:

  • Keep internal service-to-service traffic on a private Compose network.
  • Publish only the ports required by LAN clients or explicitly documented integrations.
  • Do not expose administrative dashboards, file editors, or broker management endpoints to the public internet without a separately designed access-control layer.
  • Use strong, unique credentials for each service and store them outside publicly readable Compose files where practical.
  • After changing a service name, network, port, or credential, test the Home Assistant integration and any dependent automations.
  • Monitor logs for Home Assistant and every auxiliary container, not just the container that appears to be failing.

Backups and disaster recovery

Supervisor-based installations can coordinate backups for supported components. With Container, you must build that process yourself. A usable backup plan includes:

  1. Home Assistant’s complete /config directory.
  2. Each auxiliary service’s persistent data, configuration, and authentication database.
  3. A copy of the Compose file and any environment files, with secrets protected.
  4. A list of image tags, network names, published ports, host paths, device mappings, and required permissions.
  5. A restore test on a separate host or empty directory, so you know the backup contains usable data rather than merely files.

Back up before upgrades, before changing storage or permissions, and before migrating to another host. A container recreation is not itself a recovery strategy.

Troubleshooting common failures

Symptom Likely cause Checks and corrective action
The Apps store is missing You are running Home Assistant Container without Supervisor Use independent containers for required services or migrate to Home Assistant OS if native Apps are essential.
Home Assistant cannot connect to the service Wrong hostname, port, network, or credentials Confirm both containers share the intended network, use the Compose service name internally, verify the service is listening, and retest credentials.
Data disappears after recreation No persistent volume or bind mount was configured Review the service’s documented data directory and map it to durable host storage before rebuilding.
The service starts but cannot read or write files Host ownership, permissions, or user IDs do not match Check container logs and the project’s documented UID/GID requirements; correct permissions without granting broader host access.
A USB device is unavailable The device was not mapped into the container or its host path changed Check the host device, Compose device mapping, permissions, and whether another process already owns it.
An upgrade breaks the service Image behavior or configuration changed Read release notes, restore the last known-good data backup, select a deliberate image tag, and recreate the service with verified settings.
Home Assistant works but an automation fails The external service is reachable but its protocol, topic, share, or permission changed Test the protocol directly, inspect both sets of logs, and verify integration settings after every network or credential change.

Supervisor App development is a separate case

The Apps documentation records a version-sensitive change in Supervisor 2026.04.0: Supervisor stopped supplying a default BUILD_FROM argument when building an App. App developers must now use an explicit base image, and pinned base-image versions are recommended for build stability.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

This change matters when you are building a Supervisor App for a Supervisor-based installation. It does not make Apps available in Home Assistant Container and does not change the normal process for consuming a published service image in Compose.

When moving to Home Assistant OS is the better answer

Select Home Assistant OS when your priority is the Apps store, Supervisor-managed updates and backups, or an appliance-like installation with less host administration. It is also the practical choice when a required service depends on Supervisor APIs, D-Bus, privileged host integration, or operating-system services that you do not want to engineer manually.

Stay with Container plus Compose when you already operate Linux and Docker confidently, need direct control over images and networks, or want each service to follow its own deployment and upgrade schedule. That flexibility comes with ownership of patching, monitoring, permissions, backups, and recovery.

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.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

appsDockerDocker ComposeHome AssistantHome Assistant ContainerHome Assistant OSMQTTself-hosting

Leave a Reply

Your email address will not be published. Required fields are marked *

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Recommended PC Tool
Recommended PC Tool
PC Slower Than It Used to Be?Free scan - under a minute
Outdated Drivers Are Slowing You DownFree scan - exact matches

Two free Windows tools

One Free Minute Could Fix That PC

Before you go - each of these free tools takes about a minute and tackles what quietly slows a Windows PC down.

Special offer. View Outbyte info, uninstall instructions, EULA, and Privacy Policy.