feat(docker): add endpoint filtering and setup assistant

2026-08-18 17:47:31 +02:00
1 parent 315245e048
commit f9e62a4932
@@ -58,12 +58,12 @@ A random secret can be generated by using the following command: `openssl rand -

 ## Docker

-| Environment Variable  | Description                                                                                                                                                                                               | Possible values                                         | Default |
-| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | ------- |
-| `DOCKER_ENDPOINTS`    | JSON array of named, capability-scoped Docker or Podman endpoints. Supports socket, explicitly insecure TCP, and TLS transports. See the [Docker and Podman integration guide](/docs/integrations/docker) | A JSON array of endpoint descriptors                    | -       |
-| `DOCKER_HOSTNAMES`    | Legacy comma-separated list of plaintext TCP hostnames. Ignored when `DOCKER_ENDPOINTS` is set                                                                                                            | For example `localhost,docker.example.com`              | -       |
-| `DOCKER_PORTS`        | Legacy comma-separated list of plaintext TCP ports. Ignored when `DOCKER_ENDPOINTS` is set                                                                                                                | For example `2375,2376`                                 | -       |
-| `DOCKER_SOCKET_PATHS` | Legacy comma-separated list of mounted Docker-compatible socket paths. Ignored when `DOCKER_ENDPOINTS` is set                                                                                             | For example `/var/run/docker.sock,/var/run/podman.sock` | -       |
+| Environment Variable  | Description                                                                                                                                                                                                                                                   | Possible values                                         | Default |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | ------- |
+| `DOCKER_ENDPOINTS`    | JSON array of named, capability-scoped Docker or Podman endpoints. Each stable `id` can be selected in Docker widgets. Supports socket, explicitly insecure TCP, and TLS transports. See the [Docker and Podman integration guide](/docs/integrations/docker) | A JSON array of endpoint descriptors                    | -       |
+| `DOCKER_HOSTNAMES`    | Legacy comma-separated list of plaintext TCP hostnames. Ignored when `DOCKER_ENDPOINTS` is set                                                                                                                                                                | For example `localhost,docker.example.com`              | -       |
+| `DOCKER_PORTS`        | Legacy comma-separated list of plaintext TCP ports. Ignored when `DOCKER_ENDPOINTS` is set                                                                                                                                                                    | For example `2375,2376`                                 | -       |
+| `DOCKER_SOCKET_PATHS` | Legacy comma-separated list of mounted Docker-compatible socket paths. Ignored when `DOCKER_ENDPOINTS` is set                                                                                                                                                 | For example `/var/run/docker.sock,/var/run/podman.sock` | -       |

 ## Database

@@ -167,12 +167,37 @@ Supported transports are:
 Plaintext Docker TCP can grant unauthenticated control of the Docker host. Prefer a local socket, a least-privilege socket proxy, or TLS. The structured configuration refuses TCP unless `allowInsecure` is explicitly set to `true`.
 :::

+For example, two socket proxies can be configured as separate environments:
+
+```yaml
+environment:
+  DOCKER_ENDPOINTS: >-
+    [
+      {
+        "id": "home",
+        "name": "Home Docker",
+        "kind": "docker",
+        "transport": { "type": "tcp", "host": "docker-proxy-home", "port": 2375, "allowInsecure": true },
+        "capabilities": ["inventory", "logs", "lifecycle"]
+      },
+      {
+        "id": "lab",
+        "name": "Lab Docker",
+        "kind": "docker",
+        "transport": { "type": "tcp", "host": "docker-proxy-lab", "port": 2375, "allowInsecure": true },
+        "capabilities": ["inventory", "logs"]
+      }
+    ]
+```
+
+Homarr must be attached to the Docker network of each proxy, and every configured host must be reachable from the Homarr container.
+
 When `DOCKER_ENDPOINTS` is set, it takes precedence over the legacy `DOCKER_SOCKET_PATHS`, `DOCKER_HOSTNAMES`, and `DOCKER_PORTS` variables.

 ### Managing your Docker containers within Homarr

 Homarr allows you to interact with Docker containers running on your system.
-The **Service setup** section compares the visible containers with your existing Homarr apps and integrations. It keeps every service distinct by Docker endpoint and container ID, including multiple containers that use the same integration type.
+The collapsed **Assisted Docker setup** helper optionally compares visible containers with your existing Homarr apps and integrations. Open it only when you want setup suggestions; it never blocks normal container management. Every service stays distinct by Docker endpoint and container ID, including multiple containers that use the same integration type.

 Homarr can show a service as:

@@ -187,7 +212,7 @@ Suggested addresses are ranked and explain where they came from. A published add
 Service discovery is read-only. Homarr never creates or changes an app or integration automatically; use the action on an individual suggestion to review and confirm its setup.
 :::

-Use the inbox filters to focus on services that need attention or those already represented in Homarr. Refresh runs discovery again. Dismissed suggestions are stored in the current browser using their endpoint-qualified service identity and can be restored from the same panel. If multiple existing items could match, Homarr marks the result as ambiguous and does not choose one automatically.
+Suggestions appear as a compact task list. Expand an item only when you want to inspect its address, match confidence, or observed health layers. Use the filters to focus on services that need attention or those already represented in Homarr. Refresh runs discovery again. Dismissed suggestions are stored in the current browser using their endpoint-qualified service identity and can be restored from the same helper. If multiple existing items could match, Homarr marks the result as ambiguous and does not choose one automatically.

 The health badges are an evidence-based projection across Docker, integration configuration, app representation, and persisted widget links. Authentication, API request success, and widget query execution are labeled **Not observed** because Homarr does not currently retain trustworthy last-run results for these layers. Use the suggested integration test or board action to diagnose them live; **Not observed** is never presented as healthy.

@@ -216,6 +241,10 @@ This opens a dedicated page with an xterm.js terminal that streams the container
 The Docker management table supports optional **CPU usage** and **Memory usage** columns.
 These columns are hidden by default and can be toggled on from the table column visibility settings.

+#### Choosing Docker environments in the widget
+
+The Docker widget can show one or more configured Docker environments. Leave **Docker environments** empty to include every endpoint, which is also the default for existing widgets. Selecting one or more entries limits container and statistics requests to those endpoints.
+
 #### Add apps from containers

 Homarr also lets you add apps from containers. You can simply select all containers you want to add an app for and then click the `Add to Homarr` button.
@@ -110,6 +110,10 @@ Pass those pairs unchanged to `docker.startAll`, `docker.stopAll`, `docker.resta
 names use underscores, such as `docker_restartAll`. Endpoint qualification prevents identical container IDs on different
 Docker or Podman endpoints from targeting the wrong service.

