Give every stack an icon, and put the status on it (0.51.0)

Stacks were a name and a coloured dot. The dot carried the status but nothing
carried identity, so a list of twenty stacks read as twenty identical rows.
This gives each one an icon in front of its name and moves the status onto that
icon as a halo in the status colour, which is the thing the eye lands on anyway.

The constraint that shaped the design: people already have stacks. Asking them
to pick an icon for each one before the feature does anything would mean it
never gets used, so the icon is *derived* from the stack's name and the column
stays empty until somebody overrides it. ~700 keywords in 79 groups cover the
self-hosted long tail (jellyfin -> clapperboard, vaultwarden -> key,
home-assistant -> house) plus generic English and German terms; the longest
match wins, so photoprism beats a bare photo, and short keywords like "tv" only
match as whole words. No backfill, no migration, and a rename moves the icon
with it.

That is also why the catalog and the matcher live in the frontend. It is the
only place that can render an icon, so a copy in the backend would be a list to
keep in sync and nothing else. The server validates the shape of the stored
value and stores uploads; it never needs to know what "lucide:database" looks
like. An icon name that later leaves the catalog falls back to the derived one
rather than blanking the row.

Overriding happens in two places, because there are two moments: the editor
(holding a chosen file until the stack exists, since uploading needs an id) and
a click on the icon on the detail page, which is how a stack that has existed
for a year gets one without a trip through the editor.

Uploads are classified by their bytes, not by the filename or Content-Type the
browser claims, and land in ${DATA_DIR}/stack-icons/ under the stack id. SVG is
allowed — <img> does not execute it — but the endpoint serves every icon as an
attachment so one can never be opened as a document in the API's own origin. A
client-supplied "custom:" value is refused: the server mints those, so a stack
cannot be pointed at a file it does not own. Files follow the stack: replaced on
re-upload (including across formats, or the old one orphans), copied on clone,
removed on delete.

The one piece of plumbing worth knowing about: the icon endpoint needs the
bearer token like everything else, and an <img src> would not carry it. So
StackIcon fetches the bytes through the API client and renders the blob, keyed
on the stored value — which carries an upload timestamp precisely so a re-upload
changes the key and retires the cached image.

Covered by 22 backend tests (the value rules, byte-sniffing, the file lifecycle,
the API round-trip, and that the read-only role cannot change an icon) and 29
frontend ones for the matcher. The schema change was verified against a
hand-built pre-0.51 database: the column is added on start and existing rows
come back NULL, i.e. automatic. Not click-tested in a browser — no Docker in
this environment — so the row height the taller icon produces is unverified.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

frontend/package.json

