If you run Home Assistant itself in Docker, alongside a pile of other docker compose stacks on the same box (or across a few boxes), you’ve probably felt the gap: Portainer works, but it’s not in Home Assistant — it’s another tab, another login, another thing to check separately from the dashboard you actually live in.
I built Docker Compose Manager to close that gap — a custom integration that turns your Compose stacks into real HA devices and entities, with a dashboard you can build right alongside everything else.
What it actually does
- Auto-discovers your stacks. Point it at your stacks root (wherever your
docker-compose.ymlfolders live) and it finds everything — no manual entity setup per container. - Real state, CPU, and memory sensors per stack and per service, polled concurrently so it stays fast even with a lot of stacks.
- Pull & recreate, right from HA — a button that runs
docker compose pull && up -d, using a detached, resumable exec mechanism, so a slow pull surviving an HA restart doesn’t leave you guessing what happened. - Genuine version tracking — not just “is there an update,” but what version you’re actually running, what the newest real release is, and (via digest correlation) what version you’d actually get if you pulled right now. Pulls from GitHub releases and walks the image registry’s own tag list directly, so it works even for images with no useful OCI labels.
- Multi-host support. One HA instance, multiple Docker hosts (I run a Synology NAS and a Raspberry Pi side by side) — each gets its own config entry, fully independent.
- Built on a docker-socket-proxy + sidecar architecture, so HA never touches your raw Docker socket directly — the integration only ever gets the specific permissions it actually needs.
- A self-referential-stack protection mechanism — if you run HA itself (or the sidecar/proxy) as one of your own managed stacks, it won’t let you accidentally pull-and-recreate the very thing running the integration out from under itself.
Dashboard
There’s an example dashboard in the repo — click a stack, see its compose config, its containers, current vs. available versions, and pull/restart controls, all without leaving the page. It needs a couple of HACS frontend cards (auto-entities, button-card) and one helper entity — details in the repo.
Install
Manual for now — copy custom_components/ha_docker_compose into your HA config, restart, add the integration, point it at your stacks root. Full setup (including the socket-proxy/sidecar side) is in the repo’s docs/deploy/ folder.
github.com/skyw33/ha-docker-compose
Why I built it
Portainer announced a pivot toward Kubernetes-first, and rather than keep leaning on a tool drifting away from my actual use case, I built something purpose-fit for “I run HA and a bunch of other stuff in Compose, and I want it to feel like it all lives in one place.”
ha-docker-compose brings your container infrastructure natively into Home Assistant by organizing your workflows around logical docker-compose.yml stacks rather than a flat, disconnected list of containers. It is built on a least-privilege socket-proxy and sidecar architecture that completely sandboxes your core instance while scaling to multi-host environments—allowing you to manage local boxes and remote NAS setups side by side from a single interface. Beyond basic state monitoring, it delivers true version intelligence by walking image registries and correlating digests for update tracking.
Still actively using and improving this on my own setup, so feedback, issues, and PRs are genuinely welcome — especially if you hit an image/ registry combination that trips up the version-detection logic, since that’s been the trickiest part to get right across different projects’ tagging conventions.