+`docker.getContainers` also accepts an optional `endpointIds` array. Omit it or pass an empty array to query every configured
+Docker environment, or pass one or more IDs returned by `docker.getEndpoints` to query only those Dockerode clients. The
+Docker widget uses the same behavior for its environment selector.
+
 ## Partial integration failures

 Multi-integration widget queries keep data from integrations that remain available. Calendar and media-server results include
@@ -1,22 +1,34 @@
 "use client";

-import { useEffect, useState } from "react";
+import { useEffect, useId, useState } from "react";
 import {
+  ActionIcon,
  Alert,
  Avatar,
  Badge,
  Button,
-  Card,
+  Collapse,
+  Divider,
  Group,
+  Paper,
  SegmentedControl,
  Select,
  SimpleGrid,
  Stack,
  Text,
  TextInput,
+  ThemeIcon,
+  Tooltip,
 } from "@mantine/core";
 import { useLocalStorage } from "@mantine/hooks";
-import { IconAlertTriangle, IconArrowRight, IconEyeOff, IconPlugConnected, IconRefresh } from "@tabler/icons-react";
+import {
+  IconAlertTriangle,
+  IconArrowRight,
+  IconChevronDown,
+  IconEyeOff,
+  IconRefresh,
+  IconSparkles,
+} from "@tabler/icons-react";

 import type { RouterOutputs } from "@homarr/api";
 import { clientApi } from "@homarr/api/client";