@@ -1,7 +1,7 @@
 {
   "name": "stackpilot-frontend",
   "private": true,
-  "version": "0.50.0",
+  "version": "0.51.0",
   "type": "module",
   "scripts": {
     "dev": "vite",

frontend/src/api/stacks.ts

@@ -8,10 +8,24 @@ export const stacksApi = {
     api.get<Record<string, StackUpdateInfo>>("/api/stacks/updates").then((r) => r.data),
   get: (id: string) =>
     api.get<StackDetail>(`/api/stacks/${id}`).then((r) => r.data),
-  create: (body: { name: string; description?: string; yaml?: string; env?: string }) =>
-    api.post<StackSummary>("/api/stacks", body).then((r) => r.data),
-  update: (id: string, body: { name?: string; description?: string; yaml?: string; env?: string }) =>
-    api.put<StackSummary>(`/api/stacks/${id}`, body).then((r) => r.data),
+  create: (body: {
+    name: string;
+    description?: string;
+    icon?: string;
+    yaml?: string;
+    env?: string;
+  }) => api.post<StackSummary>("/api/stacks", body).then((r) => r.data),
+  update: (
+    id: string,
+    body: {
+      name?: string;
+      description?: string;
+      /** "lucide:<name>", or "" to go back to the name-derived icon. */
+      icon?: string;
+      yaml?: string;
+      env?: string;
+    }
+  ) => api.put<StackSummary>(`/api/stacks/${id}`, body).then((r) => r.data),
   remove: (id: string, deleteFiles = true) =>
     api.delete(`/api/stacks/${id}?delete_files=${deleteFiles}`).then((r) => r.data),
   clone: (id: string, name: string) =>
@@ -24,6 +38,20 @@ export const stacksApi = {
   update_images: (id: string) => api.post(`/api/stacks/${id}/update`).then((r) => r.data),
   down: (id: string) => api.post(`/api/stacks/${id}/down`).then((r) => r.data),
 
+  /** The uploaded icon, fetched through the client so it carries the token —
+   *  an <img src> pointed at this URL would be unauthenticated. */
+  icon: (id: string) =>
+    api.get<Blob>(`/api/stacks/${id}/icon`, { responseType: "blob" }).then((r) => r.data),
+  uploadIcon: (id: string, file: File) => {
+    const form = new FormData();
+    form.append("file", file);
+    return api
+      .post<StackSummary>(`/api/stacks/${id}/icon`, form)
+      .then((r) => r.data);
+  },
+  resetIcon: (id: string) =>
+    api.delete<StackSummary>(`/api/stacks/${id}/icon`).then((r) => r.data),
+
   logs: (id: string, tail = 200) =>
     api.get<{ logs: string }>(`/api/stacks/${id}/logs?tail=${tail}`).then((r) => r.data),
   convert: (command: string) =>

frontend/src/components/stacks/IconPicker.tsx

@@ -0,0 +1,237 @@
+import { useMemo, useRef, useState } from "react";
+import { createPortal } from "react-dom";
+import { useQueryClient } from "@tanstack/react-query";
+import { Sparkles, Upload, X } from "lucide-react";
+import { toast } from "sonner";
+import { Button, Input } from "@/components/ui";
+import { StackIcon } from "@/components/ui/StackIcon";
+import { cn } from "@/lib/utils";
+import { ICON_GROUPS, suggestIconName } from "@/lib/stackIcons";
+import { stacksApi } from "@/api/stacks";
+import { apiErrorMessage } from "@/api/client";
+import type { StackStatus } from "@/types";
+
+/** Matches services/icon_service.py — the server rejects anything larger. */
+const MAX_ICON_BYTES = 512 * 1024;
+const ACCEPTED = "image/png,image/jpeg,image/gif,image/webp,image/svg+xml";
+
+/**
+ * Pick a stack's icon: keep the automatic one, choose a built-in, or upload an
+ * image.
+ *
+ * The dialog itself is stateless — it reports the choice and lets the caller
+ * decide what to do with it, because the two callers differ: the editor holds
+ * the choice until the stack is saved (a stack being created has no id to
+ * upload to yet), while the detail page applies it immediately.
+ */
+export function IconPicker({
+  stack,
+  status = "stopped",
+  previewUrl,
+  busy = false,
+  onSelect,
+  onUpload,
+  onClose,
+}: {
+  stack: { id: string; name: string; icon?: string | null };
+  status?: StackStatus;
+  previewUrl?: string | null;
+  busy?: boolean;
+  /** "" means "back to the icon derived from the name". */
+  onSelect: (icon: string) => void;
+  onUpload: (file: File) => void;
+  onClose: () => void;
+}) {
+  const [q, setQ] = useState("");
+  const fileInput = useRef<HTMLInputElement>(null);
+  const automatic = useMemo(
+    () => suggestIconName(stack.name, stack.id),
+    [stack.name, stack.id]
+  );
+  const isAutomatic = !stack.icon;
+
+  const groups = useMemo(() => {
+    const needle = q.trim().toLowerCase();
+    if (!needle) return ICON_GROUPS;
+    return ICON_GROUPS.map((group) => ({
+      label: group.label,
+      icons: Object.fromEntries(
+        Object.entries(group.icons).filter(([name]) => name.includes(needle))
+      ),
+    })).filter((group) => Object.keys(group.icons).length > 0);
+  }, [q]);
+
+  const pickFile = (file: File | undefined) => {
+    if (!file) return;
+    if (file.size > MAX_ICON_BYTES) {
+      toast.error(`That image is ${Math.round(file.size / 1024)} KiB; the limit is 512 KiB.`);
+      return;
+    }
+    onUpload(file);
+  };
+
+  return createPortal(
+    <div
+      className="fixed inset-0 z-50 flex items-center justify-center bg-black/50 p-4"
+      onClick={() => !busy && onClose()}
+    >
+      <div
+        className="flex max-h-full w-full max-w-lg flex-col overflow-hidden rounded-xl border border-slate-200 bg-card shadow-xl dark:border-slate-700 dark:bg-card-dark"
+        onClick={(e) => e.stopPropagation()}
+      >
+        <div className="flex items-center gap-3 border-b border-slate-200 p-4 dark:border-slate-700">
+          <StackIcon stack={stack} status={status} size="lg" previewUrl={previewUrl} />
+          <div className="min-w-0 flex-1">
+            <h2 className="sp-heading text-lg">Stack icon</h2>
+            <p className="truncate text-sm text-slate-500">{stack.name || "New stack"}</p>
+          </div>
+          <button
+            onClick={onClose}
+            disabled={busy}
+            title="Close"
+            className="rounded-lg p-1.5 text-slate-500 hover:bg-slate-100 disabled:opacity-40 dark:hover:bg-slate-700"
+          >
+            <X className="h-4 w-4" />
+          </button>
+        </div>
+
+        <div className="flex flex-wrap items-center gap-2 border-b border-slate-200 p-4 dark:border-slate-700">
+          <Button
+            variant={isAutomatic ? "primary" : "outline"}
+            onClick={() => onSelect("")}
+            disabled={busy}
+            title={`Derived from the stack name (currently “${automatic}”)`}
+          >
+            <Sparkles className="h-4 w-4" /> Automatic
+          </Button>
+          <Button variant="outline" onClick={() => fileInput.current?.click()} disabled={busy}>
+            <Upload className="h-4 w-4" /> Upload image…
+          </Button>
+          <input
+            ref={fileInput}
+            type="file"
+            accept={ACCEPTED}
+            className="hidden"
+            onChange={(e) => {
+              pickFile(e.target.files?.[0]);
+              // Reset, or picking the same file twice fires no change event.
+              e.target.value = "";
+            }}
+          />
+          <div className="relative min-w-[140px] flex-1">
+            <Input
+              placeholder="Search icons…"
+              value={q}
+              onChange={(e) => setQ(e.target.value)}
+            />
+          </div>
+        </div>
+
+        <div className="min-h-0 flex-1 overflow-y-auto p-4">
+          {groups.length === 0 && (
+            <p className="text-sm text-slate-500">No icon matches “{q}”.</p>
+          )}
+          {groups.map((group) => (
+            <section key={group.label} className="mb-4 last:mb-0">
+              <h3 className="sp-label mb-2">{group.label}</h3>
+              <div className="grid grid-cols-8 gap-1.5 sm:grid-cols-10">
+                {Object.entries(group.icons).map(([name, Glyph]) => {
+                  const selected = stack.icon === `lucide:${name}`;
+                  return (
+                    <button
+                      key={name}
+                      title={name}
+                      disabled={busy}
+                      onClick={() => onSelect(`lucide:${name}`)}
+                      className={cn(
+                        "flex aspect-square items-center justify-center rounded-lg border transition-colors",
+                        "disabled:opacity-40",
+                        selected
+                          ? "border-accent bg-accent/10 text-accent dark:text-accent-dark"
+                          : "border-transparent text-slate-500 hover:bg-slate-100 dark:text-slate-400 dark:hover:bg-slate-700",
+                        // The automatic pick is called out so it is obvious what
+                        // "Automatic" would give you.
+                        !selected &&
+                          isAutomatic &&
+                          name === automatic &&
+                          "border-slate-300 dark:border-slate-600"
+                      )}
+                    >
+                      <Glyph className="h-[18px] w-[18px]" />
+                    </button>
+                  );
+                })}
+              </div>
+            </section>
+          ))}
+        </div>
+
+        <p className="border-t border-slate-200 px-4 py-2.5 text-xs text-slate-500 dark:border-slate-700">
+          PNG, JPEG, GIF, WebP or SVG, up to 512 KiB. Square images look best —
+          anything else is cropped to fit.
+        </p>
+      </div>
+    </div>,
+    document.body
+  );
+}
+
+/**
+ * The stack's icon, clickable: opens the picker and applies the choice right
+ * away. Used on the stack detail page, so an existing stack can be given an
+ * icon without going through the editor.
+ */
+export function StackIconEditor({
+  stack,
+  status,
+  size = "lg",
+  editable = true,
+}: {
+  stack: { id: string; name: string; icon?: string | null };
+  status: StackStatus;
+  size?: "sm" | "md" | "lg";
+  /** The read-only role sees the icon but cannot change it. */
+  editable?: boolean;
+}) {
+  const qc = useQueryClient();
+  const [open, setOpen] = useState(false);
+  const [busy, setBusy] = useState(false);
+
+  const apply = async (call: Promise<unknown>) => {
+    setBusy(true);
+    try {
+      await call;
+      qc.invalidateQueries({ queryKey: ["stack", stack.id] });
+      qc.invalidateQueries({ queryKey: ["stacks"] });
+      setOpen(false);
+    } catch (err) {
+      toast.error(apiErrorMessage(err));
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  if (!editable) return <StackIcon stack={stack} status={status} size={size} />;
+
+  return (
+    <>
+      <button
+        onClick={() => setOpen(true)}
+        title="Change icon"
+        className="rounded-[15px] outline-none ring-offset-2 transition-opacity hover:opacity-80 focus-visible:ring-2 focus-visible:ring-accent dark:ring-offset-slate-900"
+      >
+        <StackIcon stack={stack} status={status} size={size} />
+      </button>
+      {open && (
+        <IconPicker
+          stack={stack}
+          status={status}
+          busy={busy}
+          onSelect={(icon) => apply(stacksApi.update(stack.id, { icon }))}
+          onUpload={(file) => apply(stacksApi.uploadIcon(stack.id, file))}
+          onClose={() => setOpen(false)}
+        />
+      )}
+    </>
+  );
+}

frontend/src/components/stacks/StacksTable.tsx

@@ -3,8 +3,9 @@ import { Link } from "react-router-dom";
 import { useQueryClient } from "@tanstack/react-query";
 import { Play, Square, RotateCw, ArrowUpCircle, Pencil, Trash2 } from "lucide-react";
 import { toast } from "sonner";
-import { Card, Spinner, StatusDot, Badge } from "@/components/ui";
+import { Card, Spinner, Badge } from "@/components/ui";
 import { ConfirmDialog } from "@/components/ui/ConfirmDialog";
+import { StackIcon } from "@/components/ui/StackIcon";
 import { formatBytes } from "@/lib/utils";
 import { stacksApi } from "@/api/stacks";
 import { apiErrorMessage } from "@/api/client";
@@ -161,9 +162,11 @@ function StackRow({
         <div className="flex items-center gap-2">
           <Link
             to={`/stacks/${stack.id}`}
-            className="flex shrink-0 items-center gap-2"
+            className="flex shrink-0 items-center gap-2.5"
           >
-            <StatusDot status={stack.status} />
+            {/* The icon carries the status (a halo in the status colour), which
+                is why there is no separate dot here any more. */}
+            <StackIcon stack={stack} status={stack.status} />
             <span className="font-medium">{stack.name}</span>
             <Badge status={stack.status}>{stack.status}</Badge>
             <span className="text-xs text-slate-400">

frontend/src/components/ui/StackIcon.tsx

@@ -0,0 +1,153 @@
+import { useEffect, useState } from "react";
+import { useQuery } from "@tanstack/react-query";
+import { cn } from "@/lib/utils";
+import { iconComponent, resolveStackIcon } from "@/lib/stackIcons";
+import { stacksApi } from "@/api/stacks";
+import type { StackStatus } from "@/types";
+
+/**
+ * A stack's icon, wearing its status as a coloured glow.
+ *
+ * This replaces the status dot in the stacks list: the same information, but
+ * carried by the thing the eye lands on anyway. The status is still spelled out
+ * in the badge next to it and in the tooltip here, so the colour is never the
+ * only way to read it.
+ */
+
+type Size = "sm" | "md" | "lg";
+
+const SIZES: Record<Size, { box: string; glyph: string; radius: string }> = {
+  sm: { box: "h-7 w-7", glyph: "h-3.5 w-3.5", radius: "rounded-[9px]" },
+  md: { box: "h-9 w-9", glyph: "h-[18px] w-[18px]", radius: "rounded-[11px]" },
+  lg: { box: "h-12 w-12", glyph: "h-6 w-6", radius: "rounded-[15px]" },
+};
+
+/** Ring + halo per status. Kept as whole class strings because Tailwind only
+ *  sees classes it can find literally in the source. */
+const STATUS_STYLE: Record<StackStatus, { ring: string; halo: string; glyph: string }> = {
+  running: {
+    ring: "ring-green-500/60 dark:ring-green-400/60",
+    halo: "bg-green-500/40 dark:bg-green-400/40",
+    glyph: "text-green-600 dark:text-green-400",
+  },
+  partial: {
+    ring: "ring-yellow-500/60 dark:ring-yellow-400/60",
+    halo: "bg-yellow-500/40 dark:bg-yellow-400/40",
+    glyph: "text-yellow-600 dark:text-yellow-400",
+  },
+  stopped: {
+    ring: "ring-slate-400/50 dark:ring-slate-500/50",
+    halo: "bg-slate-400/20 dark:bg-slate-500/20",
+    glyph: "text-slate-500 dark:text-slate-400",
+  },
+  error: {
+    ring: "ring-red-500/60 dark:ring-red-400/60",
+    halo: "bg-red-500/45 dark:bg-red-400/45",
+    glyph: "text-red-600 dark:text-red-400",
+  },
+  updating: {
+    ring: "ring-sky-500/60 dark:ring-sky-400/60",
+    halo: "bg-sky-500/45 dark:bg-sky-400/45",
+    glyph: "text-sky-600 dark:text-sky-400",
+  },
+  unknown: {
+    ring: "ring-slate-300/60 dark:ring-slate-600/60",
+    halo: "bg-slate-300/20 dark:bg-slate-600/20",
+    glyph: "text-slate-400 dark:text-slate-500",
+  },
+};
+
+export function StackIcon({
+  stack,
+  status,
+  size = "md",
+  previewUrl,
+  className,
+}: {
+  stack: { id: string; name: string; icon?: string | null };
+  status: StackStatus;
+  size?: Size;
+  /** Shows this image instead of the stored icon — used to preview a file that
+   *  has been chosen but not uploaded yet (a stack being created). */
+  previewUrl?: string | null;
+  className?: string;
+}) {
+  const resolved = resolveStackIcon(stack);
+  const dims = SIZES[size];
+  const tone = STATUS_STYLE[status] ?? STATUS_STYLE.unknown;
+  const stored = useCustomIconUrl(
+    stack.id,
+    resolved.kind === "custom" && !previewUrl ? stack.icon : null
+  );
+  const custom = previewUrl ?? stored;
+  const Glyph = iconComponent(resolved.kind === "builtin" ? resolved.name : "");
+
+  return (
+    <span
+      className={cn("relative inline-flex shrink-0", dims.box, className)}
+      role="img"
+      aria-label={`${stack.name} — ${status}`}
+      title={status}
+    >
+      {/* The status "shimmer": a blurred copy of the status colour bleeding out
+          from behind the tile. Pulses while an operation is running. */}
+      <span
+        aria-hidden
+        className={cn(
+          "pointer-events-none absolute -inset-[3px] blur-[5px]",
+          dims.radius,
+          tone.halo,
+          status === "updating" && "animate-pulse"
+        )}
+      />
+      <span
+        className={cn(
+          "relative inline-flex h-full w-full items-center justify-center overflow-hidden",
+          "bg-sp-surface-2 ring-2",
+          dims.radius,
+          tone.ring
+        )}
+      >
+        {custom ? (
+          <img src={custom} alt="" className="h-full w-full object-cover" />
+        ) : (
+          <Glyph className={cn(dims.glyph, tone.glyph)} strokeWidth={2} />
+        )}
+      </span>
+    </span>
+  );
+}
+
+/**
+ * Object URL for a stack's uploaded icon, or null while there is none.
+ *
+ * The icon endpoint needs the bearer token, so the bytes are fetched through
+ * the API client and handed to the browser as a blob. `icon` is part of the
+ * query key and changes on every upload (it carries a version), which is what
+ * retires the previous image instead of leaving a stale one on screen.
+ */
+function useCustomIconUrl(stackId: string, icon: string | null | undefined): string | null {
+  const { data: blob } = useQuery({
+    queryKey: ["stack-icon", stackId, icon],
+    queryFn: () => stacksApi.icon(stackId),
+    enabled: Boolean(icon),
+    staleTime: Infinity,
+    gcTime: 60 * 60 * 1000,
+    retry: false,
+  });
+  const [url, setUrl] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (!blob) {
+      setUrl(null);
+      return;
+    }
+    const objectUrl = URL.createObjectURL(blob);
+    setUrl(objectUrl);
+    // Every mount makes its own URL; without this each row would leak one for
+    // the lifetime of the tab.
+    return () => URL.revokeObjectURL(objectUrl);
+  }, [blob]);
+
+  return url;
+}

frontend/src/lib/stackIcons.test.ts

@@ -0,0 +1,109 @@
+/**
+ * The name → icon matcher.
+ *
+ * This is the part of the feature that has to be right without anyone touching
+ * it: every stack that existed before icons landed gets its icon from here, and
+ * a bad guess is visible on the very first screen of the app.
+ */
+import { describe, expect, it } from "vitest";
+import {
+  FALLBACK_ICON,
+  STACK_ICONS,
+  resolveStackIcon,
+  suggestIconName,
+} from "./stackIcons";
+
+describe("suggestIconName", () => {
+  it.each([
+    ["jellyfin", "clapperboard"],
+    ["Plex Media Server", "clapperboard"],
+    ["radarr", "film"],
+    ["sonarr", "tv"],
+    ["qBittorrent", "download"],
+    ["Postgres", "database"],
+    ["mariadb", "database"],
+    ["Traefik", "network"],
+    ["pihole", "shield"],
+    ["Vaultwarden", "key-round"],
+    ["gitea", "git-branch"],
+    ["Home Assistant", "home"],
+    ["Uptime Kuma", "activity"],
+    ["nextcloud", "cloud"],
+    ["paperless-ngx", "file-text"],
+    ["Immich", "image"],
+    ["n8n", "workflow"],
+    ["Minecraft Server", "gamepad-2"],
+    ["ollama + open-webui", "brain"],
+  ])("maps %s to %s", (name, icon) => {
+    expect(suggestIconName(name)).toBe(icon);
+  });
+
+  it("finds the app inside a longer name", () => {
+    expect(suggestIconName("my-jellyfin-stack")).toBe("clapperboard");
+    expect(suggestIconName("Mediaserver Wohnzimmer")).toBe("clapperboard");
+  });
+
+  it("prefers the more specific keyword", () => {
+    // "home-assistant" and "home" both match; the longer one wins.
+    expect(suggestIconName("home-assistant")).toBe("home");
+    expect(suggestIconName("photoprism")).toBe("image");
+    // The named app beats the generic word it sits next to.
+    expect(suggestIconName("radarr media")).toBe("film");
+  });
+
+  it("only matches short keywords as whole words", () => {
+    // "tv" must not fire on "tvorba" or a random substring...
+    expect(suggestIconName("Motvind")).toBe(FALLBACK_ICON);
+    // ...but does on its own.
+    expect(suggestIconName("tv box")).toBe("tv");
+  });
+
+  it("falls back for a name that means nothing", () => {
+    expect(suggestIconName("zzz-42")).toBe(FALLBACK_ICON);
+    expect(suggestIconName("")).toBe(FALLBACK_ICON);
+  });
+
+  it("falls back to the id when the name says nothing", () => {
+    expect(suggestIconName("Stack 1", "jellyfin")).toBe("clapperboard");
+    // The name still wins when it matches on its own.
+    expect(suggestIconName("postgres", "jellyfin")).toBe("database");
+  });
+
+  it("only ever returns an icon that exists", () => {
+    const names = ["jellyfin", "nothing-at-all", "grafana", "wireguard", "mealie"];
+    for (const name of names) {
+      expect(STACK_ICONS[suggestIconName(name)]).toBeDefined();
+    }
+  });
+});
+
+describe("resolveStackIcon", () => {
+  it("uses an explicit built-in choice", () => {
+    expect(
+      resolveStackIcon({ id: "jellyfin", name: "Jellyfin", icon: "lucide:database" })
+    ).toEqual({ kind: "builtin", name: "database", automatic: false });
+  });
+
+  it("reports an uploaded image", () => {
+    expect(
+      resolveStackIcon({ id: "x", name: "X", icon: "custom:png:123" }).kind
+    ).toBe("custom");
+  });
+
+  it("derives one when nothing is stored", () => {
+    expect(resolveStackIcon({ id: "plex", name: "Plex", icon: null })).toEqual({
+      kind: "builtin",
+      name: "clapperboard",
+      automatic: true,
+    });
+  });
+
+  it("does not blank the row out for an icon that left the catalog", () => {
+    const resolved = resolveStackIcon({
+      id: "plex",
+      name: "Plex",
+      icon: "lucide:no-such-icon",
+    });
+    expect(resolved).toEqual({ kind: "builtin", name: "clapperboard", automatic: true });
+  });
+});

frontend/src/lib/stackIcons.ts

@@ -0,0 +1,499 @@
+/**
+ * Stack icons — the built-in catalog and the name → icon matcher.
+ *
+ * Every stack shows an icon in place of the old status dot. Where it comes
+ * from, in order:
+ *
+ *   1. `stack.icon === "custom:…"` — an image the user uploaded. Rendered by
+ *      `StackIcon`, which fetches it through the authenticated API client.
+ *   2. `stack.icon === "lucide:<name>"` — an icon the user picked from here.
+ *   3. `stack.icon` unset — `suggestIconName()` derives one from the stack's
+ *      name. This is what every stack that predates the feature gets, which is
+ *      why no migration backfills the column: the icon is simply computed.
+ *
+ * The catalog and the matching rules live in the frontend on purpose. This is
+ * the only place that can actually *render* an icon, so a second copy in the
+ * backend would be a list to keep in sync and nothing more — the server only
+ * validates the shape of the value (`services/icon_service.py`).
+ */
+import {
+  Activity,
+  AlarmClock,
+  Archive,
+  Atom,
+  Banknote,
+  BarChart3,
+  Bell,
+  Blocks,
+  BookOpen,
+  Bot,
+  Box,
+  Boxes,
+  Brain,
+  Briefcase,
+  Brush,
+  Bug,
+  Cable,
+  Calendar,
+  Camera,
+  Car,
+  Clapperboard,
+  ClipboardList,
+  Cloud,
+  Code,
+  Coins,
+  Compass,
+  Container,
+  Cpu,
+  CreditCard,
+  Database,
+  Dna,
+  Download,
+  Dumbbell,
+  EarthLock,
+  Feather,
+  FileText,
+  Film,
+  Flame,
+  Folder,
+  Gamepad2,
+  Gauge,
+  Gift,
+  GitBranch,
+  Globe,
+  HardDrive,
+  Headphones,
+  HeartPulse,
+  Highlighter,
+  Home,
+  Image,
+  Inbox,
+  KeyRound,
+  Layers,
+  LayoutDashboard,
+  Leaf,
+  Library,
+  Lightbulb,
+  LineChart,
+  Link,
+  ListChecks,
+  Lock,
+  Mail,
+  Map,
+  MessageCircle,
+  Mic,
+  Monitor,
+  Music,
+  Network,
+  Newspaper,
+  NotebookPen,
+  Package,
+  Palette,
+  PenTool,
+  Phone,
+  PieChart,
+  Plane,
+  Play,
+  Plug,
+  Printer,
+  Radar,
+  Radio,
+  RefreshCw,
+  Rocket,
+  Router,
+  Rss,
+  SatelliteDish,
+  Scan,
+  ScrollText,
+  Search,
+  Server,
+  Settings,
+  Share2,
+  Shield,
+  ShieldCheck,
+  ShoppingCart,
+  Signal,
+  Siren,
+  Smartphone,
+  Speaker,
+  Sparkles,
+  Star,
+  Sun,
+  Tag,
+  Terminal,
+  Thermometer,
+  Ticket,
+  Timer,
+  Tv,
+  Upload,
+  Users,
+  Utensils,
+  Video,
+  Wallet,
+  Waves,
+  Webhook,
+  Wifi,
+  Wind,
+  Workflow,
+  Wrench,
+  Zap,
+  type LucideIcon,
+} from "lucide-react";
+
+/** Every icon a stack can be given, keyed by the name stored in the database
+ *  (`lucide:<key>`). Grouped for the picker; the flat map is derived below. */
+export const ICON_GROUPS: { label: string; icons: Record<string, LucideIcon> }[] = [
+  {
+    label: "General",
+    icons: {
+      boxes: Boxes,
+      box: Box,
+      package: Package,
+      container: Container,
+      layers: Layers,
+      blocks: Blocks,
+      rocket: Rocket,
+      sparkles: Sparkles,
+      star: Star,
+      zap: Zap,
+      flame: Flame,
+      tag: Tag,
+      gift: Gift,
+      ticket: Ticket,
+      briefcase: Briefcase,
+      feather: Feather,
+    },
+  },
+  {
+    label: "Infrastructure",
+    icons: {
+      server: Server,
+      cpu: Cpu,
+      "hard-drive": HardDrive,
+      database: Database,
+      cloud: Cloud,
+      network: Network,
+      router: Router,
+      cable: Cable,
+      globe: Globe,
+      plug: Plug,
+      monitor: Monitor,
+      printer: Printer,
+      smartphone: Smartphone,
+    },
+  },
+  {
+    label: "Media",
+    icons: {
+      clapperboard: Clapperboard,
+      film: Film,
+      tv: Tv,
+      video: Video,
+      camera: Camera,
+      image: Image,
+      music: Music,
+      headphones: Headphones,
+      speaker: Speaker,
+      mic: Mic,
+      play: Play,
+      "gamepad-2": Gamepad2,
+      library: Library,
+      "book-open": BookOpen,
+    },
+  },
+  {
+    label: "Network & security",
+    icons: {
+      shield: Shield,
+      "shield-check": ShieldCheck,
+      "key-round": KeyRound,
+      lock: Lock,
+      "earth-lock": EarthLock,
+      siren: Siren,
+      wifi: Wifi,
+      signal: Signal,
+      radio: Radio,
+      "satellite-dish": SatelliteDish,
+      radar: Radar,
+      scan: Scan,
+    },
+  },
+  {
+    label: "Development",
+    icons: {
+      code: Code,
+      terminal: Terminal,
+      "git-branch": GitBranch,
+      bug: Bug,
+      workflow: Workflow,
+      webhook: Webhook,
+      wrench: Wrench,
+      settings: Settings,
+      bot: Bot,
+      brain: Brain,
+      atom: Atom,
+      dna: Dna,
+    },
+  },
+  {
+    label: "Monitoring",
+    icons: {
+      activity: Activity,
+      gauge: Gauge,
+      "bar-chart-3": BarChart3,
+      "pie-chart": PieChart,
+      "line-chart": LineChart,
+      "layout-dashboard": LayoutDashboard,
+      "heart-pulse": HeartPulse,
+      thermometer: Thermometer,
+      timer: Timer,
+      "alarm-clock": AlarmClock,
+    },
+  },
+  {
+    label: "Files & documents",
+    icons: {
+      folder: Folder,
+      "file-text": FileText,
+      "scroll-text": ScrollText,
+      "clipboard-list": ClipboardList,
+      "notebook-pen": NotebookPen,
+      archive: Archive,
+      download: Download,
+      upload: Upload,
+      "refresh-cw": RefreshCw,
+      link: Link,
+      search: Search,
+      inbox: Inbox,
+    },
+  },
+  {
+    label: "Communication",
+    icons: {
+      mail: Mail,
+      "message-circle": MessageCircle,
+      bell: Bell,
+      phone: Phone,
+      users: Users,
+      rss: Rss,
+      newspaper: Newspaper,
+      "share-2": Share2,
+    },
+  },
+  {
+    label: "Home & life",
+    icons: {
+      home: Home,
+      lightbulb: Lightbulb,
+      leaf: Leaf,
+      sun: Sun,
+      wind: Wind,
+      waves: Waves,
+      utensils: Utensils,
+      "shopping-cart": ShoppingCart,
+      wallet: Wallet,
+      banknote: Banknote,
+      coins: Coins,
+      "credit-card": CreditCard,
+      calendar: Calendar,
+      "list-checks": ListChecks,
+      map: Map,
+      compass: Compass,
+      plane: Plane,
+      car: Car,
+      dumbbell: Dumbbell,
+      palette: Palette,
+      brush: Brush,
+      "pen-tool": PenTool,
+      highlighter: Highlighter,
+    },
+  },
+];
+
+/** Flat lookup of every catalog icon. */
+export const STACK_ICONS: Record<string, LucideIcon> = Object.fromEntries(
+  ICON_GROUPS.flatMap((group) => Object.entries(group.icons))
+);
+
+/** The icon a stack gets when its name matches nothing at all. */
+export const FALLBACK_ICON = "boxes";
+
+/**
+ * Keywords that map a stack's name onto a catalog icon.
+ *
+ * The long tail is deliberate: the names people give stacks are the names of
+ * the apps inside them, and "jellyfin" should not need a manual pick to stop
+ * looking like a generic box. Order only breaks ties — the *longest* matching
+ * keyword wins, so "photoprism" beats a bare "photo" and "home-assistant"
+ * beats "home".
+ */
+const RULES: [icon: string, keywords: string[]][] = [
+  // Media
+  ["clapperboard", ["plex", "jellyfin", "emby", "kodi", "streamio", "media", "stream", "cinema", "kino", "medien"]],
+  ["film", ["radarr", "movie", "movies", "filme", "film", "tdarr", "handbrake"]],
+  ["tv", ["sonarr", "series", "serien", "show", "shows", "iptv", "threadfin", "xteve", "tvheadend", "tv", "fernsehen"]],
+  ["ticket", ["jellyseerr", "overseerr", "ombi", "petio", "request"]],
+  ["music", ["lidarr", "navidrome", "airsonic", "funkwhale", "music", "musik", "spotify", "beets", "gonic", "koel"]],
+  ["headphones", ["audiobookshelf", "audiobook", "podcast", "podgrab", "readarr", "booklore", "hoerbuch"]],
+  ["image", ["immich", "photoprism", "piwigo", "lychee", "photo", "photos", "fotos", "gallery", "galerie", "chevereto"]],
+  ["library", ["komga", "kavita", "calibre", "comic", "manga", "ebook", "bibliothek", "library", "booklog"]],
+  ["video", ["jitsi", "meet", "bigbluebutton", "owncast", "peertube", "tube", "youtube", "metube", "tubearchivist"]],
+  ["camera", ["frigate", "shinobi", "motioneye", "zoneminder", "nvr", "cctv", "surveillance", "kamera", "camera", "viseron"]],
+  ["gamepad-2", ["minecraft", "valheim", "palworld", "factorio", "satisfactory", "terraria", "pterodactyl", "steam", "game", "games", "gaming", "romm", "emulator"]],
+
+  // Downloads & indexers
+  ["download", ["qbittorrent", "transmission", "deluge", "rtorrent", "sabnzbd", "nzbget", "torrent", "download", "downloads", "jdownloader", "aria2", "pyload", "slskd", "usenet"]],
+  ["search", ["prowlarr", "jackett", "searxng", "searx", "whoogle", "meilisearch", "elasticsearch", "opensearch", "typesense", "search", "suche"]],
+  ["scroll-text", ["bazarr", "subtitle", "subtitles", "untertitel", "dozzle", "graylog", "loki", "logs", "syslog", "logging"]],
+
+  // Data stores
+  ["database", ["postgres", "postgresql", "pgadmin", "mysql", "mariadb", "mongo", "mongodb", "sqlite", "influx", "influxdb", "timescale", "clickhouse", "couchdb", "database", "datenbank", "supabase"]],
+  ["zap", ["redis", "valkey", "memcached", "dragonfly", "cache", "keydb"]],
+  ["share-2", ["rabbitmq", "kafka", "nats", "queue", "broker", "pulsar"]],
+  ["hard-drive", ["minio", "garage", "seaweedfs", "ceph", "storage", "speicher", "nas", "truenas"]],
+
+  // Network & proxies
+  ["network", ["traefik", "nginx", "caddy", "haproxy", "envoy", "proxy", "gateway", "ingress", "swag", "zoraxy", "pangolin"]],
+  ["shield", ["pihole", "adguard", "blocky", "unbound", "technitium", "dnsmasq", "adblock"]],
+  ["earth-lock", ["wireguard", "tailscale", "headscale", "netbird", "openvpn", "zerotier", "gluetun", "vpn", "wg"]],
+  ["shield-check", ["crowdsec", "fail2ban", "firewall", "opnsense", "pfsense", "waf", "security", "sicherheit", "modsecurity"]],
+  ["cloud", ["nextcloud", "owncloud", "seafile", "cloudflare", "cloudflared", "tunnel", "cloud", "pydio"]],
+  ["router", ["unifi", "omada", "openwrt", "router", "netbox", "phpipam", "librenms"]],
+  ["gauge", ["speedtest", "bandwidth", "iperf", "librespeed", "benchmark"]],
+
+  // Monitoring & ops
+  ["activity", ["uptime", "kuma", "statping", "healthcheck", "healthchecks", "netdata", "glances", "beszel", "scrutiny", "zabbix", "checkmk", "gatus", "status", "monitoring", "monitor"]],
+  ["bar-chart-3", ["prometheus", "metrics", "telegraf", "collectd", "victoriametrics", "statistik"]],
+  ["layout-dashboard", ["grafana", "dashboard", "dashy", "homarr", "heimdall", "homepage", "homer", "organizr", "flame", "glance", "startpage"]],
+  ["pie-chart", ["matomo", "umami", "plausible", "analytics", "goaccess", "posthog"]],
+  ["container", ["portainer", "dockge", "yacht", "docker", "compose", "swarm", "kubernetes", "k3s", "watchtower", "diun", "lazydocker"]],
+  ["package", ["registry", "harbor", "nexus", "artifactory", "verdaccio", "gitea-registry", "packages"]],
+
+  // Dev
+  ["git-branch", ["gitea", "forgejo", "gitlab", "github", "gogs", "onedev", "git", "repo", "repository"]],
+  ["rocket", ["jenkins", "drone", "woodpecker", "buildkite", "runner", "deploy", "deployment", "argocd", "flux", "production"]],
+  ["code", ["code-server", "codeserver", "vscode", "vscodium", "theia", "coder", "jupyter", "gitpod", "ide", "devcontainer"]],
+  ["wrench", ["it-tools", "ittools", "tools", "utility", "utilities", "werkzeug", "toolbox"]],
+  ["bug", ["sentry", "bugsink", "glitchtip", "debug", "testing"]],
+  ["workflow", ["n8n", "node-red", "nodered", "huginn", "windmill", "activepieces", "temporal", "airflow", "automation", "automatisierung", "flow", "workflow"]],
+  ["webhook", ["webhook", "webhooks", "smee", "ngrok", "relay"]],
+  ["brain", ["ollama", "open-webui", "openwebui", "localai", "llm", "whisper", "comfyui", "automatic1111", "stable-diffusion", "librechat", "anythingllm", "langflow", "chatgpt"]],
+  ["bot", ["bot", "bots", "discord", "telegram", "mirotalk", "matterbridge"]],
+  ["terminal", ["shell", "ssh", "sshwifty", "wetty", "terminal", "console", "guacamole"]],
+
+  // Files & documents
+  ["folder", ["filebrowser", "filestash", "files", "dateien", "folder", "explorer", "projectsend", "pingvin"]],
+  ["refresh-cw", ["syncthing", "resilio", "rclone", "sync", "syncing", "unison"]],
+  ["archive", ["duplicati", "restic", "borg", "borgmatic", "kopia", "duplicacy", "backrest", "backup", "backups", "sicherung", "archive", "archiv"]],
+  ["file-text", ["paperless", "docspell", "mayan", "stirling", "gotenberg", "ocr", "pdf", "dokumente", "documents", "invoiceninja", "papermerge"]],
+  ["book-open", ["wiki", "bookstack", "outline", "docmost", "mediawiki", "dokuwiki", "docusaurus", "mkdocs", "documentation", "handbuch"]],
+  ["notebook-pen", ["trilium", "memos", "joplin", "obsidian", "silverbullet", "standardnotes", "notes", "notizen", "notion", "affine", "anytype"]],
+  ["bookmark", ["linkwarden", "wallabag", "shaarli", "linkding", "shiori", "hoarder", "karakeep", "bookmark", "bookmarks", "lesezeichen"]],
+  ["rss", ["freshrss", "miniflux", "rss", "feed", "feeds", "newsblur", "commafeed", "reader"]],
+  ["newspaper", ["news", "nachrichten", "ghost", "wordpress", "blog", "hugo", "publii", "writefreely"]],
+
+  // Communication
+  ["mail", ["mailu", "mailcow", "mailserver", "roundcube", "postfix", "dovecot", "stalwart", "snappymail", "mailpit", "maildev", "smtp", "imap", "mail", "email"]],
+  ["message-circle", ["matrix", "synapse", "conduit", "element", "rocketchat", "mattermost", "zulip", "revolt", "chat", "irc", "thelounge", "signal-cli"]],
+  ["bell", ["ntfy", "gotify", "apprise", "pushover", "notify", "notification", "benachrichtigung", "alert", "alertmanager"]],
+  ["users", ["authentik", "authelia", "keycloak", "zitadel", "kanidm", "lldap", "ldap", "oauth", "oidc", "sso", "auth", "authentication", "login", "identity"]],
+  ["key-round", ["vaultwarden", "bitwarden", "vault", "passbolt", "keepass", "password", "passwort", "secrets", "infisical", "psono"]],
+
+  // Home & IoT
+  ["home", ["home-assistant", "homeassistant", "hass", "openhab", "domoticz", "iobroker", "smarthome", "hausautomation", "home"]],
+  ["lightbulb", ["deconz", "hue", "zigbee2mqtt", "zigbee", "zwave", "zwavejs", "esphome", "tasmota", "wled", "licht", "lights"]],
+  ["radio", ["mosquitto", "mqtt", "emqx", "rtl", "sdr", "meshtastic", "aprs"]],
+  ["thermometer", ["thermostat", "temperatur", "temperature", "sensors", "sensor", "weather", "wetter"]],
+  ["leaf", ["evcc", "solar", "photovoltaik", "openems", "energy", "energie", "garden", "garten"]],
+  ["printer", ["octoprint", "klipper", "mainsail", "fluidd", "prusa", "printer", "drucker", "cups", "3d"]],
+  ["car", ["teslamate", "tesla", "abrp", "auto", "vehicle", "fahrzeug"]],
+
+  // Life & admin
+  ["utensils", ["mealie", "tandoor", "grocy", "recipe", "recipes", "rezepte", "kochbuch", "kitchen", "food", "essen"]],
+  ["wallet", ["firefly", "actual", "budget", "ghostfolio", "maybe", "finance", "finanzen", "money", "geld", "banking", "wallabe"]],
+  ["shopping-cart", ["shop", "shopware", "woocommerce", "medusa", "store", "ecommerce", "shopping", "einkauf", "grocery"]],
+  ["list-checks", ["vikunja", "planka", "focalboard", "wekan", "kanboard", "taiga", "openproject", "redmine", "todo", "tasks", "task", "kanban", "aufgaben", "projekt", "project", "tickets", "jira"]],
+  ["calendar", ["radicale", "baikal", "davical", "calendar", "kalender", "caldav", "carddav", "cal", "booking", "cal-com", "easyappointments"]],
+  ["users", ["crm", "invoiceplane", "espocrm", "kunden", "contacts", "kontakte"]],
+  ["dumbbell", ["fitness", "workout", "wger", "sport", "training", "gym"]],
+  ["heart-pulse", ["health", "gesundheit", "medical", "librephotos-health", "openemr"]],
+  ["palette", ["excalidraw", "drawio", "penpot", "figma", "design", "tldraw", "canvas", "whiteboard"]],
+  ["map", ["openstreetmap", "osm", "nominatim", "traccar", "owntracks", "gpx", "wanderer", "maps", "karte", "navigation"]],
+  ["plane", ["flight", "flug", "travel", "reise", "adsb", "tar1090", "flightradar", "urlaub", "holiday"]],
+
+  // Generic shapes, last resort before the fallback
+  ["globe", ["website", "webseite", "site", "www", "web", "homepage-site", "portal", "landing"]],
+  ["server", ["api", "backend", "service", "microservice", "app", "daemon"]],
+  ["monitor", ["desktop", "vnc", "rdp", "kasm", "webtop", "remote"]],
+  ["settings", ["config", "admin", "verwaltung", "management", "panel", "control"]],
+  ["timer", ["cron", "scheduler", "job", "jobs", "batch", "zeitplan"]],
+  ["users", ["forum", "discourse", "flarum", "lemmy", "mastodon", "community", "social", "friendica", "pixelfed"]],
+];
+
+/** Normalize a name to the space-separated lowercase form the rules match on. */
+function normalize(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, " ")
+    .trim();
+}
+
+function matches(haystack: string, keyword: string): boolean {
+  if (keyword.length >= 4) {
+    // Long enough to be unambiguous inside a run-together name
+    // ("mediastack", "my-jellyfin-server").
+    return haystack.includes(keyword);
+  }
+  return new RegExp(`(?:^| )${keyword}(?: |$)`).test(haystack);
+}
+
+/**
+ * The icon a stack's name suggests.
+ *
+ * `extra` is matched with lower priority than the name itself — the stack id is
+ * passed there, so a renamed stack follows its new name rather than its slug.
+ */
+export function suggestIconName(name: string, extra = ""): string {
+  for (const haystack of [normalize(name), normalize(extra)]) {
+    if (!haystack) continue;
+    let best: { icon: string; score: number } | null = null;
+    for (const [icon, keywords] of RULES) {
+      for (const keyword of keywords) {
+        if (matches(haystack, keyword) && (!best || keyword.length > best.score)) {
+          best = { icon, score: keyword.length };
+        }
+      }
+    }
+    if (best) return best.icon;
+  }
+  return FALLBACK_ICON;
+}
+
+export type ResolvedIcon =
+  | { kind: "custom"; name: null }
+  | { kind: "builtin"; name: string; automatic: boolean };
+
+/** What to draw for a stack, given its stored choice (or the lack of one). */
+export function resolveStackIcon(stack: {
+  id: string;
+  name: string;
+  icon?: string | null;
+}): ResolvedIcon {
+  const stored = stack.icon ?? "";
+  if (stored.startsWith("custom:")) return { kind: "custom", name: null };
+  if (stored.startsWith("lucide:")) {
+    const name = stored.slice("lucide:".length);
+    // An icon that was dropped from the catalog must not blank the row out.
+    if (STACK_ICONS[name]) return { kind: "builtin", name, automatic: false };
+  }
+  return {
+    kind: "builtin",
+    name: suggestIconName(stack.name, stack.id),
+    automatic: true,
+  };
+}
+
+/** The component for a catalog name, falling back to the generic icon. */
+export function iconComponent(name: string): LucideIcon {
+  return STACK_ICONS[name] ?? STACK_ICONS[FALLBACK_ICON];
+}

frontend/src/pages/StackDetail.tsx

@@ -13,13 +13,14 @@ import {
   LayoutTemplate,
 } from "lucide-react";
 import { toast } from "sonner";
-import { Badge, Button, Card, Input, Spinner, StatusDot } from "@/components/ui";
+import { Badge, Button, Card, Input, Spinner } from "@/components/ui";
 import { ConfirmDialog } from "@/components/ui/ConfirmDialog";
 import { LogViewer } from "@/components/stacks/LogViewer";
 import { ContainerCard } from "@/components/stacks/ContainerCard";
 import { ActionStatusList } from "@/components/stacks/ActionStatusBanner";
 import { AutoUpdatePanel } from "@/components/stacks/AutoUpdatePanel";
 import { SecretsPanel } from "@/components/stacks/SecretsPanel";
+import { StackIconEditor } from "@/components/stacks/IconPicker";
 import { BackupButton } from "@/components/stacks/BackupRestore";
 import { stacksApi } from "@/api/stacks";
 import { templatesApi } from "@/api/templates";
@@ -51,15 +52,19 @@ export function StackDetail() {
   return (
     <div className="flex h-full flex-col space-y-4">
       <div className="flex flex-wrap items-center justify-between gap-3">
-        <div>
-          <div className="flex items-center gap-2">
-            <StatusDot status={data.status} />
-            <h1 className="sp-heading text-xl">{data.name}</h1>
-            <Badge status={data.status}>{data.status}</Badge>
+        <div className="flex items-center gap-3">
+          {/* Clicking the icon opens the picker — the way an existing stack
+              gets one without a trip through the editor. */}
+          <StackIconEditor stack={data} status={data.status} editable={isAdmin} />
+          <div>
+            <div className="flex items-center gap-2">
+              <h1 className="sp-heading text-xl">{data.name}</h1>
+              <Badge status={data.status}>{data.status}</Badge>
+            </div>
+            {data.description && (
+              <p className="mt-1 text-sm text-slate-500">{data.description}</p>
+            )}
           </div>
-          {data.description && (
-            <p className="mt-1 text-sm text-slate-500">{data.description}</p>
-          )}
         </div>
         {isAdmin && (
           <div className="flex flex-wrap gap-2">

frontend/src/pages/StackEditor.tsx

@@ -5,6 +5,8 @@ import Editor, { DiffEditor } from "@monaco-editor/react";
 import { Rocket, Save, Wand2, FileCode, CheckCircle2, GitCompare, X } from "lucide-react";
 import { Button, Card, Input } from "@/components/ui";
 import { EditorHelperPanel } from "@/components/stacks/EditorHelperPanel";
+import { IconPicker } from "@/components/stacks/IconPicker";
+import { StackIcon } from "@/components/ui/StackIcon";
 import { EnvEditor } from "@/components/env/EnvEditor";
 import { PortConflictDialog } from "@/components/stacks/PortConflictDialog";
 import { DeployConsole } from "@/components/stacks/DeployConsole";
@@ -32,6 +34,11 @@ export function StackEditor() {
 
   const [name, setName] = useState("");
   const [description, setDescription] = useState("");
+  // null = automatic (derived from the name). A freshly picked file is held
+  // here until the stack exists, because uploading needs an id.
+  const [icon, setIcon] = useState<string | null>(null);
+  const [iconFile, setIconFile] = useState<File | null>(null);
+  const [iconOpen, setIconOpen] = useState(false);
   const [yaml, setYaml] = useState(STARTER);
   const [env, setEnv] = useState("");
   const [tab, setTab] = useState<"compose" | "env">("compose");
@@ -56,6 +63,7 @@ export function StackEditor() {
     if (existing.data) {
       setName(existing.data.name);
       setDescription(existing.data.description ?? "");
+      setIcon(existing.data.icon ?? null);
       setYaml(existing.data.yaml || STARTER);
       setEnv(existing.data.env || "");
     }
@@ -69,11 +77,27 @@ export function StackEditor() {
     setSaving(true);
     try {
       let stackId = id;
+      // The icon field only ever carries a built-in choice or "" (automatic).
+      // A pending upload is sent separately once the stack has an id, and an
+      // upload that is already stored is left untouched — the server mints
+      // those values and refuses them coming back in.
+      const iconField =
+        iconFile || icon?.startsWith("custom:") ? undefined : icon ?? "";
       if (isNew) {
-        const created = await stacksApi.create({ name, description, yaml, env });
+        const created = await stacksApi.create({
+          name,
+          description,
+          icon: iconField,
+          yaml,
+          env,
+        });
         stackId = created.id;
       } else {
-        await stacksApi.update(id!, { name, description, yaml, env });
+        await stacksApi.update(id!, { name, description, icon: iconField, yaml, env });
+      }
+      if (iconFile && stackId) {
+        await stacksApi.uploadIcon(stackId, iconFile);
+        setIconFile(null);
       }
       qc.invalidateQueries({ queryKey: ["stacks"] });
       qc.invalidateQueries({ queryKey: ["stack", stackId] });
@@ -111,6 +135,28 @@ export function StackEditor() {
   const originalYaml = existing.data?.yaml ?? "";
   const dirty = !isNew && originalYaml !== yaml;
 
+  // Object URL for a file that has been chosen but not uploaded yet. Created in
+  // an effect rather than during render so React's cleanup is what revokes it —
+  // a URL made while rendering leaks on every re-render that discards it.
+  const [iconPreview, setIconPreview] = useState<string | null>(null);
+  useEffect(() => {
+    if (!iconFile) {
+      setIconPreview(null);
+      return;
+    }
+    const url = URL.createObjectURL(iconFile);
+    setIconPreview(url);
+    return () => URL.revokeObjectURL(url);
+  }, [iconFile]);
+  // What the icon would look like right now, name included: picking an icon
+  // before the stack exists has to preview against the name being typed.
+  const iconStack = {
+    id: id ?? "",
+    name,
+    icon: iconFile ? "custom:pending" : icon,
+  };
+  const iconStatus = existing.data?.status ?? "stopped";
+
   const validate = async () => {
     setValidating(true);
     setValidation(null);
@@ -144,6 +190,14 @@ export function StackEditor() {
     // bottom padding (pb-10), so the editor fills whatever screen the user has.
     <div className="flex h-[calc(100vh-116px)] min-h-[420px] flex-col space-y-3">
       <div className="flex flex-wrap items-center gap-3">
+        <button
+          type="button"
+          onClick={() => setIconOpen(true)}
+          title="Choose an icon for this stack"
+          className="rounded-[11px] outline-none ring-offset-2 transition-opacity hover:opacity-80 focus-visible:ring-2 focus-visible:ring-accent dark:ring-offset-slate-900"
+        >
+          <StackIcon stack={iconStack} status={iconStatus} previewUrl={iconPreview} />
+        </button>
         <Input
           className="max-w-xs"
           placeholder="Stack name"
@@ -162,6 +216,24 @@ export function StackEditor() {
         </Button>
       </div>
 
+      {iconOpen && (
+        <IconPicker
+          stack={iconStack}
+          status={iconStatus}
+          previewUrl={iconPreview}
+          onSelect={(value) => {
+            setIcon(value || null);
+            setIconFile(null);
+            setIconOpen(false);
+          }}
+          onUpload={(file) => {
+            setIconFile(file);
+            setIconOpen(false);
+          }}
+          onClose={() => setIconOpen(false)}
+        />
+      )}
+
       {convertOpen && (
         <Card className="flex items-center gap-2">
           <Input

frontend/src/types/index.ts

@@ -10,6 +10,9 @@ export interface StackSummary {
   id: string;
   name: string;
   description?: string | null;
+  /** "lucide:<name>", "custom:<ext>:<version>", or null for the icon derived
+   *  from the stack's name. See lib/stackIcons.ts. */
+  icon?: string | null;
   status: StackStatus;
   service_count: number;
   running_count: number;
@@ -46,6 +49,7 @@ export interface StackDetail {
   id: string;
   name: string;
   description?: string | null;
+  icon?: string | null;
   status: StackStatus;
   yaml: string;
   env: string;