From 60ab98ae36abe712c825f7828394d3e3e98c888a Mon Sep 17 00:00:00 2001
From: generalmat82 <110256073+generalmat82@users.noreply.github.com>
Date: Sat, 22 Nov 2025 05:32:31 -0500
Subject: [PATCH] feat(docker): hide containers with label homarr.hide (#4506)

Co-authored-by: Meier Lukas <meierschlumpf@gmail.com>
---
 packages/docker/src/index.ts           |  1 +
 packages/docker/src/labels.ts          |  4 ++++
 packages/request-handler/package.json  |  1 +
 packages/request-handler/src/docker.ts | 12 +++++-------
 pnpm-lock.yaml                         |  3 +++
 5 files changed, 14 insertions(+), 7 deletions(-)
 create mode 100644 packages/docker/src/labels.ts

diff --git a/packages/docker/src/index.ts b/packages/docker/src/index.ts
index 131507d6a..bd8f5dc2a 100644
--- a/packages/docker/src/index.ts
+++ b/packages/docker/src/index.ts
@@ -8,3 +8,4 @@ export type { Docker };
 export const containerStates = ["created", "running", "paused", "restarting", "exited", "removing", "dead"] as const;
 
 export type ContainerState = (typeof containerStates)[number];
+export * from "./labels";
diff --git a/packages/docker/src/labels.ts b/packages/docker/src/labels.ts
new file mode 100644
index 000000000..84bf0071f
--- /dev/null
+++ b/packages/docker/src/labels.ts
@@ -0,0 +1,4 @@
+export const dockerLabels = {
+  // Label to hide a container from Homarrs docker integration
+  hide: "homarr.hide",
+} as const;
diff --git a/packages/request-handler/package.json b/packages/request-handler/package.json
index 8592069e1..4f1238365 100644
--- a/packages/request-handler/package.json
+++ b/packages/request-handler/package.json
@@ -26,6 +26,7 @@
     "@homarr/common": "workspace:^0.1.0",
     "@homarr/db": "workspace:^0.1.0",
     "@homarr/definitions": "workspace:^0.1.0",
+    "@homarr/docker": "workspace:^0.1.0",
     "@homarr/integrations": "workspace:^0.1.0",
     "@homarr/log": "workspace:^0.1.0",
     "@homarr/redis": "workspace:^0.1.0",
diff --git a/packages/request-handler/src/docker.ts b/packages/request-handler/src/docker.ts
index cd82688d3..7a6d27be5 100644
--- a/packages/request-handler/src/docker.ts
+++ b/packages/request-handler/src/docker.ts
@@ -3,9 +3,9 @@ import type { ContainerInfo, ContainerStats } from "dockerode";
 
 import { db, like, or } from "@homarr/db";
 import { icons } from "@homarr/db/schema";
+import type { ContainerState } from "@homarr/docker";
+import { dockerLabels, DockerSingleton } from "@homarr/docker";
 
-import type { ContainerState } from "../../docker/src";
-import { DockerSingleton } from "../../docker/src";
 import { createCachedWidgetRequestHandler } from "./lib/cached-widget-request-handler";
 
 export const dockerContainersRequestHandler = createCachedWidgetRequestHandler({
@@ -27,13 +27,11 @@ async function getContainersWithStatsAsync() {
   const containers = await Promise.all(
     dockerInstances.map(async ({ instance, host }) => {
       const instanceContainers = await instance.listContainers({ all: true });
-      return instanceContainers.map((container) => ({
-        ...container,
-        instance: host,
-      }));
+      return instanceContainers
+        .filter((container) => dockerLabels.hide in container.Labels === false)
+        .map((container) => ({ ...container, instance: host }));
     }),
   ).then((res) => res.flat());
-
   const likeQueries = containers.map((container) => like(icons.name, `%${extractImage(container)}%`));
 
   const dbIcons =
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 4e3ff5075..25b1ef49d 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -1895,6 +1895,9 @@ importers:
       '@homarr/definitions':
         specifier: workspace:^0.1.0
         version: link:../definitions
+      '@homarr/docker':
+        specifier: workspace:^0.1.0
+        version: link:../docker
       '@homarr/integrations':
         specifier: workspace:^0.1.0
         version: link:../integrations