@@ -39,8 +51,13 @@ type ServiceHealth = RouterOutputs["docker"]["getServiceHealth"]["services"][num
 export const DockerReconciliation = () => {
  const t = useScopedI18n("docker.reconciliation");
  const utils = clientApi.useUtils();
+  const panelId = useId();
+  const [isOpen, setIsOpen] = useLocalStorage({
+    key: "homarr-docker-reconciliation-open",
+    defaultValue: false,
+  });
  const reconciliation = clientApi.docker.reconcileServices.useQuery();
-  const health = clientApi.docker.getServiceHealth.useQuery();
+  const health = clientApi.docker.getServiceHealth.useQuery(undefined, { enabled: isOpen });
  const refreshInventory = clientApi.docker.refreshInventory.useMutation({
    async onSuccess() {
      await Promise.all([
@@ -79,86 +96,112 @@ export const DockerReconciliation = () => {

  const unavailableEndpoints = reconciliation.data.endpoints.filter(({ status }) => status === "unavailable");
  const candidates = filterDockerReconciliationInbox(reconciliation.data.candidates, filter, dismissedCandidateKeys);
-  const attentionCount = health.data
-    ? health.data.services.filter(
-        ({ key, status }) =>
-          ["newRecognized", "newApp", "moved"].includes(status) && !dismissedCandidateKeys.includes(key),
-      ).length
-    : 0;
+  const attentionCount = reconciliation.data.candidates.filter(
+    ({ candidateKey, state }) =>
+      ["newRecognized", "newApp", "moved"].includes(state) && !dismissedCandidateKeys.includes(candidateKey),
+  ).length;
  const isRefreshing = refreshInventory.isPending || reconciliation.isFetching || health.isFetching;
+  const toggleLabel = isOpen ? t("action.hide") : t("action.review");

  return (
-    <Card withBorder>
-      <Stack>
+    <Paper withBorder p="sm">
+      <Stack gap={isOpen ? "sm" : 0}>
        <Group justify="space-between" align="start">
-          <div>
-            <Group gap="xs">
-              <IconPlugConnected size={20} />
-              <Text fw={600}>{t("title")}</Text>
-            </Group>
-            <Text c="dimmed" size="sm">
-              {t("description")}
-            </Text>
-          </div>
-          {health.data && <Badge variant="light">{t("attention", { count: String(attentionCount) })}</Badge>}
-        </Group>
-
-        <Group justify="space-between">
-          <SegmentedControl
-            value={filter}
-            onChange={(value) => setFilter(value as DockerReconciliationInboxFilter)}
-            data={[
-              { value: "attention", label: t("filter.attention") },
-              { value: "represented", label: t("filter.represented") },
-              { value: "all", label: t("filter.all") },
-            ]}
-          />
-          <Group gap="xs">
-            {dismissedCandidateKeys.length > 0 && (
-              <Button variant="subtle" size="xs" onClick={() => setDismissedCandidateKeys([])}>
-                {t("action.restoreDismissed", { count: String(dismissedCandidateKeys.length) })}
-              </Button>
-            )}
-            <Button
-              variant="light"
-              size="xs"
-              loading={isRefreshing}
-              leftSection={<IconRefresh size={14} />}
-              onClick={() => refreshInventory.mutate()}
-            >
-              {t("action.refresh")}
-            </Button>
+          <Group gap="sm" wrap="nowrap" style={{ minWidth: 0 }}>
+            <ThemeIcon variant="light" size="lg" radius="md">
+              <IconSparkles size={18} />
+            </ThemeIcon>
+            <div>
+              <Group gap="xs">
+                <Text fw={600}>{t("title")}</Text>
+                <Badge variant="light" color={attentionCount > 0 ? "blue" : "gray"} aria-live="polite">
+                  {t("suggestions", { count: String(attentionCount) })}
+                </Badge>
+              </Group>
+              <Text c="dimmed" size="sm">
+                {t("description")}
+              </Text>
+            </div>
          </Group>
+          <Button
+            variant="subtle"
+            size="compact-sm"
+            rightSection={
+              <IconChevronDown
+                size={15}
+                style={{ transform: isOpen ? "rotate(180deg)" : undefined, transition: "transform 150ms ease" }}
+              />
+            }
+            aria-expanded={isOpen}
+            aria-controls={panelId}
+            onClick={() => setIsOpen((current) => !current)}
+          >
+            {toggleLabel}
+          </Button>
        </Group>

-        {unavailableEndpoints.length > 0 && (
-          <Alert color="yellow" icon={<IconAlertTriangle size={16} />}>
-            {t("endpointUnavailable", { names: unavailableEndpoints.map(({ name }) => name).join(", ") })}
-          </Alert>
-        )}
-
-        {candidates.length === 0 ? (
-          <Text c="dimmed" size="sm">
-            {reconciliation.data.candidates.length === 0 ? t("empty") : t("emptyFilter")}
-          </Text>
-        ) : (
-          <SimpleGrid cols={{ base: 1, lg: 2 }}>
-            {candidates.map((candidate) => (
-              <DockerReconciliationCandidate
-                key={candidate.candidateKey}
-                candidate={candidate}
-                health={health.data?.services.find(({ key }) => key === candidate.candidateKey)}
-                onDismiss={() =>
-                  setDismissedCandidateKeys((current) =>
-                    dismissDockerReconciliationCandidate(current, candidate.candidateKey),
-                  )
-                }
+        <Collapse id={panelId} expanded={isOpen}>
+          <Divider mb="sm" />
+          <Stack gap="sm">
+            <Group justify="space-between">
+              <SegmentedControl
+                size="xs"
+                value={filter}
+                onChange={(value) => setFilter(value as DockerReconciliationInboxFilter)}
+                data={[
+                  { value: "attention", label: t("filter.attention") },
+                  { value: "represented", label: t("filter.represented") },
+                  { value: "all", label: t("filter.all") },
+                ]}
              />
-            ))}
-          </SimpleGrid>
-        )}
+              <Group gap="xs">
+                {dismissedCandidateKeys.length > 0 && (
+                  <Button variant="subtle" size="compact-xs" onClick={() => setDismissedCandidateKeys([])}>
+                    {t("action.restoreDismissed", { count: String(dismissedCandidateKeys.length) })}
+                  </Button>
+                )}
+                <Button
+                  variant="light"
+                  size="compact-xs"
+                  loading={isRefreshing}
+                  leftSection={<IconRefresh size={14} />}
+                  onClick={() => refreshInventory.mutate()}
+                >
+                  {t("action.refresh")}
+                </Button>
+              </Group>
+            </Group>
+
+            {unavailableEndpoints.length > 0 && (
+              <Alert color="yellow" icon={<IconAlertTriangle size={16} />}>
+                {t("endpointUnavailable", { names: unavailableEndpoints.map(({ name }) => name).join(", ") })}
+              </Alert>
+            )}
+
+            {candidates.length === 0 ? (
+              <Text c="dimmed" size="sm">
+                {reconciliation.data.candidates.length === 0 ? t("empty") : t("emptyFilter")}
+              </Text>
+            ) : (
+              <Stack gap="xs">
+                {candidates.map((candidate) => (
+                  <DockerReconciliationCandidate
+                    key={candidate.candidateKey}
+                    candidate={candidate}
+                    health={health.data?.services.find(({ key }) => key === candidate.candidateKey)}
+                    onDismiss={() =>
+                      setDismissedCandidateKeys((current) =>
+                        dismissDockerReconciliationCandidate(current, candidate.candidateKey),
+                      )
+                    }
+                  />
+                ))}
+              </Stack>
+            )}
+          </Stack>
+        </Collapse>
      </Stack>
-    </Card>
+    </Paper>
  );
 };

@@ -185,6 +228,9 @@ const DockerReconciliationCandidate = ({
  const target = getCandidateTarget(candidate, validatedUrl ?? "");
  const actionNeedsUrl = target.kind === "createApp" || target.kind === "setupIntegration";
  const isActionDisabled = actionNeedsUrl && validatedUrl === null;
+  const detailsId = useId();
+  const [detailsOpen, setDetailsOpen] = useState(isActionDisabled || candidate.representation.signals.ambiguous);
+  const detailsLabel = detailsOpen ? t("action.hideDetails") : t("action.showDetails");

  useEffect(() => {
    setSelectedCandidateId(initialUrlCandidate?.id ?? null);
@@ -192,114 +238,151 @@ const DockerReconciliationCandidate = ({
  }, [initialUrlCandidate?.id, initialUrlCandidate?.url]);

  return (
-    <Card withBorder padding="md">
-      <Stack gap="sm">
-        <Group justify="space-between" align="start" wrap="nowrap">
-          <Group wrap="nowrap">
-            <Avatar src={candidate.container.iconUrl} radius="sm">
+    <Paper withBorder p="sm">
+      <Stack gap="xs">
+        <Group justify="space-between" align="center">
+          <Group wrap="nowrap" style={{ minWidth: 0 }}>
+            <Avatar src={candidate.container.iconUrl} radius="sm" size="sm">
              {candidate.container.name.at(0)?.toUpperCase()}
            </Avatar>
-            <div>
-              <Text fw={600} lineClamp={1}>
-                {candidate.container.name}
-              </Text>
+            <div style={{ minWidth: 0 }}>
+              <Group gap="xs" wrap="nowrap">
+                <Text fw={600} size="sm" truncate>
+                  {candidate.container.name}
+                </Text>
+                <Badge color={stateColor(candidate.state)} variant="light" size="xs">
+                  {t(`state.${candidate.state}`)}
+                </Badge>
+              </Group>
              <Text c="dimmed" size="xs">
                {candidate.endpointName}
              </Text>
            </div>
          </Group>
-          <Badge color={stateColor(candidate.state)} variant="light">
-            {t(`state.${candidate.state}`)}
-          </Badge>
-        </Group>
-
-        {candidate.match && (
-          <Group gap="xs">
-            <Badge variant="outline">{candidate.match.kind}</Badge>
-            <Text c="dimmed" size="xs">
-              {t("match", { confidence: t(`confidence.${candidate.match.confidence}`) })}
-            </Text>
-          </Group>
-        )}
-
-        {candidate.representation.signals.ambiguous && (
-          <Alert color="yellow" icon={<IconAlertTriangle size={16} />}>
-            {t("ambiguous")}
-          </Alert>
-        )}
-
-        {health && (
-          <div>
-            <Text c="dimmed" size="xs" mb={4}>
-              {t("health.title")}
-            </Text>
-            <Group gap={4}>
-              {health.layers.map((layer) => (
-                <Badge key={layer.layer} color={healthStatusColor(layer.status)} variant="dot" size="sm">
-                  {t(`health.layer.${layer.layer}`)}: {t(`health.status.${layer.status}`)}
-                </Badge>
-              ))}
-            </Group>
-          </div>
-        )}
-
-        <Select
-          label={t("url.label")}
-          description={selectedCandidate ? t(`reason.${selectedCandidate.reason}`) : t("reason.manualHostRequired")}
-          value={selectedCandidateId}
-          data={candidate.urlCandidates.map((item) => ({
-            value: item.id,
-            label: item.url || t("url.manual"),
-          }))}
-          onChange={(value) => {
-            setSelectedCandidateId(value);
-            setUrl(candidate.urlCandidates.find(({ id }) => id === value)?.url ?? "");
-          }}
-        />
-        <TextInput
-          label={t("url.inputLabel")}
-          aria-label={t("url.inputLabel")}
-          value={url}
-          placeholder="https://service.example.com"
-          error={isInvalidUrl ? t("url.invalid") : undefined}
-          onChange={(event) => setUrl(event.currentTarget.value)}
-        />
-
-        <Group justify="space-between">
-          <Button variant="subtle" color="gray" leftSection={<IconEyeOff size={16} />} onClick={onDismiss}>
-            {t("action.dismiss")}
-          </Button>
-          {target.kind === "createApp" ? (
+          <Group gap={4} justify="flex-end">
            <Button
-              variant="light"
-              rightSection={<IconArrowRight size={16} />}
-              disabled={isActionDisabled}
-              onClick={() =>
-                openModal({
-                  selectedContainers: [candidate.container],
-                  initialUrls: validatedUrl ? [validatedUrl] : undefined,
-                })
+              variant="subtle"
+              color="gray"
+              size="compact-xs"
+              rightSection={
+                <IconChevronDown
+                  size={14}
+                  style={{
+                    transform: detailsOpen ? "rotate(180deg)" : undefined,
+                    transition: "transform 150ms ease",
+                  }}
+                />
              }
+              aria-expanded={detailsOpen}
+              aria-controls={detailsId}
+              onClick={() => setDetailsOpen((current) => !current)}
            >
-              {t("action.createApp")}
+              {detailsLabel}
            </Button>
-          ) : (
-            <Button
-              component={Link}
-              href={target.href}
-              variant="light"
-              rightSection={<IconArrowRight size={16} />}
-              disabled={isActionDisabled}
-              onClick={(event) => {
-                if (isActionDisabled) event.preventDefault();
-              }}
-            >
-              {t(`action.${target.kind}`)}
-            </Button>
-          )}
+            {target.kind === "createApp" ? (
+              <Button
+                variant="light"
+                size="compact-xs"
+                rightSection={<IconArrowRight size={14} />}
+                disabled={isActionDisabled}
+                onClick={() =>
+                  openModal({
+                    selectedContainers: [candidate.container],
+                    initialUrls: validatedUrl ? [validatedUrl] : undefined,
+                  })
+                }
+              >
+                {t("action.createApp")}
+              </Button>
+            ) : (
+              <Button
+                component={Link}
+                href={target.href}
+                variant="light"
+                size="compact-xs"
+                rightSection={<IconArrowRight size={14} />}
+                disabled={isActionDisabled}
+                onClick={(event) => {
+                  if (isActionDisabled) event.preventDefault();
+                }}
+              >
+                {t(`action.${target.kind}`)}
+              </Button>
+            )}
+            <Tooltip label={t("action.dismiss")} events={{ hover: true, focus: true, touch: false }}>
+              <ActionIcon variant="subtle" color="gray" size="sm" aria-label={t("action.dismiss")} onClick={onDismiss}>
+                <IconEyeOff size={15} />
+              </ActionIcon>
+            </Tooltip>
+          </Group>
        </Group>
+
+        <Collapse id={detailsId} expanded={detailsOpen}>
+          <Divider mb="sm" />
+          <Stack gap="sm">
+            {candidate.match && (
+              <Group gap="xs">
+                <Badge variant="outline" size="sm">
+                  {candidate.match.kind}
+                </Badge>
+                <Text c="dimmed" size="xs">
+                  {t("match", { confidence: t(`confidence.${candidate.match.confidence}`) })}
+                </Text>
+              </Group>
+            )}
+
+            {candidate.representation.signals.ambiguous && (
+              <Alert color="yellow" icon={<IconAlertTriangle size={16} />}>
+                {t("ambiguous")}
+              </Alert>
+            )}
+
+            {health && (
+              <div>
+                <Text c="dimmed" size="xs" mb={4}>
+                  {t("health.title")}
+                </Text>
+                <Group gap={4}>
+                  {health.layers.map((layer) => (
+                    <Badge key={layer.layer} color={healthStatusColor(layer.status)} variant="dot" size="sm">
+                      {t(`health.layer.${layer.layer}`)}: {t(`health.status.${layer.status}`)}
+                    </Badge>
+                  ))}
+                </Group>
+              </div>
+            )}
+
+            {actionNeedsUrl && (
+              <SimpleGrid cols={{ base: 1, sm: 2 }}>
+                <Select
+                  label={t("url.label")}
+                  description={
+                    selectedCandidate ? t(`reason.${selectedCandidate.reason}`) : t("reason.manualHostRequired")
+                  }
+                  value={selectedCandidateId}
+                  data={candidate.urlCandidates.map((item) => ({
+                    value: item.id,
+                    label: item.url || t("url.manual"),
+                  }))}
+                  onChange={(value) => {
+                    setSelectedCandidateId(value);
+                    setUrl(candidate.urlCandidates.find(({ id }) => id === value)?.url ?? "");
+                  }}
+                />
+                <TextInput
+                  label={t("url.inputLabel")}
+                  aria-label={t("url.inputLabel")}
+                  value={url}
+                  placeholder="https://service.example.com"
+                  error={isInvalidUrl ? t("url.invalid") : undefined}
+                  onChange={(event) => setUrl(event.currentTarget.value)}
+                />
+              </SimpleGrid>
+            )}
+          </Stack>
+        </Collapse>
      </Stack>
-    </Card>
+    </Paper>
  );
 };

@@ -65,12 +65,14 @@ export const dockerRouter = createTRPCRouter({
    .meta({
      mcp: {
        enabled: true,
-        description: "List all Docker containers with their state, image, CPU/memory usage, and ports",
+        description:
+          "List Docker containers with their state, image, CPU/memory usage, and ports. Optionally filter by endpoint IDs; omitted or empty means all endpoints.",
      },
    })
    .concat(dockerMiddleware())
-    .query(async () => {
-      const innerHandler = dockerContainersRequestHandler.handler({});
+    .input(z.object({ endpointIds: z.array(z.string().min(1)).max(100).optional() }).optional())
+    .query(async ({ input }) => {
+      const innerHandler = dockerContainersRequestHandler.handler(input ?? {});
      const result = await innerHandler.getDataAsync();

      const { data, timestamp } = result;
@@ -196,7 +196,7 @@ const mockContainers: {
 ];

 export const dockerContainersRequestHandler = createWidgetRequestHandler({
-  async requestAsync() {
+  async requestAsync({ endpointIds }: { endpointIds?: string[] }) {
    if (isDemoMode()) {
      return {
        containers: mockContainers.map((container) => ({
@@ -219,7 +219,7 @@ export const dockerContainersRequestHandler = createWidgetRequestHandler({
        ] satisfies DockerEndpointStatus[],
      };
    }
-    return await getContainersWithStatsAsync();
+    return await getContainersWithStatsAsync(dockerWidgetEndpointTimeoutMs, endpointIds);
  },
 });

@@ -331,9 +331,18 @@ export const getDockerEndpointsAsync = (): DockerEndpointStatus[] => {
  ];
 };

-export async function getContainersWithStatsAsync(timeoutMs = dockerWidgetEndpointTimeoutMs) {
-  const dockerInstances = DockerSingleton.getInstances();
-  const initializationFailures = DockerSingleton.getInitializationFailures();
+export async function getContainersWithStatsAsync(
+  timeoutMs = dockerWidgetEndpointTimeoutMs,
+  endpointIds: string[] = [],
+) {
+  const selectedEndpointIds = new Set(endpointIds);
+  const includesAllEndpoints = selectedEndpointIds.size === 0;
+  const dockerInstances = DockerSingleton.getInstances().filter(
+    ({ endpointId }) => includesAllEndpoints || selectedEndpointIds.has(endpointId),
+  );
+  const initializationFailures = DockerSingleton.getInitializationFailures().filter(
+    ({ descriptor }) => includesAllEndpoints || selectedEndpointIds.has(descriptor.id),
+  );
  const results = await Promise.allSettled(
    dockerInstances.map(async ({ instance, host, endpointId, endpointName }) => {
      const instanceContainers = await withDockerTimeoutAsync(
@@ -127,6 +127,31 @@ describe("calculateMemoryUsage", () => {
 });

 describe("getContainersWithStatsAsync", () => {
+  test("queries only selected Docker endpoints and leaves an empty selection as all", async () => {
+    const firstListContainers = vi.fn(async () => []);
+    const secondListContainers = vi.fn(async () => []);
+    vi.spyOn(DockerSingleton, "getInstances").mockReturnValue([
+      createDockerInstance("first", firstListContainers),
+      createDockerInstance("second", secondListContainers),
+    ] as never);
+    vi.spyOn(DockerSingleton, "getInitializationFailures").mockReturnValue([]);
+
+    try {
+      const selectedResult = await getContainersWithStatsAsync(50, ["second"]);
+
+      expect(firstListContainers).not.toHaveBeenCalled();
+      expect(secondListContainers).toHaveBeenCalledOnce();
+      expect(selectedResult.endpoints.map(({ id }) => id)).toEqual(["second"]);
+
+      await getContainersWithStatsAsync(50, []);
+
+      expect(firstListContainers).toHaveBeenCalledOnce();
+      expect(secondListContainers).toHaveBeenCalledTimes(2);
+    } finally {
+      vi.restoreAllMocks();
+    }
+  });
+
  test("marks a timed-out endpoint unavailable without blocking healthy endpoints", async () => {
    vi.useFakeTimers();
    try {
@@ -3737,6 +3737,11 @@
      "name": "Docker stats",
      "description": "Stats of your containers (This widget can only be added with administrator privileges)",
      "option": {
+        "endpointIds": {
+          "label": "Docker environments",
+          "description": "Leave empty to show containers from every Docker environment",
+          "placeholder": "All Docker environments"
+        },
        "columns": {
          "label": "Columns to show"
        },
@@ -5685,6 +5690,7 @@
    },
    "dynamicSelect": {
      "noResults": "No results found",
+      "loading": "Loading...",
      "loadError": "Failed to load options"
    },
    "assistant": {
@@ -7072,8 +7078,9 @@
  "docker": {
    "title": "Containers",
    "reconciliation": {
-      "title": "Service setup",
-      "description": "Docker services are compared with your apps and integrations. Review every suggestion before Homarr changes anything.",
+      "title": "Assisted Docker setup",
+      "description": "Optional suggestions to connect Docker services with Homarr apps and integrations.",
+      "suggestions": "{count, plural, =0 {No suggestions} one {# suggestion} other {# suggestions}}",
      "attention": "{count} need attention",
      "endpointUnavailable": "Some services could not be checked because these endpoints are unavailable: {names}",
      "empty": "No visible Docker services were found.",
@@ -7131,6 +7138,10 @@
        }
      },
      "action": {
+        "review": "Review",
+        "hide": "Hide",
+        "showDetails": "Details",
+        "hideDetails": "Hide details",
        "refresh": "Refresh",
        "retry": "Try again",
        "dismiss": "Dismiss",
@@ -7141,7 +7152,7 @@
        "viewRepresentation": "View setup"
      },
      "loadError": {
-        "title": "Service setup could not be loaded",
+        "title": "Docker setup assistant could not be loaded",
        "message": "Docker service information is unavailable. Try again without leaving this page."
      },
      "refreshError": {
@@ -4,6 +4,7 @@ import { WidgetAppInput } from "./widget-app-input";
 import { WidgetCustomWidgetSelectInput } from "./widget-custom-widget-select-input";
 import { WidgetCustomWidgetConfigurationInput } from "./widget-custom-widget-configuration-input";
 import { WidgetDynamicSelectInput } from "./widget-dynamic-select-input";
+import { WidgetDynamicMultiSelectInput } from "./widget-dynamic-multiselect-input";
 import { WidgetLocationInput } from "./widget-location-input";
 import { WidgetMultiTextInput } from "./widget-multi-text-input";
 import { WidgetMultiReleasesRepositoriesInput } from "./widget-multiReleasesRepositories-input";
@@ -36,6 +37,7 @@ const mapping = {
  sortableItemList: WidgetSortedItemListInput,
  multiReleasesRepositories: WidgetMultiReleasesRepositoriesInput,
  dynamicSelect: WidgetDynamicSelectInput,
+  dynamicMultiSelect: WidgetDynamicMultiSelectInput,
  umamiEventName: WidgetUmamiEventInput,
  umamiEventNames: WidgetUmamiEventNamesInput,
  umamiWebsite: WidgetUmamiWebsiteInput,
@@ -0,0 +1,44 @@
+"use client";
+
+import { Loader, MultiSelect } from "@mantine/core";
+
+import { useScopedI18n } from "@homarr/translation/client";
+
+import type { CommonWidgetInputProps } from "./common";
+import { useWidgetInputTranslation } from "./common";
+import { useFormContext } from "./form";
+
+export const WidgetDynamicMultiSelectInput = ({
+  property,
+  kind,
+  options,
+}: CommonWidgetInputProps<"dynamicMultiSelect">) => {
+  const t = useScopedI18n("widget.dynamicSelect");
+  const tInput = useWidgetInputTranslation(kind, property);
+  const form = useFormContext();
+  const inputProps = form.getInputProps(`options.${property}`);
+  const selectedValues = (inputProps.value as string[] | undefined) ?? [];
+  const { data: selectData, isPending, isError } = options.useOptions();
+  const data = [
+    ...selectData,
+    ...selectedValues
+      .filter((selectedValue) => !selectData.some((option) => option.value === selectedValue))
+      .map((selectedValue) => ({ value: selectedValue, label: selectedValue })),
+  ];
+
+  return (
+    <MultiSelect
+      {...inputProps}
+      label={tInput("label")}
+      description={options.withDescription ? tInput("description") : undefined}
+      placeholder={isPending ? t("loading") : tInput("placeholder")}
+      leftSection={isPending ? <Loader size="xs" /> : undefined}
+      searchable
+      clearable
+      nothingFoundMessage={t("noResults")}
+      data={data}
+      disabled={isError}
+      error={isError ? t("loadError") : inputProps.error}
+    />
+  );
+};
@@ -248,7 +248,7 @@ export default function DockerWidget({
  const isAdvanced = displayMode === "advanced";

  const utils = clientApi.useUtils();
-  const containersQuery = clientApi.docker.getContainers.useQuery();
+  const containersQuery = clientApi.docker.getContainers.useQuery({ endpointIds: options.endpointIds });
  const data = getUsableWidgetQueryData(containersQuery);
  const { isFetching } = containersQuery;
  const refreshInventory = clientApi.docker.refreshInventory.useMutation({
@@ -1,6 +1,7 @@
 import { IconBrandDocker, IconServerOff } from "@tabler/icons-react";

 import type { RouterOutputs } from "@homarr/api";
+import { clientApi } from "@homarr/api/client";

 import { createWidgetDefinition } from "../definition";
 import { optionsBuilder } from "../options";
@@ -30,6 +31,18 @@ export const { definition, componentLoader } = createWidgetDefinition("dockerCon
  createOptions() {
    return optionsBuilder.from(
      (factory) => ({
+        endpointIds: factory.dynamicMultiSelect({
+          defaultValue: [],
+          withDescription: true,
+          useOptions: () => {
+            const { data = [], isPending, isError } = clientApi.docker.getEndpoints.useQuery();
+            return {
+              data: data.map((endpoint) => ({ value: endpoint.id, label: endpoint.name })),
+              isPending,
+              isError,
+            };
+          },
+        }),
        columns: factory.multiSelect({
          defaultValue: [...allColumnsList],
          options: allColumnsList.map((value) => ({
@@ -69,6 +69,14 @@ interface DynamicSelectInput extends CommonInput<DynamicSelectOption | null> {
  };
 }

+interface DynamicMultiSelectInput extends CommonInput<string[]> {
+  useOptions: () => {
+    data: DynamicSelectOption[];
+    isPending: boolean;
+    isError: boolean;
+  };
+}
+
 interface IntegrationSelectInput extends CommonInput<string> {
  clearable?: boolean;
  searchable?: boolean;
@@ -141,6 +149,12 @@ const optionsFactory = {
    useOptions: input.useOptions,
    withDescription: input.withDescription ?? false,
  }),
+  dynamicMultiSelect: (input: DynamicMultiSelectInput) => ({
+    type: "dynamicMultiSelect" as const,
+    defaultValue: input.defaultValue ?? [],
+    useOptions: input.useOptions,
+    withDescription: input.withDescription ?? false,
+  }),
  select: <const TOptions extends SelectOption[]>(input: SelectInput<TOptions>) => ({
    type: "select" as const,
    defaultValue: (input.defaultValue ?? input.options[0]) as inferSelectOptionValue<TOptions[number]>,