refactor: let integrations own HTTP authentication

fix: make integration types searchable
feat: reuse authentication for all HTTP integrations
2026-09-12 23:57:33 +02:00 · 2026-09-12 23:39:10 +02:00 · 2026-09-12 23:33:23 +02:00 · 2026-09-12 22:45:52 +02:00 · 2026-09-12 20:32:03 +02:00 · 2026-09-12 20:26:39 +02:00
191 changed files with 27246 additions and 23913 deletions
@@ -13,7 +13,7 @@ interface HomarrCustomWidgetV2 {
 }
 ```

-The object key `default` is the required source ID; `default` is not a property on a source. Source properties are `name?`, `baseUrl`, `networkScope`, and `auth?`:
+`sources.default` is required. HTTP source properties: `name?`, `baseUrl`, `networkScope`, and `auth?`:

 ```json
 {
@@ -40,10 +40,12 @@ The object key `default` is the required source ID; `default` is not a property
 }
 ```

-Auth is `none`, `bearer`, `basic`, `{ "type": "apiKeyHeader", "name": "X-Api-Key" }`, or `{ "type": "apiKeyQuery", "name": "api_key" }`. A request defaults to source `default`, kind `query`, method `GET`, trigger `load`, inherited auth, and view permission. Set `trigger: "manual"` for a parameterized query. An action defaults to manual and modify permission. DELETE uses full permission and confirmation. Do not use `load: false`.
+Integration sources use `{"type":"integration","integrationKind":"sonarr"}`. Bind `integrationId` from `integration_all`; exports omit it. Calls require full integration access. Omit URL/auth fields. Paths append to the integration URL; non-GET requests must be actions.

-Use stable real URLs for public APIs and clear suggested URLs for self-hosted services. Homarr collects the installer's server URL, network scope, and credentials as source setup; credentials remain outside the manifest.
+Auth: `none`, `bearer`, `basic`, `{ "type": "apiKeyHeader", "name": "X-Api-Key" }`, or `{ "type": "apiKeyQuery", "name": "api_key" }`. Requests default to source `default`, kind `query`, method `GET`, trigger `load`, inherited auth, and view permission. Parameterized queries need `trigger: "manual"`. Actions default to manual/modify; DELETE requires full permission and confirmation. Do not use `load: false`.

-Paths use `{option:name}` and `{param:name}`; query/body references use `{ "$option": "name" }` and `{ "$param": "name" }`. Constants stay primitive (`take: 10`); `$param` is only for manual helpers, never load queries. Names and types are inferred.
+HTTP sources declare public URLs or self-hosted suggestions; installers configure their URL, network scope, and credentials separately.

-Every option has `label`, `control`, and `default`. Optional fields are `description`, `choices`, `choicesFrom`, `min`, `max`, `step`, `advanced`, and `group`.
+Paths bind `{option:name}` and `{param:name}`; query/body references bind `{ "$option": "name" }` and `{ "$param": "name" }`. Use primitive constants (`take: 10`). `$param` is only for manual requests.
+
+Options require `label`, `control`, and `default`. Optional fields: `description`, `choices`, `choicesFrom`, `min`, `max`, `step`, `advanced`, `group`.
@@ -25,6 +25,18 @@ body:
    attributes:
      label: Additional information
      description: Add any other information related to the bug here, screenshots if applicable.
+  - type: input
+    id: exactBuild
+    attributes:
+      label: Exact build or image
+      description: For preview or development builds, include the commit SHA or image digest. A moving tag such as v2 is not enough to identify the build.
+      placeholder: "Commit SHA, image digest, or release version"
+  - type: input
+    id: lastWorkingVersion
+    attributes:
+      label: Last working version
+      description: If this worked before, include the last version or build where you tried the same action. Leave blank if unknown.
+      placeholder: "Version or commit SHA"
  - type: dropdown
    id: version
    attributes:
@@ -33,6 +45,7 @@ body:
      options:
        # The below comment is used to insert a new version with on-release.yml
        #NEXT_VERSION#
+        - 1.77.0
        - 1.76.2
        - 1.76.1
        - 1.76.0
@@ -92,7 +92,7 @@ When documentation is needed, use these locations:
 - Lint: oxlint (not ESLint)
 - Format: oxfmt (not Prettier)
 - UI: Mantine (not Tailwind) — Tailwind is only used in docs app
- Mantine: use the project-scoped MCP server in `.mcp.json` for current v9 APIs, and check `packages/ui/` before creating a new primitive.
+- Mantine: use the `mantine` MCP server in `.mcp.json` for current v9 APIs before writing component code. Prefer built-in primitives (`Combobox`/`useCombobox`, the polymorphic `component` prop, `@mantine/hooks`) and check `packages/ui/` for existing conventions first.
 - Icons: @tabler/icons-react
 - Docs app can import from `@homarr/definitions` for shared types
 - Run `pnpm dev:cli -- dev` to browse local `homarr:*` images and remote PR images.
@@ -100,6 +100,10 @@ When documentation is needed, use these locations:
 - Run `pnpm dev:cli -- build --pr <number>` to build a PR locally from a temporary checkout.
 - Run Go checks from `tools/homarr-dev` with `go test ./...` and `go vet ./...`.

+## MCP servers
+
+`.mcp.json` declares project-scoped MCP servers. Keep only keyless definitions there; credentials belong in local dotfiles. See [Mantine LLM tooling](https://mantine.dev/guides/llms/) for client-specific setup.
+
 ## Agent Skills

 Portable skills live in `.agents/skills/`. Read the relevant `SKILL.md` before working in that domain; detailed references are loaded only when needed. Claude-compatible discovery is provided through `.claude/skills`.
@@ -1,3 +1,7 @@
+## [1.77.1](https://github.com/homarr-labs/homarr/compare/v1.77.0...v1.77.1) (2026-09-11)
+
+## [1.77.0](https://github.com/homarr-labs/homarr/compare/v1.76.2...v1.77.0) (2026-09-06)
+
 ## [1.76.2](https://github.com/homarr-labs/homarr/compare/v1.76.1...v1.76.2) (2026-08-27)

 ## [1.76.1](https://github.com/homarr-labs/homarr/compare/v1.76.0...v1.76.1) (2026-08-26)
@@ -13,7 +13,8 @@ You can change the user and group by using the `PUID` and `PGID` environment var
 Important to note is, that you'll also need to change the permissions for the mounted directories accordingly.

 :::info
-When starting up an updated version of the container it will have about **10 seconds longer to start** as it has to change the permissions of the app directories
+At startup, Homarr updates ownership of its data directories and runtime caches for the selected user and group.
+Startup time depends on the amount of persistent data; application code and dependencies do not need ownership changes.
 :::

 ## Without mounted Docker socket
@@ -28,6 +28,8 @@ import { smartHomeExecuteAutomationWidget } from "@site/docs/widgets/smart-home-
  ]}
 />

+Entity toggles and automation triggers send JSON requests to Home Assistant. A rejected action is shown as a failure.
+
 ### Adding the integration

 <AddingIntegration />
@@ -30,6 +30,8 @@ import { systemResourcesWidget } from "@site/docs/widgets/system-resources";
  ]}
 />

+Disk temperatures are matched to filesystem partitions, including device names without the `/dev/` prefix.
+
 ### Adding the integration

 <AddingIntegration />
@@ -19,6 +19,9 @@ import Alert from "@theme/Admonition";

 <IntegrationCapabilites items={[{ widget: healthMonitoringWidget }, { widget: systemResourcesWidget }]} />

+Disk space uses each pool's root dataset to account for RAIDZ parity and dataset limits. If dataset space is unavailable,
+Homarr falls back to physical pool space, which reads higher on RAIDZ, and keeps reporting pool health.
+
 ### Adding the integration

 <AddingIntegration />
@@ -23,6 +23,8 @@ import imgSelectApikeyPreset from "./imgs/unraid-select-api-key-preset.png";

 <IntegrationCapabilites items={[{ widget: healthMonitoringWidget }, { widget: systemResourcesWidget }]} />

+CPU usage is averaged across logical processors, including SMT threads.
+
 ### Adding the integration

 <AddingIntegration />
@@ -64,3 +64,8 @@ Below you can find instructions for some of the integrations.
 Since version 6 of Pi-hole, the web interface can be accessed through HTTPS.
 The certificate can be found in the path `/etc/pihole/tls_ca.crt`. To add the certificate, this file needs to be copied and uploaded to Homarr.
 You can find more details regarding SSL / TLS for Pi-hole [here](https://docs.pi-hole.net/api/tls/).
+
+### Proxmox
+
+For the default Proxmox VE cluster certificates, trust the cluster CA from `/etc/pve/pve-root-ca.pem` on any node.
+See [Proxmox certificate management](https://pve.proxmox.com/wiki/Certificate_Management).
@@ -3,10 +3,28 @@
 Most widgets use a single source named `default`; the manifest must contain it. Extra keyed sources are available for widgets
 that combine APIs. Source IDs are case-insensitively unique. Base URLs must use HTTP(S), contain no embedded credentials,
 query string, or fragment, and sources can be `public`, `private`, or `loopback`. Authentication is `none`, `bearer`,
-`basic`, an API-key header, or an API-key query parameter. Credentials belong to the widget but remain outside its manifest.
+`basic`, an API-key header, or an API-key query parameter. HTTP source credentials belong to the widget but remain outside its manifest.
 Source origins are fixed by the definition and source-setup flow; widget options and invocation parameters cannot redirect a
 request to a different origin.

+## Existing integrations
+
+Sources can reuse any configured HTTP integration, including its saved credentials and login session. WebSocket-only integrations and the internal mock integration are excluded:
+
+```json
+{
+  "sources": { "default": { "type": "integration", "integrationKind": "sonarr" } },
+  "requests": { "queue": { "path": "/api/v3/queue" } }
+}
+```
+
+Select the local instance during source setup. Homarr uses its current URL, API key, and trusted certificates;
+paths append to the saved URL, including reverse-proxy subpaths. Changing the integration updates all sources bound to it.
+Deleting it leaves the widget unconfigured until another instance is selected. The binding is shared by every placement
+of that widget definition. Exports and Workshop submissions retain the required type and omit the local integration ID.
+
+Arbitrary integration requests require integration `full` access, including GET requests: service APIs can expose credentials or change state through reads. Board permissions still apply separately. Saved credentials are redacted from upstream responses. Non-GET integration requests must be actions. Requests and redirects stay within the configured URL path. Expired sessions are refreshed; queries can retry once, while actions require another explicit invocation.
+
 ## Named requests

 Requests are keyed by ID. `source`, `kind`, `method`, `trigger`, `auth`, and `permission` have sensible defaults, so a load query can be as small as:
@@ -12,7 +12,7 @@ import { appWidget } from ".";
 <WidgetHeader widget={appWidget} categories={["Links", "Apps"]} />

 The App widget opens an application or website and can show whether Homarr can reach it. Configure the target and status
-check from the tile's edit actions.
+check from the tile's edit actions. In view mode, right-click uses the browser's link menu; Homarr's widget menu remains available in edit mode.

 ### Adding the widget

@@ -22,6 +22,8 @@ one-row widgets. Horizontal, vertical, compact-grid, and icon-only layouts keep
 preserves its configured columns when the dashboard is scaled. Bookmark cards, icons, text, and gaps keep the same
 visual density when a low-column dashboard is enlarged to fill the screen.

+Right-click a bookmark link in view mode to use the browser menu, including opening it in a new tab or copying its address.
+
 ### Screenshots

 import gridIconsOnly from "./img/grid-icons-only.png";
@@ -41,6 +41,7 @@ import temperature from "./img/temperature.png";
 ### Interactions

 - Toggle entity state by clicking on the entity (only when clickable enabled).
+- After a successful toggle, the displayed state refreshes immediately.
 - If Homarr cannot refresh an entity, the last known state stays visible but toggling is disabled until the connection recovers.

 <WidgetInteractionGuide />
@@ -51,4 +51,6 @@ import withDisplayname from "./img/with-displayname.png";

 ### Configuration

+Use the Home Assistant entity ID (for example, `automation.turn_on_lights`) in the **Automation ID** field, not the automation's internal ID.
+
 <WidgetConfig configuration={smartHomeExecuteAutomationWidget.configuration} />
@@ -32,6 +32,7 @@ import type { WorkshopSubmission, WorkshopVote } from "@site/src/lib/pocketbase"
 import { getWorkshopBackend } from "@site/src/lib/pocketbase";
 import { getRuntimeWorkshopApiUrl } from "@site/src/lib/runtime-config";
 import type { SubmissionType } from "@site/src/lib/workshop-schema";
+import { integrationDefs, isHttpIntegrationKind } from "@homarr/definitions";
 import type { HomarrCustomWidgetV2 } from "@homarr/custom-widgets/core";
 import {
  githubAvatarUrl,
@@ -96,7 +97,15 @@ const isNotFound = (caught: unknown) =>

 const avatarFallback = (name: string) => name.trim().slice(0, 1).toUpperCase() || "?";

-const sourceHost = (baseUrl: string) => {
+type WidgetSource = HomarrCustomWidgetV2["sources"][string];
+
+const sourceHost = (source: WidgetSource) => {
+  if (source.type === "integration") {
+    if (isHttpIntegrationKind(source.integrationKind))
+      return `${integrationDefs[source.integrationKind].name} integration`;
+    return `${source.integrationKind} integration`;
+  }
+  const { baseUrl } = source;
  try {
    return new URL(baseUrl).host;
  } catch {
@@ -104,26 +113,30 @@ const sourceHost = (baseUrl: string) => {
  }
 };

-const sourceAuthLabel = (auth: HomarrCustomWidgetV2["sources"][string]["auth"]) => {
-  if (typeof auth === "string")
-    return auth === "none" ? "No credentials" : auth === "basic" ? "Basic auth" : "Bearer token";
-  return auth.type === "apiKeyHeader" ? `API key header · ${auth.name}` : `API key query · ${auth.name}`;
+const sourceAuthLabel = (source: WidgetSource) => {
+  if (source.type === "integration") return "Uses stored integration credentials";
+  const { auth } = source;
+  if (auth === "none") return "No credentials";
+  if (auth === "basic") return "Basic auth";
+  if (auth === "bearer") return "Bearer token";
+  if (auth.type === "apiKeyHeader") return `API key header · ${auth.name}`;
+  return `API key query · ${auth.name}`;
 };

-const sourceNeedsSecret = (auth: HomarrCustomWidgetV2["sources"][string]["auth"]) => auth !== "none";
+const sourceNeedsSecret = (source: WidgetSource) => source.type === "integration" || source.auth !== "none";

 const WidgetSafetySummary = ({ widget }: { widget: HomarrCustomWidgetV2 }) => {
  const sources = Object.entries(widget.sources);
  const requests = Object.values(widget.requests);
-  const protectedSources = sources.filter(([, source]) => sourceNeedsSecret(source.auth));
+  const protectedSources = sources.filter(([, source]) => sourceNeedsSecret(source));
  const queryCount = requests.filter((request) => request.kind === "query").length;
  const actionCount = requests.filter((request) => request.kind === "action").length;
  const credentialLabel =
    protectedSources.length === 0
      ? "None required"
      : protectedSources.length === 1
-        ? sourceAuthLabel(protectedSources[0][1].auth)
-        : `${protectedSources.length} credentials required`;
+        ? sourceAuthLabel(protectedSources[0][1])
+        : `${protectedSources.length} authenticated sources`;

  return (
    <section
@@ -152,9 +165,9 @@ const WidgetSafetySummary = ({ widget }: { widget: HomarrCustomWidgetV2 }) => {
          <dd className="mt-1.5 space-y-1.5">
            {sources.slice(0, 2).map(([id, source]) => (
              <span key={id} className="flex min-w-0 items-center justify-between gap-2">
-                <span className="truncate font-mono text-xs font-medium">{sourceHost(source.baseUrl)}</span>
+                <span className="truncate font-mono text-xs font-medium">{sourceHost(source)}</span>
                <Badge variant="secondary" className="shrink-0 font-normal">
-                  {source.networkScope}
+                  {source.networkScope ?? "integration"}
                </Badge>
              </span>
            ))}
@@ -536,7 +549,7 @@ const MarketplaceDetail = ({ workshopUrl }: { workshopUrl: string }) => {
  const sources = widgetDefinition ? Object.entries(widgetDefinition.sources) : [];
  const requests = widgetDefinition ? Object.entries(widgetDefinition.requests) : [];
  const options = widgetDefinition ? Object.entries(widgetDefinition.options) : [];
-  const protectedSources = sources.filter(([, source]) => sourceNeedsSecret(source.auth));
+  const protectedSources = sources.filter(([, source]) => sourceNeedsSecret(source));
  const displayedContent = formatWorkshopContent(submission.type, submission.content);
  const socialTitle = `${submission.title} · Homarr Workshop`;
  const socialDescription = `${typeSocialLabels[submission.type]} for Homarr. ${submission.description}`.trim();
@@ -779,11 +792,11 @@ const MarketplaceDetail = ({ workshopUrl }: { workshopUrl: string }) => {
                        <div className="flex items-center justify-between gap-2 text-sm">
                          <span className="truncate font-medium">{source.name || id}</span>
                          <Badge variant="secondary" className="shrink-0">
-                            {source.networkScope}
+                            {source.networkScope ?? "integration"}
                          </Badge>
                        </div>
-                        <p className="truncate text-xs text-muted-foreground">{sourceHost(source.baseUrl)}</p>
-                        <p className="mt-0.5 text-xs text-muted-foreground">{sourceAuthLabel(source.auth)}</p>
+                        <p className="truncate text-xs text-muted-foreground">{sourceHost(source)}</p>
+                        <p className="mt-0.5 text-xs text-muted-foreground">{sourceAuthLabel(source)}</p>
                      </div>
                    ))}
                  </div>
@@ -16,6 +16,9 @@ import {
 } from "@mantine/core";
 import { IconCheck, IconKey, IconLock } from "@tabler/icons-react";

+import type { CustomWidgetSource } from "@homarr/custom-widgets/core";
+import { IntegrationSourceSelect } from "~/components/custom-widgets/integration-source-select";
+
 import { useI18n } from "@homarr/translation/client";

 interface RequestDetails {
@@ -24,10 +27,7 @@ interface RequestDetails {
  kinds: Array<"apiKey" | "username" | "password">;
  expiresAt: number;
  status: "pending" | "completed";
-  source: {
-    baseUrl: string;
-    networkScope: "public" | "private" | "loopback";
-  };
+  source: CustomWidgetSource;
 }

 export function CustomWidgetConfigurationEntry({ token }: { token: string }) {
@@ -35,6 +35,7 @@ export function CustomWidgetConfigurationEntry({ token }: { token: string }) {
  const tSecret = useI18n("customWidget.secret");
  const [details, setDetails] = useState<RequestDetails | null>(null);
  const [values, setValues] = useState<Record<string, string>>({});
+  const [integrationId, setIntegrationId] = useState<string>();
  const [baseUrl, setBaseUrl] = useState("");
  const [networkScope, setNetworkScope] = useState<"public" | "private" | "loopback">("public");
  const [error, setError] = useState<string | null>(null);
@@ -47,8 +48,9 @@ export function CustomWidgetConfigurationEntry({ token }: { token: string }) {
        const body = (await response.json()) as RequestDetails | { error: string };
        if (!response.ok || "error" in body) throw new Error("error" in body ? body.error : t("unavailable"));
        setDetails(body);
-        setBaseUrl(body.source.baseUrl);
-        setNetworkScope(body.source.networkScope);
+        setBaseUrl(body.source.baseUrl ?? "");
+        setNetworkScope(body.source.networkScope ?? "public");
+        setIntegrationId(body.source.integrationId);
      })
      .catch((cause: unknown) => setError(cause instanceof Error ? cause.message : t("unavailable")))
      .finally(() => setLoading(false));
@@ -58,10 +60,12 @@ export function CustomWidgetConfigurationEntry({ token }: { token: string }) {
    setSaving(true);
    setError(null);
    try {
+      let configuration: unknown = { baseUrl, networkScope, secrets: values };
+      if (details?.source.type === "integration") configuration = { integrationId, secrets: {} };
      const response = await fetch(`/api/custom-widgets/configuration-request/${encodeURIComponent(token)}`, {
        method: "POST",
        headers: { "content-type": "application/json" },
-        body: JSON.stringify({ baseUrl, networkScope, secrets: values }),
+        body: JSON.stringify(configuration),
      });
      const body = (await response.json()) as { status?: string; error?: string };
      if (!response.ok) throw new Error(body.error ?? t("saveError"));
@@ -102,20 +106,31 @@ export function CustomWidgetConfigurationEntry({ token }: { token: string }) {
                  {t("source", { name: details.sourceName })}
                </Text>
              </Card>
-              <TextInput
-                label={t("baseUrl")}
-                type="url"
-                value={baseUrl}
-                onChange={(event) => setBaseUrl(event.currentTarget.value)}
-                required
-              />
-              <Select
-                label={t("networkScope")}
-                data={["public", "private", "loopback"]}
-                value={networkScope}
-                allowDeselect={false}
-                onChange={(value) => value && setNetworkScope(value as typeof networkScope)}
-              />
+              {details.source.type === "integration" && (
+                <IntegrationSourceSelect
+                  kind={details.source.integrationKind}
+                  integrationId={integrationId}
+                  onChange={setIntegrationId}
+                />
+              )}
+              {details.source.type !== "integration" && (
+                <>
+                  <TextInput
+                    label={t("baseUrl")}
+                    type="url"
+                    value={baseUrl}
+                    onChange={(event) => setBaseUrl(event.currentTarget.value)}
+                    required
+                  />
+                  <Select
+                    label={t("networkScope")}
+                    data={["public", "private", "loopback"]}
+                    value={networkScope}
+                    allowDeselect={false}
+                    onChange={(value) => value && setNetworkScope(value as typeof networkScope)}
+                  />
+                </>
+              )}
              {details.kinds.map((kind) => {
                const Input = kind === "username" ? TextInput : PasswordInput;
                return (
@@ -132,7 +147,10 @@ export function CustomWidgetConfigurationEntry({ token }: { token: string }) {
              })}
              <Button
                loading={saving}
-                disabled={!URL.canParse(baseUrl) || details.kinds.some((kind) => !values[kind])}
+                disabled={
+                  (details.source.type === "integration" ? !integrationId : !URL.canParse(baseUrl)) ||
+                  details.kinds.some((kind) => !values[kind])
+                }
                onClick={() => void submit()}
              >
                {t("save")}
@@ -4,9 +4,15 @@ import { Button, Fieldset, Group, PasswordInput, Select, Stack, TextInput } from
 import { IconKey, IconTrash } from "@tabler/icons-react";

 import { getCustomWidgetSourceUrlIssue } from "@homarr/custom-widgets/core";
-import type { CustomWidgetSource, CustomWidgetSourceUrlIssue } from "@homarr/custom-widgets/core";
+import type {
+  CustomWidgetHttpSource,
+  CustomWidgetSource,
+  CustomWidgetSourceUrlIssue,
+} from "@homarr/custom-widgets/core";
 import { useI18n } from "@homarr/translation/client";

+import { IntegrationSourceSelect } from "~/components/custom-widgets/integration-source-select";
+
 import type { CustomWidgetWorkbenchForm } from "./_custom-widget-form-utils";
 import { CustomWidgetIdentifierInput } from "./_custom-widget-identifier-input";

@@ -52,9 +58,6 @@ export function CustomWidgetSourceField({
  onRemove,
 }: CustomWidgetSourceFieldProps) {
  const t = useI18n("customWidget.workbench.sources");
-  const tSecret = useI18n("customWidget.secret");
-  const baseUrlIssue = getCustomWidgetSourceUrlIssue(source.baseUrl);
-  const authType = typeof source.auth === "string" ? source.auth : source.auth.type;

  return (
    <Fieldset legend={index === 0 ? t("primary") : source.name}>
@@ -73,72 +76,41 @@ export function CustomWidgetSourceField({
            onChange={(event) => onUpdate(index, { name: event.currentTarget.value })}
          />
        </Group>
-        <TextInput
-          label={t("baseUrl")}
-          type="url"
-          value={source.baseUrl}
-          error={baseUrlIssue ? t(sourceUrlErrorKeys[baseUrlIssue]) : undefined}
-          onChange={(event) => onUpdate(index, { baseUrl: event.currentTarget.value })}
+        <Select
+          label={t("sourceType")}
+          data={[
+            { value: "http", label: t("manualSource") },
+            { value: "integration", label: t("existingIntegration") },
+          ]}
+          value={source.type ?? "http"}
+          allowDeselect={false}
+          onChange={(type) => {
+            if (type === "integration") onUpdate(index, { type, integrationKind: "sonarr" });
+            else if (type === "http")
+              onUpdate(index, { type, baseUrl: "https://example.com", networkScope: "public", auth: "none" });
+          }}
        />
-        <Group grow align="start">
-          <Select
-            label={t("networkScope")}
-            data={["public", "private", "loopback"]}
-            value={source.networkScope}
-            onChange={(value) =>
-              value && onUpdate(index, { networkScope: value as CustomWidgetSource["networkScope"] })
-            }
-            allowDeselect={false}
-          />
-          <Select
-            label={t("authentication")}
-            data={["none", "bearer", "basic", "apiKeyHeader", "apiKeyQuery"]}
-            value={authType}
-            onChange={(value) => onSetAuthentication(index, value ?? "none")}
-            allowDeselect={false}
-          />
-        </Group>
-        {typeof source.auth === "object" && source.auth.type === "apiKeyHeader" && (
-          <TextInput
-            label={t("headerName")}
-            value={source.auth.name}
-            onChange={(event) => onUpdate(index, { auth: { type: "apiKeyHeader", name: event.currentTarget.value } })}
+        {source.type === "integration" && (
+          <IntegrationSourceSelect
+            kind={source.integrationKind}
+            integrationId={source.integrationId}
+            onChange={(integrationId) => onUpdate(index, { integrationId })}
+            onKindChange={(integrationKind) => onUpdate(index, { integrationKind, integrationId: undefined })}
          />
        )}
-        {typeof source.auth === "object" && source.auth.type === "apiKeyQuery" && (
-          <TextInput
-            label={t("queryParameter")}
-            value={source.auth.name}
-            onChange={(event) => onUpdate(index, { auth: { type: "apiKeyQuery", name: event.currentTarget.value } })}
+        {source.type !== "integration" && (
+          <CustomWidgetHttpSourceFields
+            source={source}
+            index={index}
+            form={form}
+            definitionId={definitionId}
+            clearSecretPending={clearSecretPending}
+            onUpdate={onUpdate}
+            onSetAuthentication={onSetAuthentication}
+            onSetSecret={onSetSecret}
+            onClearSecret={onClearSecret}
          />
        )}
-        {(secretFields[authType] ?? []).map(({ kind }) => {
-          const secret = form.values.secrets.find((entry) => entry.sourceId === source.id && entry.kind === kind);
-          const Input = kind === "username" ? TextInput : PasswordInput;
-          return (
-            <Group key={kind} align="end" wrap="nowrap">
-              <Input
-                style={{ flex: 1 }}
-                label={tSecret(kind)}
-                value={secret?.value ?? ""}
-                placeholder={secret?.hasValue ? t("configured") : undefined}
-                leftSection={<IconKey size={15} />}
-                onChange={(event) => onSetSecret(source.id, kind, event.currentTarget.value)}
-              />
-              {definitionId && secret?.hasValue && (
-                <Button
-                  type="button"
-                  color="red"
-                  variant="subtle"
-                  loading={clearSecretPending}
-                  onClick={() => void onClearSecret(source.id, kind)}
-                >
-                  {t("clear")}
-                </Button>
-              )}
-            </Group>
-          );
-        })}
        {index > 0 && (
          <Button
            type="button"
@@ -154,3 +126,88 @@ export function CustomWidgetSourceField({
    </Fieldset>
  );
 }
+
+function CustomWidgetHttpSourceFields({
+  source,
+  index,
+  form,
+  definitionId,
+  clearSecretPending,
+  onUpdate,
+  onSetAuthentication,
+  onSetSecret,
+  onClearSecret,
+}: Omit<CustomWidgetSourceFieldProps, "source" | "onRemove"> & { source: CustomWidgetHttpSource & { id: string } }) {
+  const t = useI18n("customWidget.workbench.sources");
+  const tSecret = useI18n("customWidget.secret");
+  const baseUrlIssue = getCustomWidgetSourceUrlIssue(source.baseUrl);
+  const authType = typeof source.auth === "string" ? source.auth : source.auth.type;
+  return (
+    <>
+      <TextInput
+        label={t("baseUrl")}
+        type="url"
+        value={source.baseUrl}
+        error={baseUrlIssue ? t(sourceUrlErrorKeys[baseUrlIssue]) : undefined}
+        onChange={(event) => onUpdate(index, { baseUrl: event.currentTarget.value })}
+      />
+      <Group grow align="start">
+        <Select
+          label={t("networkScope")}
+          data={["public", "private", "loopback"]}
+          value={source.networkScope}
+          onChange={(value) => value && onUpdate(index, { networkScope: value as CustomWidgetSource["networkScope"] })}
+          allowDeselect={false}
+        />
+        <Select
+          label={t("authentication")}
+          data={["none", "bearer", "basic", "apiKeyHeader", "apiKeyQuery"]}
+          value={authType}
+          onChange={(value) => onSetAuthentication(index, value ?? "none")}
+          allowDeselect={false}
+        />
+      </Group>
+      {typeof source.auth === "object" && source.auth.type === "apiKeyHeader" && (
+        <TextInput
+          label={t("headerName")}
+          value={source.auth.name}
+          onChange={(event) => onUpdate(index, { auth: { type: "apiKeyHeader", name: event.currentTarget.value } })}
+        />
+      )}
+      {typeof source.auth === "object" && source.auth.type === "apiKeyQuery" && (
+        <TextInput
+          label={t("queryParameter")}
+          value={source.auth.name}
+          onChange={(event) => onUpdate(index, { auth: { type: "apiKeyQuery", name: event.currentTarget.value } })}
+        />
+      )}
+      {(secretFields[authType] ?? []).map(({ kind }) => {
+        const secret = form.values.secrets.find((entry) => entry.sourceId === source.id && entry.kind === kind);
+        const Input = kind === "username" ? TextInput : PasswordInput;
+        return (
+          <Group key={kind} align="end" wrap="nowrap">
+            <Input
+              style={{ flex: 1 }}
+              label={tSecret(kind)}
+              value={secret?.value ?? ""}
+              placeholder={secret?.hasValue ? t("configured") : undefined}
+              leftSection={<IconKey size={15} />}
+              onChange={(event) => onSetSecret(source.id, kind, event.currentTarget.value)}
+            />
+            {definitionId && secret?.hasValue && (
+              <Button
+                type="button"
+                color="red"
+                variant="subtle"
+                loading={clearSecretPending}
+                onClick={() => void onClearSecret(source.id, kind)}
+              >
+                {t("clear")}
+              </Button>
+            )}
+          </Group>
+        );
+      })}
+    </>
+  );
+}
@@ -28,6 +28,12 @@ export function CustomWidgetSourcesEditor({
  const clearSecretMutation = clientApi.customWidget.secretClear.useMutation();
  const sources = parseSources(form.values.sources);
  const update = (index: number, changes: Partial<CustomWidgetSource> & { id?: string }) => {
+    if (changes.type) {
+      form.setFieldValue(
+        "secrets",
+        form.values.secrets.filter((secret) => secret.sourceId !== sources[index]?.id),
+      );
+    }
    const previousId = sources[index]?.id;
    const nextId = changes.id ?? previousId;
    if (nextId && sources.some((source, sourceIndex) => sourceIndex !== index && source.id === nextId)) {
@@ -42,7 +48,7 @@ export function CustomWidgetSourcesEditor({
        Object.fromEntries(
          sourceEntries.map(([id, source], i) => [
            i === index ? nextId : id,
-            i === index ? { ...source, ...changes, id: undefined } : source,
+            i === index ? { ...(changes.type ? { name: source.name } : source), ...changes, id: undefined } : source,
          ]),
        ),
        null,
@@ -1,5 +1,6 @@
 "use client";

+import { SourceSetupPanel } from "~/components/custom-widgets/integration-source-select";
 import { useRouter } from "next/navigation";
 import { useMemo } from "react";
 import {
@@ -22,7 +23,7 @@ import { IconAlertTriangle, IconArrowLeft, IconDownload, IconExternalLink, IconF

 import { CUSTOM_WIDGET_SCHEMA } from "@homarr/custom-widgets/core";
 import type { HomarrCustomWidgetV2 } from "@homarr/custom-widgets/core";
-import { CustomWidgetSourceSetupPanel, ImportReviewContent } from "@homarr/custom-widgets/workbench";
+import { ImportReviewContent } from "@homarr/custom-widgets/workbench";
 import { useI18n } from "@homarr/translation/client";
 import { Link } from "@homarr/ui";
 import { useWorkshopReportSummariesQuery, useWorkshopSubmissionQuery } from "@homarr/workshop/backend";
@@ -190,7 +191,7 @@ export function WorkshopDetail({ id }: { id: string }) {
                </Text>
              </Box>
              <ImportReviewContent review={importer.review} messages={importer.reviewMessages}>
-                <CustomWidgetSourceSetupPanel
+                <SourceSetupPanel
                  setups={importer.setups}
                  values={importer.values}
                  onChange={importer.setValue}
@@ -3,6 +3,7 @@ import { NextResponse } from "next/server";

 import {
  claimCustomWidgetConfigurationRequest,
+  assertCustomWidgetIntegrationBindings,
  completeCustomWidgetConfigurationRequest,
  configureCustomWidgetSourceFromRequest,
  configurePreviewSessionSource,
@@ -12,6 +13,7 @@ import {
 import { customWidgetSourceSchema } from "@homarr/custom-widgets/core";
 import { invalidateCustomWidgetResponseCache } from "@homarr/custom-widgets/server";
 import { db } from "@homarr/db";
+import { auth } from "@homarr/auth/next";

 import { adminRoute } from "../../admin";
 import { readConfigurationRequestBody } from "../body";
@@ -52,17 +54,40 @@ const completeConfigurationRequest = async (request: NextRequest, context: Route
    return NextResponse.json({ error: "Enter a valid source configuration." }, { status: 400 });
  }
  const body = parsedBody.data;
-  const sourceResult = customWidgetSourceSchema.safeParse({
-    ...pending.source,
-    baseUrl: body.baseUrl,
-    networkScope: body.networkScope,
-  });
+  let candidate: unknown;
+  if (pending.source.type === "integration") {
+    if (
+      !body.integrationId ||
+      body.baseUrl !== undefined ||
+      body.networkScope !== undefined ||
+      Object.keys(body.secrets).length > 0
+    ) {
+      return NextResponse.json({ error: "Select an existing integration." }, { status: 400 });
+    }
+    candidate = { ...pending.source, integrationId: body.integrationId };
+  } else {
+    if (body.integrationId)
+      return NextResponse.json({ error: "HTTP sources cannot bind an integration." }, { status: 400 });
+    candidate = { ...pending.source, baseUrl: body.baseUrl, networkScope: body.networkScope };
+  }
+  const sourceResult = customWidgetSourceSchema.safeParse(candidate);
  if (!sourceResult.success) {
    return NextResponse.json(
      { error: sourceResult.error.issues[0]?.message ?? "Enter a valid server URL." },
      { status: 400 },
    );
  }
+  try {
+    await assertCustomWidgetIntegrationBindings(
+      { db, session: await auth() },
+      { [pending.sourceId]: sourceResult.data },
+    );
+  } catch {
+    return NextResponse.json(
+      { error: "The selected integration is unavailable or has a different type." },
+      { status: 400 },
+    );
+  }
  const secrets = pending.kinds.flatMap((kind) => {
    const value = body.secrets[kind];
    return typeof value === "string" && value.length > 0 && value.length <= 8192
@@ -95,6 +120,7 @@ const completeConfigurationRequest = async (request: NextRequest, context: Route
      const result = await configureCustomWidgetSourceFromRequest(db, {
        definitionId: claimed.target.id,
        sourceId: claimed.sourceId,
+        integrationId: sourceResult.data.integrationId,
        baseUrl: sourceResult.data.baseUrl,
        networkScope: sourceResult.data.networkScope,
        secrets,
@@ -1,11 +1,17 @@
 import { z } from "zod/v4";

 export const MAX_CONFIGURATION_REQUEST_BODY_BYTES = 24 * 1024;
-const configurationRequestBodySchema = z.strictObject({
-  baseUrl: z.string(),
-  networkScope: z.enum(["public", "private", "loopback"]),
-  secrets: z.record(z.string(), z.string()),
-});
+const configurationRequestBodySchema = z
+  .strictObject({
+    baseUrl: z.string().optional(),
+    integrationId: z.string().min(1).max(100).optional(),
+    networkScope: z.enum(["public", "private", "loopback"]).optional(),
+    secrets: z.record(z.string(), z.string()),
+  })
+  .refine(
+    (value) => Boolean(value.integrationId) || (value.baseUrl !== undefined && value.networkScope !== undefined),
+    "Provide an integration or HTTP connection",
+  );

 export async function readConfigurationRequestBody(
  request: Request,
@@ -4,6 +4,7 @@ import { callMcpTool } from "@homarr/api/mcp";
 import type { McpTool } from "@homarr/api/mcp";

 import { toAssistantToolOutput } from "../assistant/chat/assistant-tool-output";
+import { serializeMcpToolResult } from "./_serialize-result";

 interface CreateMcpProtocolHandlerOptions {
  caller: unknown;
@@ -53,7 +54,7 @@ export const createMcpProtocolHandler = ({
                content: [
                  {
                    type: "text" as const,
-                    text: JSON.stringify(toAssistantToolOutput(result)),
+                    text: serializeMcpToolResult(toAssistantToolOutput(result)),
                  },
                ],
              };
@@ -0,0 +1,23 @@
+import { describe, expect, it } from "vitest";
+
+import { serializeMcpToolResult } from "./_serialize-result";
+
+describe("serializeMcpToolResult", () => {
+  it("serializes objects as JSON strings", () => {
+    expect(serializeMcpToolResult({ boardId: "1" })).toBe('{"boardId":"1"}');
+  });
+
+  it("serializes primitive values", () => {
+    expect(serializeMcpToolResult("hello")).toBe('"hello"');
+    expect(serializeMcpToolResult(42)).toBe("42");
+    expect(serializeMcpToolResult(true)).toBe("true");
+  });
+
+  it("serializes null as the string null", () => {
+    expect(serializeMcpToolResult(null)).toBe("null");
+  });
+
+  it("serializes void results as the string null so MCP content text is always a string", () => {
+    expect(serializeMcpToolResult(undefined)).toBe("null");
+  });
+});
@@ -0,0 +1,3 @@
+export function serializeMcpToolResult(result: unknown): string {
+  return JSON.stringify(result) ?? "null";
+}
@@ -244,7 +244,13 @@ export const WidgetContextMenu = ({
    setMenuOpened(false);
  }, []);

-  if (!session || !settings.enableRightClickOnWidgets || isEditMode || item.kind === "app") {
+  if (
+    !session ||
+    !settings.enableRightClickOnWidgets ||
+    isEditMode ||
+    item.kind === "app" ||
+    item.kind === "bookmarks"
+  ) {
    return <>{children}</>;
  }

@@ -11,6 +11,7 @@ import type { ContainerSectionItem } from "~/app/[locale]/boards/_types";
 import { COLLAPSED_SECTION_ROW_COUNT } from "~/components/board/layout";
 import { SectionGrid } from "./grid/section-grid";
 import { useSectionCollapse } from "./section-collapse";
+import { useSectionContext } from "./section-context";
 import { useOpenSectionApps } from "./use-open-section-apps";
 import classes from "./item.module.css";

@@ -25,6 +26,7 @@ interface Props {

 export const BoardContainerSection = ({ section }: Props) => {
  const board = useRequiredBoard();
+  const { section: parentSection } = useSectionContext();
  const [isEditMode] = useEditMode();
  const t = useI18n("section.container");
  const tSection = useI18n("section");
@@ -39,8 +41,26 @@ export const BoardContainerSection = ({ section }: Props) => {
  });
  const label = options.title.trim() || t("untitled");
  const contentId = `board-container-${section.id}-content`;
-  const labelLeft = 8;
-  const labelRight = isEditMode ? 48 : options.showOpenAll ? 40 : 8;
+  let labelLeft = 8;
+  let labelRight = 8;
+  if (isEditMode) {
+    // Match the root/nested menu offsets in BoardContainerMenu, plus its width and gap.
+    labelLeft = 36;
+    if (parentSection.kind === "container") labelLeft = 68;
+  } else if (options.showOpenAll) {
+    labelRight = 40;
+  }
+  // Expanded controls sit on the border like the ordinary label, without reserving a header row.
+  const toggleLayout = isVisuallyCollapsed
+    ? { top: 0, left: 0, w: "100%", h: "100%", maw: "100%" }
+    : {
+        top: "calc(var(--mantine-spacing-xs) * -1)",
+        left: labelLeft,
+        w: "auto",
+        h: 20,
+        maw: `calc(100% - ${labelLeft + labelRight}px)`,
+      };
+  const toggleIcon = isVisuallyCollapsed ? <IconChevronDown size={16} /> : <IconChevronUp size={16} />;

  return (
    <Box className="board-grid-item-content" data-grid-item-content w="100%" h="100%" style={{ overflow: "visible" }}>
@@ -68,24 +88,14 @@ export const BoardContainerSection = ({ section }: Props) => {
          <Button
            className={classes.containerToggle}
            pos="absolute"
-            top={0}
-            left={0}
-            w="100%"
-            h={isVisuallyCollapsed ? "100%" : 24}
-            px={12}
-            pe={isEditMode ? 48 : options.showOpenAll ? 40 : 12}
+            {...toggleLayout}
+            px={6}
+            ps={isVisuallyCollapsed ? labelLeft : 6}
+            pe={isVisuallyCollapsed ? labelRight : 6}
            radius="sm"
            variant="default"
            justify={options.showLabel ? "flex-start" : "center"}
-            leftSection={
-              options.showLabel ? (
-                isVisuallyCollapsed ? (
-                  <IconChevronDown size={16} />
-                ) : (
-                  <IconChevronUp size={16} />
-                )
-              ) : undefined
-            }
+            leftSection={options.showLabel && toggleIcon}
            onClick={toggle}
            aria-expanded={!isVisuallyCollapsed}
            aria-controls={contentId}
@@ -94,13 +104,7 @@ export const BoardContainerSection = ({ section }: Props) => {
            data-board-container-label
            title={options.showLabel ? label : undefined}
          >
-            {options.showLabel ? (
-              label
-            ) : isVisuallyCollapsed ? (
-              <IconChevronDown size={16} />
-            ) : (
-              <IconChevronUp size={16} />
-            )}
+            {options.showLabel ? label : toggleIcon}
          </Button>
        )}
        {!isVisuallyCollapsed && !options.collapsible && options.showLabel && options.title && (
@@ -133,6 +133,21 @@ body[data-board-grid-interacting="resize"] .board-grid-entry[data-dnd-active="tr
  background: color-mix(in srgb, var(--mantine-primary-color-filled) 10%, transparent);
 }

+.board-grid-placeholder[data-grid-placeholder-type="section"] {
+  clip-path: none;
+  background: none;
+  border: 0;
+}
+
+.board-grid-placeholder[data-grid-placeholder-type="section"]::after {
+  position: absolute;
+  inset: var(--board-container-inset, 0px);
+  content: "";
+  background: color-mix(in srgb, var(--mantine-primary-color-filled) 16%, transparent);
+  border: 2px dashed var(--mantine-primary-color-filled);
+  border-radius: inherit;
+}
+
 .board-grid-resize-outline {
  z-index: 1002;
  clip-path: inset(var(--board-grid-item-inset, 0px));
@@ -136,6 +136,7 @@ export const GridPreviewLayer = ({
      style={getLogicalItemStyle(targetPlacement)}
      data-grid-placeholder-for={interaction?.activeId}
      data-grid-placeholder-mode={interaction?.mode}
+      data-grid-placeholder-type={targetPlacement.type}
      data-grid-x={targetPlacement.x}
      data-grid-y={targetPlacement.y}
      data-grid-w={targetPlacement.w}
@@ -10,9 +10,9 @@
   while growing during a drag happening anywhere else on the board - any container (not just
   a scrollable one - a non-scrollable, e.g. collapsible, container is just as capped) sits
   inside that section's DOM tree, so the stray value cascades straight through and silently
-   defeats the `var(--board-grid-drag-height, ...px)` fallback in section-grid.tsx (including
-   its collapsibleHeaderInset adjustment), which only kicks in when the property is entirely
-   unset, not merely inherited. Reset it here so every container can never inherit a stray
+   defeats the `var(--board-grid-drag-height, ...px)` fallback in section-grid.tsx, which only
+   kicks in when the property is entirely unset, not merely inherited. Reset it here so every
+   container can never inherit a stray
   value from anywhere above it, no matter what any ancestor's own drag state is doing.
   https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_cascading_variables#custom_properties_and_inheritance */
 .viewport[data-section-kind="container"] {
@@ -62,9 +62,9 @@
  overflow: visible;
 }

-/* Containers provide their own inner item gap, so their card must keep the full grid aspect ratio. */
+/* SectionGrid fits its content to the same inset in both view and edit mode. */
 .staticItem[data-type="section"] > .contentMount {
-  inset: 0;
+  inset: var(--board-container-inset, 0px);
 }

 .staticItem[data-type="item"] > .contentMount {
@@ -1,7 +1,7 @@
 "use client";

 import type { CSSProperties, KeyboardEvent, PointerEvent } from "react";
-import { useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
+import { createContext, useContext, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
 import { Box } from "@mantine/core";
 import combineClasses from "clsx";

@@ -29,6 +29,9 @@ import { useSectionItems } from "../use-section-items";
 import { useBoardGridPortalHost } from "./grid-portal-host";
 import classes from "./section-grid.module.css";

+const GridContentScaleContext = createContext(1);
+const CONTAINER_CARD_INSET = 5;
+
 interface SectionGridProps {
  section: Exclude<Section, { kind: "container" }> | ContainerSectionItem;
  columnCount: number;
@@ -50,6 +53,7 @@ export const SectionGrid = ({
 }: SectionGridProps) => {
  const [isEditMode] = useEditMode();
  const canvasScale = useBoardCanvasScale();
+  const parentContentScale = useContext(GridContentScaleContext);
  const editorRuntimeStatus = useGridEditorRuntimeStatus();
  const editorRegistry = useGridEditorRegistry();
  const editorHostRef = useRef<HTMLDivElement>(null);
@@ -143,36 +147,37 @@ export const SectionGrid = ({
  const isScrollableContainer = section.kind === "container" && section.options.scrollable;
  const viewportRowCount =
    viewportRowCountOverride ?? (isScrollableContainer ? Math.max(requestedRowCount, 1) : rowCount);
-  const effectiveCanvasScale = Number.isFinite(canvasScale) && canvasScale > 0 ? canvasScale : 1;
-  // The collapsible label keeps a fixed physical height while the grid uses logical canvas pixels.
-  // Convert that height so the label reserves the same space at every board scale.
-  const collapsibleHeaderInset =
-    section.kind === "container" && section.options.collapsible ? CONTAINER_HEADER_HEIGHT / effectiveCanvasScale : 0;
+  const parentScale = canvasScale * parentContentScale;
+  const effectiveCanvasScale = Number.isFinite(parentScale) && parentScale > 0 ? parentScale : 1;
+  // Match the card's inset without changing its persisted grid footprint. Include ancestor
+  // container zoom so equally sized nested containers keep distinct borders at every depth.
+  let outerCardInset = 0;
+  if (section.kind === "container") {
+    outerCardInset = (2 * CONTAINER_CARD_INSET) / effectiveCanvasScale;
+  }
  const fullGridWidth = getLogicalGridSize(columnCount);
  const fullGridHeight = getLogicalGridSize(rowCount);
-  const logicalWidth = fullGridWidth;
-  const viewportHeight = Math.max(1, getLogicalGridSize(viewportRowCount) - collapsibleHeaderInset);
-  // For a scrollable container, rowCount covers *all* content rows, not just the visible card -
-  // fullGridHeight grows right along with it, so a ratio built from it drifts toward 1 as content
-  // grows regardless of the (fixed) inset, under-scaling relative to what the actually-visible
-  // viewport needs and clipping the bottom of the visible rows. viewportHeight/viewportRowCount
-  // describe the real visible card size in both cases (they equal the non-scrollable values when
-  // rowCount and viewportRowCount are the same), so use those instead.
  const fullViewportHeight = getLogicalGridSize(viewportRowCount);
-  // A collapsible container reserves a fixed-height label above the square-cell grid. Keep the
-  // nested content uniformly scaled within the remaining height so labels and icons retain their
-  // proportions; ordinary containers use the original unscaled, edge-aligned grid geometry.
-  const containerContentScale =
-    section.kind === "container" && fullGridWidth > 0 && fullViewportHeight > 0
-      ? Math.max(0.01, Math.min(logicalWidth / fullGridWidth, viewportHeight / fullViewportHeight, 1))
-      : 1;
+  const logicalWidth = Math.max(1, fullGridWidth - outerCardInset);
+  const viewportHeight = Math.max(1, fullViewportHeight - outerCardInset);
+  // Fit square cells into the inset card. Scrollable grids use the visible row count,
+  // not their full content height. Collapse controls never change this geometry.
+  let containerContentScale = 1;
+  if (section.kind === "container" && fullGridWidth > 0 && fullViewportHeight > 0) {
+    containerContentScale = Math.max(
+      0.01,
+      Math.min(logicalWidth / fullGridWidth, viewportHeight / fullViewportHeight, 1),
+    );
+  }
+  const contentScale = parentContentScale * containerContentScale;
+  const effectiveContentScale = effectiveCanvasScale * containerContentScale;
  // Compute the combined value in JS rather than a CSS calc() referencing the existing
  // --board-canvas-ui-scale: custom properties declared on the *same* element don't have a
  // sequential/temporal order the way normal variables do, so any calc() on this element that
  // both reads and writes --board-canvas-ui-scale (even indirectly, through another property)
  // is a circular reference - CSS invalidates the whole group rather than using "the old value",
  // silently breaking every icon/text/custom-CSS size that compensates off it for descendants.
-  const combinedUiScale = calculateBoardUiScale(canvasScale) / containerContentScale;
+  const combinedUiScale = calculateBoardUiScale(canvasScale) / contentScale;
  // A collapsed container's compact coordinates are display-only. Its own
  // nested grid stays inactive until an explicit edit interaction expands it.
  const isInteractionDisabled = section.kind === "container" && collapsedSectionIds.has(section.id);
@@ -268,9 +273,9 @@ export const SectionGrid = ({
          {
            width: logicalWidth,
            height: `var(--board-grid-drag-height, ${viewportHeight}px)`,
-            marginTop: collapsibleHeaderInset || undefined,
            "--board-item-radius": `var(--mantine-radius-${board.itemRadius})`,
            "--board-grid-content-scale": containerContentScale,
+            "--board-container-inset": `${CONTAINER_CARD_INSET / effectiveContentScale}px`,
          } as CSSProperties
        }
        data-section-id={section.id}
@@ -289,14 +294,17 @@ export const SectionGrid = ({
              height: fullGridHeight,
              zoom: containerContentScale,
              margin: containerContentScale < 1 ? "0 auto" : undefined,
-              ...(containerContentScale < 1 ? { "--board-canvas-ui-scale": combinedUiScale } : {}),
+              "--board-canvas-inverse-scale": 1 / effectiveContentScale,
+              "--board-canvas-ui-scale": combinedUiScale,
            } as CSSProperties
          }
          data-grid-section-id={section.id}
          data-kind={section.kind}
          data-grid-editor-error={isEditMode && editorRuntimeStatus === "error" ? "true" : undefined}
        >
-          <SectionContent />
+          <GridContentScaleContext.Provider value={contentScale}>
+            <SectionContent />
+          </GridContentScaleContext.Provider>
        </Box>
        <div ref={editorHostRef} className={classes.editorPortalHost} />
      </Box>
@@ -304,9 +312,6 @@ export const SectionGrid = ({
  );
 };

-// Matches the collapsible container toggle's h={24} in container-section.tsx.
-const CONTAINER_HEADER_HEIGHT = 24;
-
 const INTERACTIVE_GRID_SELECTOR =
  'a,button,input,textarea,select,option,[contenteditable="true"],[role="button"],[data-grid-no-drag]';
 const EDIT_ACTIVATION_KEYS = new Set(["Enter", " ", "ArrowLeft", "ArrowRight", "ArrowUp", "ArrowDown"]);
@@ -1,9 +1,10 @@
 "use client";

+import { SourceSetupPanel } from "~/components/custom-widgets/integration-source-select";
 import type { ModalProps } from "@mantine/core";

 import type { HomarrCustomWidgetV2 } from "@homarr/custom-widgets/core";
-import { CustomWidgetSourceSetupPanel, ImportReviewDialog } from "@homarr/custom-widgets/workbench";
+import { ImportReviewDialog } from "@homarr/custom-widgets/workbench";
 import { useI18n } from "@homarr/translation/client";

 import { useCustomWidgetImport } from "./use-custom-widget-import";
@@ -67,7 +68,7 @@ export function CustomWidgetImportDialog({
        confirm: legacyId ? t("importReview.confirmMigration") : (labels?.confirm ?? t("importReview.confirm")),
      }}
    >
-      <CustomWidgetSourceSetupPanel
+      <SourceSetupPanel
        setups={importer.setups}
        values={importer.values}
        onChange={importer.setValue}
@@ -1,5 +1,6 @@
 "use client";

+import { SourceSetupPanel } from "~/components/custom-widgets/integration-source-select";
 import { useRouter } from "next/navigation";
 import { useEffect, useMemo, useState } from "react";
 import { Button, Center, Group, Loader, Modal, Stack, Text } from "@mantine/core";
@@ -8,11 +9,7 @@ import { clientApi } from "@homarr/api/client";
 import { revalidatePathActionAsync } from "@homarr/common/client";
 import { getCustomWidgetSourceSetups } from "@homarr/custom-widgets/core";
 import type { CustomWidgetSecretKind } from "@homarr/custom-widgets/core";
-import {
-  createCustomWidgetSourceSetupValues,
-  CustomWidgetSourceSetupPanel,
-  isCustomWidgetSourceSetupReady,
-} from "@homarr/custom-widgets/workbench";
+import { createCustomWidgetSourceSetupValues, isCustomWidgetSourceSetupReady } from "@homarr/custom-widgets/workbench";
 import type { CustomWidgetSourceSetupMessages, CustomWidgetSourceSetupValue } from "@homarr/custom-widgets/workbench";
 import { showErrorNotification, showSuccessNotification } from "@homarr/notifications";
 import { useI18n } from "@homarr/translation/client";
@@ -68,6 +65,14 @@ export function CustomWidgetSourceSetupDialog({ definitionId, opened, onClose }:
        const secrets = Object.entries(value.secrets).flatMap(([kind, secret]) =>
          secret?.trim() ? [{ sourceId: setup.sourceId, kind: kind as CustomWidgetSecretKind, value: secret }] : [],
        );
+        if (setup.integrationKind) {
+          await configureMutation.mutateAsync({
+            definitionId,
+            sourceId: setup.sourceId,
+            integrationId: value.integrationId,
+          });
+          continue;
+        }
        await configureMutation.mutateAsync({
          definitionId,
          sourceId: setup.sourceId,
@@ -109,7 +114,7 @@ export function CustomWidgetSourceSetupDialog({ definitionId, opened, onClose }:
        </Text>
      ) : (
        <Stack gap="md">
-          <CustomWidgetSourceSetupPanel
+          <SourceSetupPanel
            setups={setups}
            values={values}
            messages={messages}
@@ -0,0 +1,81 @@
+"use client";
+
+import { Alert, Select, Stack, Text } from "@mantine/core";
+
+import { CustomWidgetSourceSetupPanel } from "@homarr/custom-widgets/workbench";
+import type { CustomWidgetSourceSetupPanelProps } from "@homarr/custom-widgets/workbench";
+
+import { clientApi } from "@homarr/api/client";
+import type { CustomWidgetIntegrationSource } from "@homarr/custom-widgets/core";
+import { integrationDefs, integrationKinds, isHttpIntegrationKind } from "@homarr/definitions";
+import { useI18n } from "@homarr/translation/client";
+
+const httpIntegrationKinds = integrationKinds.filter(isHttpIntegrationKind);
+
+interface IntegrationSourceSelectProps {
+  kind: CustomWidgetIntegrationSource["integrationKind"];
+  integrationId?: string;
+  onChange(integrationId: string | undefined): void;
+  onKindChange?(kind: CustomWidgetIntegrationSource["integrationKind"]): void;
+}
+
+export function IntegrationSourceSelect({ kind, integrationId, onChange, onKindChange }: IntegrationSourceSelectProps) {
+  const t = useI18n("customWidget.workbench.sources");
+  const query = clientApi.integration.all.useQuery();
+  const integrations = (query.data ?? []).filter(
+    (integration) => integration.kind === kind && integration.permissions.hasFullAccess,
+  );
+  const unavailable = Boolean(integrationId && query.isSuccess && !integrations.some(({ id }) => id === integrationId));
+  return (
+    <Stack gap="sm">
+      {onKindChange && (
+        <Select
+          label={t("integrationType")}
+          searchable
+          data={httpIntegrationKinds.map((value) => ({ value, label: integrationDefs[value].name }))}
+          value={kind}
+          allowDeselect={false}
+          onChange={(value) => {
+            const selected = httpIntegrationKinds.find((candidate) => candidate === value);
+            if (selected) onKindChange(selected);
+          }}
+        />
+      )}
+      <Select
+        label={t("selectIntegration")}
+        description={isHttpIntegrationKind(kind) ? integrationDefs[kind].name : kind}
+        data={integrations.map(({ id, name }) => ({ value: id, label: name }))}
+        value={integrationId ?? null}
+        searchable
+        clearable
+        disabled={query.isPending}
+        nothingFoundMessage={t("noIntegrations")}
+        error={unavailable && t("integrationUnavailable")}
+        onChange={(value) => onChange(value ?? undefined)}
+      />
+      {query.error && <Alert color="red">{query.error.message}</Alert>}
+      <Text size="xs" c="dimmed">
+        {t("integrationDescription")}
+      </Text>
+    </Stack>
+  );
+}
+
+export function SourceSetupPanel(props: CustomWidgetSourceSetupPanelProps) {
+  return (
+    <CustomWidgetSourceSetupPanel
+      {...props}
+      renderIntegrationSource={(setup, value) => {
+        const kind = httpIntegrationKinds.find((candidate) => candidate === setup.integrationKind);
+        if (!kind) return null;
+        return (
+          <IntegrationSourceSelect
+            kind={kind}
+            integrationId={value.integrationId}
+            onChange={(integrationId) => props.onChange(setup.sourceId, { ...value, integrationId })}
+          />
+        );
+      }}
+    />
+  );
+}
@@ -60,7 +60,7 @@ export function useCustomWidgetImport({ widget, legacyId, onImported }: UseCusto
        Object.fromEntries(
          Object.entries(values).map(([sourceId, value]) => [
            sourceId,
-            { baseUrl: value.baseUrl, networkScope: value.networkScope },
+            { baseUrl: value.baseUrl, networkScope: value.networkScope, integrationId: value.integrationId },
          ]),
        ),
      ),
@@ -1,5 +1,5 @@
 interface PublishableWorkshopDefinition {
-  sources: Record<string, { name?: string; networkScope: string }>;
+  sources: Record<string, { name?: string; networkScope?: string }>;
 }

 export const serializeWorkshopDefinition = (definition: unknown): string => {
@@ -29,5 +29,5 @@ export async function publishWorkshopDefinition({

 export const getPrivateWorkshopSourceNames = (definition: PublishableWorkshopDefinition | undefined) =>
  Object.entries(definition?.sources ?? {}).flatMap(([sourceId, source]) =>
-    source.networkScope === "public" ? [] : [source.name ?? sourceId],
+    source.networkScope === undefined || source.networkScope === "public" ? [] : [source.name ?? sourceId],
  );
@@ -9,7 +9,7 @@ http {

        # Route websockets traffic to port 3001
        location /websockets {
-            proxy_pass http://${HOSTNAME}:3001;
+            proxy_pass http://127.0.0.1:3001;
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection "Upgrade";
@@ -18,7 +18,7 @@ http {

        # Route all other traffic to port 3000
        location / {
-            proxy_pass http://${HOSTNAME}:3000;
+            proxy_pass http://127.0.0.1:3000;
            proxy_set_header Host $http_host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
@@ -5,3 +5,5 @@ export {
  serializeCustomWidgetDefinition,
 } from "./router/custom-widget/stored-definition";
 export { configureCustomWidgetSourceFromRequest } from "./router/custom-widget/secret-persistence";
+
+export { assertCustomWidgetIntegrationBindings } from "./router/custom-widget/source-resolver";
@@ -1,3 +1,4 @@
+import { assertCustomWidgetIntegrationBindings } from "./source-resolver";
 import { TRPCError } from "@trpc/server";
 import { z } from "zod/v4";

@@ -44,6 +45,7 @@ export const creationProcedures = {
    .mutation(async ({ ctx, input }) => {
      const { secrets, ...candidate } = input;
      const definition = parseCustomWidgetAuthoringInput(() => normalizeCustomWidgetAuthoringDefinition(candidate));
+      await assertCustomWidgetIntegrationBindings(ctx, definition.sources);
      assertSecretSources(definition.sources, secrets);
      const id = await insertCustomWidgetDefinition(ctx.db, definition, ctx.session.user.id, secrets);
      logger.info("Created custom widget definition", { id, name: definition.name });
@@ -115,6 +117,7 @@ export const creationProcedures = {
      const secrets = Object.keys(session.sources).flatMap((sourceId) =>
        getPreviewSessionSecrets(session, sourceId).map((secret) => ({ sourceId, ...secret })),
      );
+      await assertCustomWidgetIntegrationBindings(ctx, definition.sources);
      assertSecretSources(definition.sources, secrets);
      const id = await insertCustomWidgetDefinition(ctx.db, definition, ctx.session.user.id, secrets);
      logger.info("Created custom widget definition from tested preview", {
@@ -1,3 +1,5 @@
+import { assertCustomWidgetIntegrationBindings } from "./source-resolver";
+import { getCustomWidgetSourceAuthType } from "@homarr/custom-widgets/core";
 import { TRPCError } from "@trpc/server";
 import { z } from "zod/v4";

@@ -60,6 +62,7 @@ export const customWidgetRouter = createTRPCRouter({
        const changes = normalizeCustomWidgetAuthoringUpdate(authoringChanges);
        return customWidgetDefinitionSchema.parse({ ...current, ...changes });
      });
+      await assertCustomWidgetIntegrationBindings(ctx, definition.sources);
      if (secrets) assertSecretSources(definition.sources, secrets);
      const definitionChanges = { ...serializeCustomWidgetDefinition(definition), updatedAt: new Date() };
      const secretRows = secrets?.map((secret) => ({
@@ -106,7 +109,7 @@ export const customWidgetRouter = createTRPCRouter({
            }

            for (const [sourceId, source] of Object.entries(definition.sources)) {
-              const kinds = [...requiredSecretKinds(typeof source.auth === "string" ? source.auth : source.auth.type)];
+              const kinds = [...requiredSecretKinds(getCustomWidgetSourceAuthType(source))];
              const where = and(
                eq(schema.customWidgetSecrets.definitionId, id),
                eq(schema.customWidgetSecrets.sourceId, sourceId),
@@ -151,7 +154,7 @@ export const customWidgetRouter = createTRPCRouter({
            }

            for (const [sourceId, source] of Object.entries(definition.sources)) {
-              const kinds = [...requiredSecretKinds(typeof source.auth === "string" ? source.auth : source.auth.type)];
+              const kinds = [...requiredSecretKinds(getCustomWidgetSourceAuthType(source))];
              const where = and(eq(customWidgetSecrets.definitionId, id), eq(customWidgetSecrets.sourceId, sourceId));
              transaction
                .delete(customWidgetSecrets)
@@ -1,3 +1,4 @@
+import { resolveCustomWidgetSource } from "./source-resolver";
 import { TRPCError } from "@trpc/server";
 import { z } from "zod/v4";

@@ -153,31 +154,19 @@ export const managementQueryProcedures = {
      });
      try {
        const values = resolveOptionRequestValues(request, input.params);
-        const authType = typeof source.auth === "string" ? source.auth : source.auth.type;
+        const connection = await resolveCustomWidgetSource(ctx, source, request, () =>
+          stored.secrets
+            .filter((secret) => secret.sourceId === request.source)
+            .map((secret) => ({ kind: secret.kind, value: decryptSecret(secret.encryptedValue) })),
+        );
        const response = await executeCustomWidgetRequest({
-          baseUrl: source.baseUrl,
-          targetUrl: renderRequestTarget(source.baseUrl, request, values),
+          ...connection,
+          targetUrl: renderRequestTarget(connection.baseUrl, request, values),
          method: request.method,
          body: renderRequestBody(request, values),
          staticHeaders: request.headers,
-          auth:
-            request.auth === "none" || authType === "none"
-              ? undefined
-              : {
-                  type: authType,
-                  secrets: stored.secrets
-                    .filter((secret) => secret.sourceId === request.source)
-                    .map((secret) => ({ kind: secret.kind, value: decryptSecret(secret.encryptedValue) })),
-                  headerName:
-                    typeof source.auth === "object" && source.auth.type === "apiKeyHeader"
-                      ? source.auth.name
-                      : typeof source.auth === "object" && source.auth.type === "apiKeyQuery"
-                        ? source.auth.name
-                        : undefined,
-                },
-          networkScope: source.networkScope,
          kind: "query",
-          cacheKey: `custom-widget:options:${input.definitionId}:${getCustomWidgetCacheVersion(stored)}:${request.id}:${hashRuntimeParams(values)}`,
+          cacheKey: `custom-widget:options:${input.definitionId}:${getCustomWidgetCacheVersion(stored)}:${request.id}:${hashRuntimeParams(values)}:${connection.cacheVersion}`,
          cacheTtlSeconds: request.cacheSeconds ?? 30,
        });
        return {
@@ -1,3 +1,4 @@
+import { getCustomWidgetSourceAuthType } from "@homarr/custom-widgets/core";
 import type { InferSelectModel } from "drizzle-orm";

 import { createLogger } from "@homarr/core/infrastructure/logs";
@@ -50,12 +51,12 @@ export function mapCustomWidgetListItem(definition: StoredDefinition & { secrets
    name: widget.name,
    description: widget.description,
    iconUrl: widget.iconUrl,
-    sources: Object.entries(widget.sources).map(([id, { name, baseUrl, networkScope, auth }]) => ({
+    sources: Object.entries(widget.sources).map(([id, source]) => ({
      id,
-      name,
-      origin: new URL(baseUrl).origin,
-      networkScope,
-      authType: typeof auth === "string" ? auth : auth.type,
+      name: source.name,
+      origin: source.type === "integration" ? source.integrationKind : new URL(source.baseUrl).origin,
+      networkScope: source.networkScope,
+      authType: source.type === "integration" ? "integration" : getCustomWidgetSourceAuthType(source),
    })),
    requestCount: Object.keys(widget.requests).length,
    missingSecrets: getCustomWidgetSecretRequirements(widget.sources).filter(
@@ -110,11 +111,11 @@ export function mapAvailableCustomWidget(definition: StoredDefinition) {
      options: widget.options,
      defaultOptions: getCustomWidgetDefaultOptions(widget.options),
      template: widget.template,
-      sources: Object.entries(widget.sources).map(([id, { name, networkScope, auth }]) => ({
+      sources: Object.entries(widget.sources).map(([id, source]) => ({
        id,
-        name,
-        networkScope,
-        authType: typeof auth === "string" ? auth : auth.type,
+        name: source.name,
+        networkScope: source.networkScope,
+        authType: source.type === "integration" ? "integration" : getCustomWidgetSourceAuthType(source),
      })),
      requestCapabilities: Object.entries(widget.requests).map(
        ([id, { kind, method, trigger, permission, confirmation, invalidates }]) => ({
@@ -29,10 +29,10 @@ export const previewActionProcedures = {
      if (definition?.kind !== "action")
        throw new TRPCError({ code: "NOT_FOUND", message: "Preview action was not found" });
      const request = { id: input.requestId, ...definition };
-      const resolved = getPreviewRequestSource(session, request.source);
+      const resolved = await getPreviewRequestSource(ctx, session, request);
      if (!resolved) throw new TRPCError({ code: "NOT_FOUND", message: "Preview source was not found" });
      const params = resolveCustomWidgetRequestValues(request, session.options, input.params);
-      const targetUrl = renderRequestTarget(resolved.source.baseUrl, request, params);
+      const targetUrl = renderRequestTarget(resolved.baseUrl, request, params);
      const body = renderRequestBody(request, params);
      if (!session.liveActions) {
        await recordPreviewJournal(session, {
@@ -66,13 +66,12 @@ export const previewActionProcedures = {
      const startedAt = Date.now();
      try {
        const response = await executeCustomWidgetRequest({
-          baseUrl: resolved.source.baseUrl,
+          ...resolved,
          targetUrl,
          method: request.method,
          body,
          staticHeaders: request.headers,
          auth: request.auth === "none" ? undefined : resolved.auth,
-          networkScope: resolved.source.networkScope,
          kind: "action",
        });
        if (response.ok && request.invalidates?.length) {
@@ -1,3 +1,5 @@
+import { assertCustomWidgetIntegrationBindings } from "./source-resolver";
+import { getCustomWidgetSourceAuthType } from "@homarr/custom-widgets/core";
 import { TRPCError } from "@trpc/server";
 import { z } from "zod/v4";

@@ -92,6 +94,7 @@ const previewCreateProcedure = permissionRequiredProcedure
    const definition = parseCustomWidgetAuthoringInput(() =>
      normalizeCustomWidgetAuthoringDefinition(input.definition),
    );
+    await assertCustomWidgetIntegrationBindings(ctx, definition.sources);
    const options = input.options ?? getCustomWidgetDefaultOptions(definition.options);
    const optionIssues = validateCustomWidgetOptions(definition.options, options);
    if (optionIssues.length > 0) {
@@ -115,7 +118,7 @@ const previewCreateProcedure = permissionRequiredProcedure
        const hasStoredSecrets = existing.secrets.some((secret) => secret.sourceId === sourceId);
        if (!submittedSource || !hasStoredSecrets || hasSameSecretBinding(existingSource, submittedSource)) continue;

-        const authType = typeof submittedSource.auth === "string" ? submittedSource.auth : submittedSource.auth.type;
+        const authType = getCustomWidgetSourceAuthType(submittedSource);
        const missingReplacement = requiredSecretKinds(authType).some(
          (kind) => !secrets.some((secret) => secret.sourceId === sourceId && secret.kind === kind),
        );
@@ -142,7 +145,7 @@ const previewCreateProcedure = permissionRequiredProcedure

    const invalid = secrets.find((secret) => {
      const source = definition.sources[secret.sourceId];
-      const authType = typeof source?.auth === "string" ? source.auth : source?.auth.type;
+      const authType = getCustomWidgetSourceAuthType(source);
      const kinds =
        authType === "basic"
          ? ["username", "password"]
@@ -1,3 +1,4 @@
+import { resolveCustomWidgetSource } from "./source-resolver";
 import { createLogger } from "@homarr/core/infrastructure/logs";
 import type { CustomJsxRequest } from "@homarr/custom-widgets/core";
 import { z } from "zod/v4";
@@ -33,25 +34,15 @@ export const recordPreviewJournal = async (...args: Parameters<typeof appendPrev
  }
 };

-export const getPreviewRequestSource = (session: CustomWidgetPreviewSession, sourceId: string) => {
-  const source = session.sources[sourceId];
+export async function getPreviewRequestSource(
+  ctx: Parameters<typeof resolveCustomWidgetSource>[0],
+  session: CustomWidgetPreviewSession,
+  request: CustomJsxRequest,
+) {
+  const source = session.sources[request.source];
  if (!source) return null;
-  const authType = typeof source.auth === "string" ? source.auth : source.auth.type;
-  const auth =
-    authType === "none"
-      ? undefined
-      : {
-          type: authType,
-          secrets: getPreviewSessionSecrets(session, sourceId),
-          headerName:
-            typeof source.auth === "object" && source.auth.type === "apiKeyHeader"
-              ? source.auth.name
-              : typeof source.auth === "object" && source.auth.type === "apiKeyQuery"
-                ? source.auth.name
-                : undefined,
-        };
-  return { source, auth };
-};
+  return resolveCustomWidgetSource(ctx, source, request, () => getPreviewSessionSecrets(session, request.source));
+}

 export function resolvePreviewRequestParams(
  request: CustomJsxRequest,
@@ -38,10 +38,10 @@ export const previewQueryProcedures = {
      if (definition?.kind !== "query")
        throw new TRPCError({ code: "NOT_FOUND", message: "Preview query was not found" });
      const request = { id: input.requestId, ...definition };
-      const resolved = getPreviewRequestSource(session, request.source);
+      const resolved = await getPreviewRequestSource(ctx, session, request);
      if (!resolved) throw new TRPCError({ code: "NOT_FOUND", message: "Preview source was not found" });
      const params = resolvePreviewRequestParams(request, session.options, input.params);
-      const targetUrl = renderRequestTarget(resolved.source.baseUrl, request, params);
+      const targetUrl = renderRequestTarget(resolved.baseUrl, request, params);
      const body = renderRequestBody(request, params);
      const release = await acquireCustomWidgetRequestLimit({
        category: "query",
@@ -52,15 +52,14 @@ export const previewQueryProcedures = {
      const startedAt = Date.now();
      try {
        const response = await executeCustomWidgetRequest({
-          baseUrl: resolved.source.baseUrl,
+          ...resolved,
          targetUrl,
          method: request.method,
          body,
          staticHeaders: request.headers,
          auth: request.auth === "none" ? undefined : resolved.auth,
-          networkScope: resolved.source.networkScope,
          kind: "query",
-          cacheKey: `custom-jsx:preview:${session.id}:${request.id}:${hashRuntimeParams(params)}`,
+          cacheKey: `custom-jsx:preview:${session.id}:${request.id}:${hashRuntimeParams(params)}:${resolved.cacheVersion}`,
          cacheTtlSeconds: request.cacheSeconds,
        });
        await recordPreviewJournal(session, {
@@ -15,7 +15,8 @@ type CustomWidgetSecretInput = CustomWidgetCreateInput["secrets"][number];
 type ConfigureCustomWidgetSourceInput = {
  definitionId: string;
  sourceId: string;
-  baseUrl: string;
+  baseUrl?: string;
+  integrationId?: string;
  networkScope?: CustomWidgetSource["networkScope"];
  secrets: CustomWidgetCreateInput["secrets"];
  expectedSource?: CustomWidgetSource;
@@ -220,11 +221,17 @@ function prepareSourceUpdate(
  if (input.expectedSource && !hasSameCustomWidgetSourceAuthentication(previousSource, input.expectedSource)) {
    throw new SourceConfigurationError("binding-changed");
  }
-  const source = customWidgetSourceSchema.parse({
-    ...previousSource,
-    baseUrl: input.baseUrl,
-    networkScope: input.networkScope ?? previousSource.networkScope,
-  });
+  let configuration: unknown;
+  if (previousSource.type === "integration") {
+    configuration = { ...previousSource, integrationId: input.integrationId };
+  } else {
+    configuration = {
+      ...previousSource,
+      baseUrl: input.baseUrl,
+      networkScope: input.networkScope ?? previousSource.networkScope,
+    };
+  }
+  const source = customWidgetSourceSchema.parse(configuration);
  assertSecretSources({ [input.sourceId]: source }, input.secrets);
  return {
    source,
@@ -16,6 +16,7 @@ export function requiredSecretKinds(authType: string) {
 * origin, while the network scope and auth destination are part of the binding.
 */
 export function hasSameSecretBinding(left: CustomWidgetSource, right: CustomWidgetSource) {
+  if (left.type === "integration" || right.type === "integration") return false;
  return (
    new URL(left.baseUrl).origin === new URL(right.baseUrl).origin &&
    left.networkScope === right.networkScope &&
@@ -24,12 +25,12 @@ export function hasSameSecretBinding(left: CustomWidgetSource, right: CustomWidg
 }

 export function assertSecretSources(
-  sources: Record<string, { auth: string | { type: string } }>,
+  sources: Record<string, { auth?: string | { type: string }; type?: string }>,
  secrets: readonly { sourceId: string; kind: "apiKey" | "username" | "password" }[],
 ) {
  const invalid = secrets.find((secret) => {
    const source = sources[secret.sourceId];
-    const authType = typeof source?.auth === "string" ? source.auth : source?.auth.type;
+    const authType = typeof source?.auth === "string" ? source.auth : source?.auth?.type;
    return !source || !authType || !new Set<string>(requiredSecretKinds(authType)).has(secret.kind);
  });
  if (invalid) {
@@ -1,3 +1,5 @@
+import { assertCustomWidgetIntegrationBindings } from "./source-resolver";
+import { getCustomWidgetSourceAuthType } from "@homarr/custom-widgets/core";
 import { TRPCError } from "@trpc/server";
 import { z } from "zod/v4";

@@ -58,12 +60,19 @@ export const secretProcedures = {

  sourceConfigure: permissionRequiredProcedure
    .requiresPermission("admin")
-    .meta({ mcp: { enabled: true, description: "Configure one custom widget API source and its credentials." } })
+    .meta({
+      mcp: {
+        enabled: true,
+        description:
+          "Configure one custom widget source. For an integration source, provide integrationId from integration_all (matching integrationKind); omit URL and secrets. Requires administrator permission.",
+      },
+    })
    .input(
      z.object({
        definitionId: z.string(),
        sourceId: z.string(),
-        baseUrl: z.string(),
+        baseUrl: z.string().optional(),
+        integrationId: z.string().min(1).max(100).optional(),
        networkScope: z.enum(["public", "private", "loopback"]).optional(),
        secrets: customWidgetSecretsInputSchema.default([]),
      }),
@@ -76,22 +85,34 @@ export const secretProcedures = {
      const definition = parseStoredCustomWidgetDefinition(stored);
      const current = definition.sources[input.sourceId];
      if (!current) throw new TRPCError({ code: "NOT_FOUND", message: "Widget source not found" });
-      const source = customWidgetSourceSchema.parse({
-        ...current,
-        baseUrl: input.baseUrl,
-        networkScope: input.networkScope ?? current.networkScope,
-      });
+      let configuration: unknown;
+      if (current.type === "integration") {
+        if (
+          !input.integrationId ||
+          input.baseUrl !== undefined ||
+          input.networkScope !== undefined ||
+          input.secrets.length > 0
+        ) {
+          throw new TRPCError({ code: "BAD_REQUEST", message: "Integration sources require only an integrationId" });
+        }
+        configuration = { ...current, integrationId: input.integrationId };
+      } else {
+        if (input.integrationId)
+          throw new TRPCError({ code: "BAD_REQUEST", message: "HTTP sources cannot bind an integration" });
+        configuration = {
+          ...current,
+          baseUrl: input.baseUrl,
+          networkScope: input.networkScope ?? current.networkScope,
+        };
+      }
+      const source = customWidgetSourceSchema.parse(configuration);
+      await assertCustomWidgetIntegrationBindings(ctx, { [input.sourceId]: source });
      assertSecretSources({ [input.sourceId]: source }, input.secrets);
-      const configuredSource = await configureCustomWidgetSource(ctx.db, {
-        definitionId: input.definitionId,
-        sourceId: input.sourceId,
-        baseUrl: source.baseUrl,
-        networkScope: input.networkScope,
-        secrets: input.secrets,
-      });
+      const configuredSource = await configureCustomWidgetSource(ctx.db, { ...input, expectedSource: current });
      return {
        definitionId: input.definitionId,
        sourceId: input.sourceId,
+        integrationId: configuredSource.integrationId,
        baseUrl: configuredSource.baseUrl,
        networkScope: configuredSource.networkScope,
        configuredSecrets: input.secrets.map(({ kind }) => kind),
@@ -110,7 +131,7 @@ export const secretProcedures = {
      }

      let widgetName: string;
-      let source: { id: string; name: string; auth: string | { type: string }; value: CustomWidgetSource } | undefined;
+      let source: { id: string; name: string; auth: CustomWidgetSource["auth"]; value: CustomWidgetSource } | undefined;
      let target: { type: "definition"; id: string } | { type: "preview"; id: string };
      if (input.definitionId) {
        const stored = await ctx.db.query.customWidgetDefinitions.findFirst({
@@ -144,7 +165,7 @@ export const secretProcedures = {
        target = { type: "preview", id: preview.id };
      }
      if (!source) throw new TRPCError({ code: "NOT_FOUND", message: "Widget source not found" });
-      const kinds = [...requiredSecretKinds(typeof source.auth === "string" ? source.auth : source.auth.type)];
+      const kinds = [...requiredSecretKinds(getCustomWidgetSourceAuthType(source))];
      const request = await createCustomWidgetConfigurationRequest({
        userId: ctx.session.user.id,
        target,
@@ -0,0 +1,85 @@
+import { TRPCError } from "@trpc/server";
+
+import type { CustomJsxRequest, CustomWidgetSource } from "@homarr/custom-widgets/core";
+import { getCustomWidgetSourceAuthType } from "@homarr/custom-widgets/core";
+import type { CustomWidgetHttpRequest } from "@homarr/custom-widgets/server";
+import { isHttpIntegrationKind } from "@homarr/definitions";
+
+import type { IntegrationHttpContext } from "../integration/integration-http";
+import {
+  getIntegrationForHttpRequest,
+  getIntegrationHttpCacheVersion,
+  getIntegrationHttpConnection,
+} from "../integration/integration-http";
+
+export async function assertCustomWidgetIntegrationBindings(
+  ctx: IntegrationHttpContext,
+  sources: Record<string, CustomWidgetSource>,
+) {
+  for (const source of Object.values(sources)) {
+    if (source.type !== "integration" || !source.integrationId) continue;
+    await resolveIntegration(ctx, source);
+  }
+}
+
+async function resolveIntegration(
+  ctx: IntegrationHttpContext,
+  source: Extract<CustomWidgetSource, { type: "integration" }>,
+) {
+  if (!source.integrationId) {
+    throw new TRPCError({
+      code: "PRECONDITION_FAILED",
+      message: "Select an existing integration for this widget source",
+    });
+  }
+  const integration = await getIntegrationForHttpRequest(ctx, source.integrationId);
+  if (!isHttpIntegrationKind(integration.kind) || integration.kind !== source.integrationKind) {
+    throw new TRPCError({
+      code: "PRECONDITION_FAILED",
+      message: "The selected integration is unavailable or has a different type",
+    });
+  }
+  return integration;
+}
+
+export async function resolveCustomWidgetSource(
+  ctx: IntegrationHttpContext,
+  source: CustomWidgetSource,
+  request: Pick<CustomJsxRequest, "kind" | "method" | "auth">,
+  getSecrets: () => Array<{ kind: string; value: string }>,
+): Promise<
+  Pick<
+    CustomWidgetHttpRequest,
+    "baseUrl" | "networkScope" | "auth" | "tls" | "pathPrefix" | "redactSecrets" | "resolveConnectionAsync"
+  > & {
+    cacheVersion: string;
+  }
+> {
+  if (source.type !== "integration") {
+    const authType = getCustomWidgetSourceAuthType(source);
+    let auth: CustomWidgetHttpRequest["auth"];
+    if (request.auth !== "none" && authType !== "none") {
+      auth = { type: authType, secrets: getSecrets() };
+      if (typeof source.auth === "object") auth.headerName = source.auth.name;
+    }
+    return { baseUrl: source.baseUrl, networkScope: source.networkScope, auth, cacheVersion: "" };
+  }
+  const integration = await resolveIntegration(ctx, source);
+  return getIntegrationHttpConnection(integration, request.auth !== "none");
+}
+
+export async function getCustomWidgetIntegrationCacheVersions(
+  ctx: IntegrationHttpContext,
+  sources: Record<string, CustomWidgetSource>,
+) {
+  return Promise.all(
+    Object.entries(sources).flatMap(([sourceId, source]) => {
+      if (source.type !== "integration") return [];
+      return [
+        resolveIntegration(ctx, source)
+          .then((integration) => `${sourceId}:${getIntegrationHttpCacheVersion(integration)}`)
+          .catch(() => `${sourceId}:unavailable`),
+      ];
+    }),
+  );
+}
@@ -1,3 +1,5 @@
+import { exportCustomWidgetDefinition } from "@homarr/custom-widgets/core";
+import { assertCustomWidgetIntegrationBindings } from "./source-resolver";
 import { TRPCError } from "@trpc/server";
 import { parse as parseSuperJson } from "superjson";
 import { z } from "zod/v4";
@@ -24,7 +26,7 @@ export const transferProcedures = {
        where: eq(customWidgetDefinitions.id, input.id),
      });
      if (!definition) throw new TRPCError({ code: "NOT_FOUND" });
-      return parseStoredCustomWidgetDefinition(definition);
+      return exportCustomWidgetDefinition(parseStoredCustomWidgetDefinition(definition));
    }),

  exportLegacy: permissionRequiredProcedure
@@ -57,6 +59,7 @@ export const transferProcedures = {
    .requiresPermission("admin")
    .input(z.object({ widget: customWidgetImportSchema, secrets: customWidgetSecretsInputSchema.default([]) }))
    .mutation(async ({ ctx, input }) => {
+      await assertCustomWidgetIntegrationBindings(ctx, input.widget.sources);
      assertSecretSources(input.widget.sources, input.secrets);
      const id = await insertCustomWidgetDefinition(ctx.db, input.widget, ctx.session.user.id, input.secrets);
      logger.info("Imported custom widget definition", { id, name: input.widget.name });
@@ -80,6 +83,7 @@ export const transferProcedures = {
      }),
    )
    .mutation(async ({ ctx, input }) => {
+      await assertCustomWidgetIntegrationBindings(ctx, input.widget.sources);
      assertSecretSources(input.widget.sources, input.secrets);
      const [legacy, current] = await Promise.all([
        ctx.db.query.legacyCustomWidgetDefinitions.findFirst({
@@ -157,7 +161,7 @@ function canPreserveLegacySecrets(
  widget: z.infer<typeof customWidgetImportSchema>,
 ) {
  const source = widget.sources.default;
-  if (!source || getAuthType(source.auth) !== legacy.authType) return false;
+  if (!source || source.type === "integration" || getAuthType(source.auth) !== legacy.authType) return false;
  if (getOrigin(source.baseUrl) !== getOrigin(legacy.url)) return false;
  const headerName = typeof source.auth === "object" && "name" in source.auth ? source.auth.name : undefined;
  return headerName === (legacy.headerName ?? undefined);
@@ -1,3 +1,5 @@
+import { exportCustomWidgetDefinition } from "@homarr/custom-widgets/core";
+import { assertCustomWidgetIntegrationBindings } from "./source-resolver";
 import { TRPCError } from "@trpc/server";
 import { z } from "zod/v4";

@@ -56,7 +58,7 @@ async function getWorkshopWidget(submissionId: string) {
    if (!validation.success) {
      throw new TRPCError({ code: "BAD_REQUEST", message: validation.error });
    }
-    return { submission, widget: validation.data };
+    return { submission, widget: exportCustomWidgetDefinition(validation.data) };
  } catch (error) {
    if (error instanceof TRPCError) throw error;
    throwWorkshopUnavailable("Workshop widget lookup failed", "workshop_widget_lookup_failed");
@@ -72,7 +74,8 @@ const workshopSearchInputSchema = z.object({
 const sourceOverridesSchema = z.record(
  customWidgetIdentifierSchema,
  z.strictObject({
-    baseUrl: z.string(),
+    baseUrl: z.string().optional(),
+    integrationId: z.string().min(1).max(100).optional(),
    networkScope: z.enum(["public", "private", "loopback"]).optional(),
  }),
 );
@@ -165,12 +168,14 @@ export const workshopProcedures = {
              sourceId,
              {
                baseUrl: source.baseUrl,
+                integrationId: source.integrationId,
                networkScope: source.networkScope ?? widget.sources[sourceId]?.networkScope ?? "public",
              },
            ]),
          ),
        ),
      });
+      await assertCustomWidgetIntegrationBindings(ctx, configured.sources);
      assertSecretSources(configured.sources, input.secrets);
      const id = await insertCustomWidgetDefinition(ctx.db, configured, ctx.session.user.id, input.secrets);
      const configuredSecrets = new Set(input.secrets.map((secret) => `${secret.sourceId}:${secret.kind}`));
@@ -0,0 +1,126 @@
+import { createHash } from "node:crypto";
+import { TRPCError } from "@trpc/server";
+
+import type { Session } from "@homarr/auth";
+import { constructIntegrationPermissions } from "@homarr/auth/shared";
+import { decryptSecret } from "@homarr/common/server";
+import {
+  getAllTrustedCertificatesAsync,
+  getTrustedCertificateHostnamesAsync,
+} from "@homarr/core/infrastructure/certificates";
+import { createCustomCheckServerIdentity } from "@homarr/core/infrastructure/http";
+import { CustomWidgetDomainError } from "@homarr/custom-widgets/server";
+import type { CustomWidgetAuthConfig, CustomWidgetHttpRequest } from "@homarr/custom-widgets/server";
+import type { Database } from "@homarr/db";
+import { eq, inArray } from "@homarr/db";
+import { groupMembers, integrations, integrationGroupPermissions, integrationUserPermissions } from "@homarr/db/schema";
+import { getIntegrationHttpAuthenticationAsync } from "@homarr/integrations/factory";
+import type { IntegrationHttpAuthentication } from "@homarr/integrations/factory";
+
+export interface IntegrationHttpContext {
+  db: Database;
+  session: Session | null;
+}
+
+export async function getIntegrationForHttpRequest(ctx: IntegrationHttpContext, integrationId: string) {
+  const userId = ctx.session?.user.id ?? "";
+  const groups = await ctx.db.query.groupMembers.findMany({ where: eq(groupMembers.userId, userId) });
+  const integration = await ctx.db.query.integrations.findFirst({
+    where: eq(integrations.id, integrationId),
+    with: {
+      secrets: true,
+      userPermissions: { where: eq(integrationUserPermissions.userId, userId) },
+      groupPermissions: {
+        where: inArray(integrationGroupPermissions.groupId, groups.map(({ groupId }) => groupId).concat("")),
+      },
+    },
+  });
+  // An arbitrary read can expose service credentials or perform a mutation. Native
+  // integration use/interact permissions authorize only Homarr's bounded operations.
+  if (!integration || !constructIntegrationPermissions(integration, ctx.session).hasFullAccess) {
+    throw new TRPCError({
+      code: "FORBIDDEN",
+      message: "Arbitrary integration requests require full integration access",
+    });
+  }
+  return integration;
+}
+
+type HttpIntegration = Awaited<ReturnType<typeof getIntegrationForHttpRequest>>;
+
+export function getIntegrationHttpCacheVersion(integration: HttpIntegration) {
+  return createHash("sha256")
+    .update(JSON.stringify([integration.id, integration.kind, integration.url, integration.secrets]))
+    .digest("hex")
+    .slice(0, 16);
+}
+
+export async function getIntegrationHttpConnection(integration: HttpIntegration, authenticate = true) {
+  try {
+    const secrets = integration.secrets.map(({ kind, value }) => ({ kind, value: decryptSecret(value) }));
+    let baseUrl = integration.url;
+    if (integration.kind === "ical") baseUrl = secrets.find(({ kind }) => kind === "url")?.value ?? "";
+    return {
+      baseUrl,
+      networkScope: "loopback" as const,
+      pathPrefix: new URL(baseUrl).pathname,
+      redactSecrets: secrets,
+      cacheVersion: getIntegrationHttpCacheVersion(integration),
+      resolveConnectionAsync: async () => {
+        try {
+          let authentication: IntegrationHttpAuthentication = {};
+          if (authenticate) {
+            authentication = await getIntegrationHttpAuthenticationAsync({
+              ...integration,
+              externalUrl: null,
+              decryptedSecrets: secrets,
+            });
+          }
+          const auth = toWidgetAuth(authentication, secrets);
+          const url = new URL(authentication.baseUrl ?? baseUrl);
+          let tls: CustomWidgetHttpRequest["tls"];
+          if (url.protocol === "https:") {
+            const [ca, hostnames] = await Promise.all([
+              getAllTrustedCertificatesAsync(),
+              getTrustedCertificateHostnamesAsync(),
+            ]);
+            tls = { ca, checkServerIdentity: createCustomCheckServerIdentity(hostnames) };
+          }
+          return { baseUrl: url.href, auth, tls, pathPrefix: url.pathname, redactSecrets: auth.secrets };
+        } catch {
+          throw new CustomWidgetDomainError({
+            code: "BAD_GATEWAY",
+            message: "Integration connection could not be resolved",
+          });
+        }
+      },
+    };
+  } catch {
+    throw new TRPCError({ code: "PRECONDITION_FAILED", message: "Integration connection could not be resolved" });
+  }
+}
+
+function toWidgetAuth(
+  authentication: IntegrationHttpAuthentication,
+  secrets: CustomWidgetAuthConfig["secrets"],
+): CustomWidgetAuthConfig {
+  const authSecrets = [...secrets, ...(authentication.redactValues ?? []).map((value) => ({ kind: "session", value }))];
+  const refresh = authentication.refreshAsync;
+  return {
+    ...authentication,
+    type: "integration",
+    secrets: authSecrets,
+    refreshAsync:
+      refresh &&
+      (async () => {
+        try {
+          return toWidgetAuth(await refresh(), secrets);
+        } catch {
+          throw new CustomWidgetDomainError({
+            code: "BAD_GATEWAY",
+            message: "Integration session could not be refreshed",
+          });
+        }
+      }),
+  };
+}
@@ -42,7 +42,8 @@ if (!jellyfin) throw new Error("Jellyfin bundled widget is missing");
 const pokedex = BUNDLED_CUSTOM_WIDGETS.find(({ id }) => id === "seed-pokedex")?.widget;
 if (!pokedex) throw new Error("Pokédex bundled widget is missing");
 const jellyfinDefaultSource = jellyfin.sources.default;
-if (!jellyfinDefaultSource) throw new Error("Jellyfin default source is missing");
+if (!jellyfinDefaultSource || jellyfinDefaultSource.type === "integration")
+  throw new Error("Jellyfin default source is missing");

 function createCaller(db: ReturnType<typeof createDb>) {
  return customWidgetRouter.createCaller({ db, deviceType: undefined, session });
@@ -181,7 +182,7 @@ describe("custom widget definition persistence", () => {
    }

    const defaultSource = previewSession.sources.default;
-    if (!defaultSource) throw new Error("Pokédex preview source is missing");
+    if (!defaultSource || defaultSource.type === "integration") throw new Error("Pokédex preview source is missing");
    await configurePreviewSessionSource(previewSession.id, userId, "default", { ...defaultSource }, []);
    await expect(caller.createFromPreview(createInput)).rejects.toThrow("Test every final preview query successfully");

@@ -675,7 +676,7 @@ describe("custom widget definition persistence", () => {
    const created = await createCaller(db).create({ ...jellyfin, secrets: [secret] });
    const definition = customWidgetDefinitionSchema.parse(jellyfin);
    const defaultSource = definition.sources.default;
-    if (!defaultSource) throw new Error("Jellyfin default source is missing");
+    if (!defaultSource || defaultSource.type === "integration") throw new Error("Jellyfin default source is missing");
    await db
      .update(customWidgetDefinitions)
      .set(
@@ -720,7 +721,7 @@ describe("custom widget definition persistence", () => {
    const created = await createCaller(db).create({ ...jellyfin, secrets: [] });
    const definition = customWidgetDefinitionSchema.parse(jellyfin);
    const expectedSource = definition.sources.default;
-    if (!expectedSource || typeof expectedSource.auth === "string") {
+    if (!expectedSource || expectedSource.type === "integration" || typeof expectedSource.auth === "string") {
      throw new Error("Jellyfin default source must use header authentication");
    }
    await db
@@ -1,3 +1,4 @@
+import { getCustomWidgetIntegrationCacheVersions, resolveCustomWidgetSource } from "../custom-widget/source-resolver";
 import { TRPCError } from "@trpc/server";
 import { parse as parseSuperJson } from "superjson";
 import { z } from "zod/v4";
@@ -13,7 +14,7 @@ import {
  normalizeCustomWidgetOptions,
  validateCustomWidgetOptions,
 } from "@homarr/custom-widgets/core";
-import type { CustomJsxRequest, CustomWidgetSource } from "@homarr/custom-widgets/core";
+import type { CustomJsxRequest } from "@homarr/custom-widgets/core";

 import { createTRPCRouter, protectedProcedure, publicProcedure } from "../../trpc";
 import { throwIfActionForbiddenAsync } from "../board/board-access";
@@ -121,25 +122,6 @@ const findSource = (resolved: ResolvedDefinition, sourceId: string) => {
 };

 type IdentifiedRequest = CustomJsxRequest & { id: string };
-type IdentifiedSource = CustomWidgetSource & { id: string };
-
-const getAuth = (resolved: ResolvedDefinition, source: IdentifiedSource, mode: "inherit" | "none") => {
-  const authType = typeof source.auth === "string" ? source.auth : source.auth.type;
-  if (mode === "none" || authType === "none") return undefined;
-  const secrets = resolved.stored.secrets
-    .filter((secret) => secret.sourceId === source.id)
-    .map((secret) => ({ kind: secret.kind, value: decryptSecret(secret.encryptedValue) }));
-  return {
-    type: authType,
-    secrets,
-    headerName:
-      typeof source.auth === "object" && source.auth.type === "apiKeyHeader"
-        ? source.auth.name
-        : typeof source.auth === "object" && source.auth.type === "apiKeyQuery"
-          ? source.auth.name
-          : undefined,
-  };
-};

 const withRequestLimit = async <T>(
  ctx: RouterContext,
@@ -172,21 +154,26 @@ const executeRequest = async (
  await throwIfActionForbiddenAsync(ctx, eq(boards.id, resolved.item.boardId), request.permission as BoardPermission);
  const source = findSource(resolved, request.source);
  const values = resolveCustomWidgetRequestValues(request, resolved.configuration, params);
-  const targetUrl = renderRequestTarget(source.baseUrl, request, values);
-  return withRequestLimit(ctx, resolved, request, () =>
+  const connection = await resolveCustomWidgetSource(ctx, source, request, () =>
+    resolved.stored.secrets
+      .filter((secret) => secret.sourceId === source.id)
+      .map((secret) => ({ kind: secret.kind, value: decryptSecret(secret.encryptedValue) })),
+  );
+  const targetUrl = renderRequestTarget(connection.baseUrl, request, values);
+  const response = await withRequestLimit(ctx, resolved, request, () =>
    executeCustomWidgetRequest({
-      baseUrl: source.baseUrl,
+      ...connection,
      targetUrl,
      method: request.method,
      body: renderRequestBody(request, values),
      staticHeaders: request.headers,
-      auth: getAuth(resolved, source, request.auth),
-      networkScope: source.networkScope,
      kind: request.kind,
-      cacheKey: request.kind === "query" ? getCacheKey(resolved, request, values) : undefined,
+      cacheKey:
+        request.kind === "query" ? `${getCacheKey(resolved, request, values)}:${connection.cacheVersion}` : undefined,
      cacheTtlSeconds: request.cacheSeconds,
    }),
  );
+  return response;
 };

 export const customApiRouter = createTRPCRouter({
@@ -199,6 +186,7 @@ export const customApiRouter = createTRPCRouter({

  getData: publicProcedure.input(itemInputSchema).query(async ({ ctx, input }) => {
    const resolved = await resolvePlacedDefinitionAsync(ctx, input.itemId);
+    const integrationVersions = await getCustomWidgetIntegrationCacheVersions(ctx, resolved.definition.sources);
    const loadRequests = Object.entries(resolved.definition.requests).filter(
      ([, request]) => request.kind === "query" && request.trigger === "load",
    );
@@ -239,7 +227,7 @@ export const customApiRouter = createTRPCRouter({
    return {
      type: "customJsx" as const,
      template: resolved.definition.template,
-      queryCacheKey: `${getCustomWidgetCacheVersion(resolved.stored)}:${hashRuntimeParams(resolved.configuration)}`,
+      queryCacheKey: `${getCustomWidgetCacheVersion(resolved.stored)}:${hashRuntimeParams(resolved.configuration)}:${integrationVersions.join(":")}`,
      data: Object.fromEntries(entries.map(([id, result]) => [id, result.data])),
      status: Object.fromEntries(entries.map(([id, result]) => [id, result.status])),
      options: resolved.configuration,
@@ -43,7 +43,7 @@ async function importCookiesAsync() {

 function getBaseUrl() {
  if (typeof window !== "undefined") return window.location.origin;
-  return `http://${process.env.HOSTNAME ?? "localhost"}:3000`;
+  return "http://127.0.0.1:3000";
 }

 export const trpcPath = "/api/trpc";
@@ -14,7 +14,6 @@ import { UndiciHttpAgent } from "@homarr/core/infrastructure/http";

 import type { TrustedCertificateHostname } from "../certificates/hostnames";
 import { withTimeoutAsync } from "./timeout";
-
 export const createCustomCheckServerIdentity = (
  trustedHostnames: TrustedCertificateHostname[],
 ): typeof checkServerIdentity => {
@@ -1,3 +1,4 @@
+import { getCustomWidgetSourceAuthType } from "../src/core/request-schema";
 import { mkdir, writeFile } from "node:fs/promises";
 import path from "node:path";

@@ -279,7 +280,7 @@ export function getDeterministicEvaluationIssues(
      message: `Use the verified source URL ${expectations.sourceBaseUrl}.`,
    });
  }
-  const authType = typeof source?.auth === "string" ? source.auth : source?.auth.type;
+  const authType = getCustomWidgetSourceAuthType(source);
  if (authType !== expectations.sourceAuth) {
    issues.push({
      path: ["sources", "default", "auth"],
@@ -467,7 +468,7 @@ const getJudgeRuntimeContext = (widget: HomarrCustomWidgetV2) => {
  const sections = [getCustomWidgetSkillReference("runtime").content];
  const hasMutation = Object.values(widget.requests).some((request) => request.kind === "action");
  const hasProtectedSource = Object.values(widget.sources).some((source) => {
-    const authType = typeof source.auth === "string" ? source.auth : source.auth.type;
+    const authType = getCustomWidgetSourceAuthType(source);
    return authType !== "none";
  });
  if (hasMutation || hasProtectedSource) sections.push(getCustomWidgetSkillReference("security").content);
@@ -72,6 +72,8 @@ ${leanShape}

 Sources are keyed by name and must include "default". Auth is "none", "bearer", "basic", {"type":"apiKeyHeader","name":"X-Api-Key"}, or {"type":"apiKeyQuery","name":"api_key"}. Use the stable public API URL for public services and a clear suggested URL for self-hosted services; Homarr asks the installer for their own server URL. Never put credentials in the manifest.

+Supported existing integrations use {"type":"integration","integrationKind":"sonarr"} as a source, without baseUrl, networkScope, or auth. The installer selects their local integration. An MCP author can use integration_all to obtain a matching integrationId for preview/create. Integration URLs and credentials resolve server-side; exports remove integrationId. All integration calls require full integration access. Integration methods other than GET must be manual actions.
+
 Requests are keyed by ID. Defaults are source "default", kind "query", method "GET", query trigger "load", inherited auth, and permission "view" for queries or "modify" for actions. Actions are always manual. DELETE is valid only for actions, requires full permission, and receives confirmation automatically. Use {option:name} or {"$option":"name"} for saved options. Use {param:name} or {"$param":"name"} only for invocation-time params supplied by SubFetch, ActionButton, or ToggleSwitch. Load queries cannot use params. Values and primitive types are inferred from references; do not declare parameters or option bindings. Paths and query values must be primitive; JSON bodies may bind structured options.

 Options are keyed by name. Every option has label, control, and default. Controls: text, textarea, number, switch, select, multiSelect, slider, date, time, color, icon, url, duration, timeZone, json. Select choices use \`"choices": [{"label":"...","value":"..."}]\`. Dynamic choices must use \`"choicesFrom": {"request":"requestId","itemsPath":"optional.path","valuePath":"id","labelPath":"name"}\`, never an object under \`choices\`. Options are configured outside the widget and read through \`options.name\`; a bound control writes only to \`inputs.name\` and never changes an option.
@@ -13,7 +13,7 @@ export const CUSTOM_WIDGET_SKILL_SOURCE_URL =
  "https://github.com/homarr-labs/homarr/tree/HEAD/.agents/skills/homarr-custom-widget";
 export const CUSTOM_WIDGET_SKILL_INSTALL_COMMAND =
  "npx skills add https://github.com/homarr-labs/homarr --skill homarr-custom-widget";
-export const CUSTOM_WIDGET_SKILL_VERSION = "2.9.0";
+export const CUSTOM_WIDGET_SKILL_VERSION = "2.10.0";
 export const CUSTOM_WIDGET_SKILL_REFERENCE_NAMES = ["schema", "runtime", "security"] as const;
 export type CustomWidgetSkillReferenceName = (typeof CUSTOM_WIDGET_SKILL_REFERENCE_NAMES)[number];

@@ -58,7 +58,7 @@ interface HomarrCustomWidgetV2 {
 }
 \`\`\`

-The object key \`default\` is the required source ID; \`default\` is not a property on a source. Source properties are \`name?\`, \`baseUrl\`, \`networkScope\`, and \`auth?\`:
+\`sources.default\` is required. HTTP source properties: \`name?\`, \`baseUrl\`, \`networkScope\`, and \`auth?\`:

 \`\`\`json
 {
@@ -85,14 +85,17 @@ The object key \`default\` is the required source ID; \`default\` is not a prope
 }
 \`\`\`

-Auth is \`none\`, \`bearer\`, \`basic\`, \`{ "type": "apiKeyHeader", "name": "X-Api-Key" }\`, or \`{ "type": "apiKeyQuery", "name": "api_key" }\`. A request defaults to source \`default\`, kind \`query\`, method \`GET\`, trigger \`load\`, inherited auth, and view permission. Set \`trigger: "manual"\` for a parameterized query. An action defaults to manual and modify permission. DELETE uses full permission and confirmation. Do not use \`load: false\`.
+Integration sources use \`{"type":"integration","integrationKind":"sonarr"}\`. Bind \`integrationId\` from \`integration_all\`; exports omit it. Calls require full integration access. Omit URL/auth fields. Paths append to the integration URL; non-GET requests must be actions.

-Use stable real URLs for public APIs and clear suggested URLs for self-hosted services. Homarr collects the installer's server URL, network scope, and credentials as source setup; credentials remain outside the manifest.
+Auth: \`none\`, \`bearer\`, \`basic\`, \`{ "type": "apiKeyHeader", "name": "X-Api-Key" }\`, or \`{ "type": "apiKeyQuery", "name": "api_key" }\`. Requests default to source \`default\`, kind \`query\`, method \`GET\`, trigger \`load\`, inherited auth, and view permission. Parameterized queries need \`trigger: "manual"\`. Actions default to manual/modify; DELETE requires full permission and confirmation. Do not use \`load: false\`.

-Paths use \`{option:name}\` and \`{param:name}\`; query/body references use \`{ "$option": "name" }\` and \`{ "$param": "name" }\`. Constants stay primitive (\`take: 10\`); \`$param\` is only for manual helpers, never load queries. Names and types are inferred.
+HTTP sources declare public URLs or self-hosted suggestions; installers configure their URL, network scope, and credentials separately.

-Every option has \`label\`, \`control\`, and \`default\`. Optional fields are \`description\`, \`choices\`, \`choicesFrom\`, \`min\`, \`max\`, \`step\`, \`advanced\`, and \`group\`.
+Paths bind \`{option:name}\` and \`{param:name}\`; query/body references bind \`{ "$option": "name" }\` and \`{ "$param": "name" }\`. Use primitive constants (\`take: 10\`). \`$param\` is only for manual requests.
+
+Options require \`label\`, \`control\`, and \`default\`. Optional fields: \`description\`, \`choices\`, \`choicesFrom\`, \`min\`, \`max\`, \`step\`, \`advanced\`, \`group\`.
 `,
+
  "references/runtime.md": `# Runtime

 Templates read \`data.requestId\`, \`status.requestId\`, \`options.name\`, and temporary \`inputs.name\`. Status is \`{ loading, ok, status, statusText, error }\`. Render load queries directly from \`data\` and \`status\` with \`RefreshButton\`; never wrap them in \`SubFetch\`.
@@ -104,6 +104,17 @@ type Definition = z.infer<typeof customWidgetDefinitionSchema>;

 function validateRequests(definition: Definition, ctx: z.RefinementCtx) {
  for (const [requestId, request] of Object.entries(definition.requests)) {
+    if (
+      definition.sources[request.source]?.type === "integration" &&
+      request.method !== "GET" &&
+      request.kind !== "action"
+    ) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["requests", requestId, "kind"],
+        message: "Integration requests with a method other than GET must be manual actions",
+      });
+    }
    if (!definition.sources[request.source]) {
      ctx.addIssue({
        code: "custom",
@@ -1,3 +1,4 @@
+import { getCustomWidgetSourceAuthType } from "./request-schema";
 import type { HomarrCustomWidgetV2 } from "./custom-jsx-schema";
 import { customWidgetImportSchema } from "./custom-jsx-schema";

@@ -104,7 +105,7 @@ export function parseCustomWidgetClipboardDetailed(text: string): CustomWidgetPa
  if (removedIssues.length > 0) return { success: false, issues: removedIssues };
  const parsed = customWidgetImportSchema.safeParse(widget);
  if (!parsed.success) return { success: false, issues: zodIssues(parsed.error) };
-  return { success: true, widget: parsed.data, warnings: [] };
+  return { success: true, widget: exportCustomWidgetDefinition(parsed.data), warnings: [] };
 }

 export function parseCustomWidgetAiResponse(text: string): CustomWidgetParseResult {
@@ -157,17 +158,35 @@ export function getImportReview(value: unknown): ImportReview | null {
  const widget = parsed.data;
  return {
    name: widget.name,
-    origins: Object.values(widget.sources).map((source) => new URL(source.baseUrl).origin),
+    origins: Object.values(widget.sources).map((source) =>
+      source.type === "integration" ? source.integrationKind : new URL(source.baseUrl).origin,
+    ),
    authTypes: [
      ...new Set(
        Object.values(widget.sources).map((source) =>
-          typeof source.auth === "string" ? source.auth : source.auth.type,
+          source.type === "integration" ? "integration" : getCustomWidgetSourceAuthType(source),
        ),
      ),
    ],
-    networkScopes: [...new Set(Object.values(widget.sources).map((source) => source.networkScope))],
+    networkScopes: [
+      ...new Set(Object.values(widget.sources).flatMap((source) => (source.networkScope ? [source.networkScope] : []))),
+    ],
    methods: [...new Set(Object.values(widget.requests).map((request) => request.method))],
    permissions: [...new Set(Object.values(widget.requests).map((request) => request.permission))],
    hasActions: Object.values(widget.requests).some((request) => request.kind === "action"),
  };
 }
+
+/** Deployment bindings never travel with an exported or published widget. */
+export function exportCustomWidgetDefinition(widget: HomarrCustomWidgetV2): HomarrCustomWidgetV2 {
+  return {
+    ...widget,
+    sources: Object.fromEntries(
+      Object.entries(widget.sources).map(([id, source]) => {
+        if (source.type !== "integration") return [id, source];
+        const { integrationId: _localBinding, ...portable } = source;
+        return [id, portable];
+      }),
+    ),
+  };
+}
@@ -41,7 +41,10 @@ const sourceUrlIssueMessages: Record<CustomWidgetSourceUrlIssue, string> = {
  queryOrFragment: "API source URLs cannot contain a query string or fragment",
 };

-export const customWidgetSourceSchema = z.strictObject({
+export const customWidgetHttpSourceSchema = z.strictObject({
+  type: z.literal("http").optional(),
+  integrationKind: z.never().optional(),
+  integrationId: z.never().optional(),
  name: z.string().trim().min(1).max(128).optional(),
  baseUrl: z
    .string()
@@ -54,7 +57,25 @@ export const customWidgetSourceSchema = z.strictObject({
  networkScope: z.enum(customJsxNetworkScopes),
  auth: authSchema.default("none"),
 });
+export const customWidgetIntegrationSourceSchema = z.strictObject({
+  type: z.literal("integration"),
+  name: z.string().trim().min(1).max(128).optional(),
+  integrationKind: customWidgetIdentifierSchema,
+  integrationId: z.string().min(1).max(100).optional(),
+  baseUrl: z.never().optional(),
+  networkScope: z.never().optional(),
+  auth: z.never().optional(),
+});
+export const customWidgetSourceSchema = z.union([customWidgetHttpSourceSchema, customWidgetIntegrationSourceSchema]);
 export type CustomWidgetSource = z.infer<typeof customWidgetSourceSchema>;
+export type CustomWidgetHttpSource = z.infer<typeof customWidgetHttpSourceSchema>;
+export type CustomWidgetIntegrationSource = z.infer<typeof customWidgetIntegrationSourceSchema>;
+
+export function getCustomWidgetSourceAuthType(source: { auth?: CustomWidgetHttpSource["auth"] } | undefined) {
+  if (!source?.auth) return "none" as const;
+  if (typeof source.auth === "string") return source.auth;
+  return source.auth.type;
+}

 export const customWidgetSourcesSchema = z
  .record(customWidgetIdentifierSchema, customWidgetSourceSchema)
@@ -1,3 +1,4 @@
+import { getCustomWidgetSourceAuthType } from "./request-schema";
 import type { CustomWidgetSource } from "./request-schema";
 import type { CustomWidgetSecretKind } from "./schema-types";

@@ -21,7 +22,7 @@ export function getCustomWidgetSecretRequirements(
  sources: Record<string, CustomWidgetSource>,
 ): CustomWidgetSecretRequirement[] {
  return Object.entries(sources).flatMap(([sourceId, source]) => {
-    const authType = typeof source.auth === "string" ? source.auth : source.auth.type;
+    const authType = getCustomWidgetSourceAuthType(source);
    return getCustomWidgetRequiredSecretKinds(authType).map((kind) => ({
      sourceId,
      sourceName: source.name ?? sourceId,
@@ -1,4 +1,5 @@
-import type { CustomWidgetSource } from "./request-schema";
+import { getCustomWidgetSourceAuthType } from "./request-schema";
+import type { CustomJsxNetworkScope, CustomWidgetSource } from "./request-schema";
 import { getCustomWidgetSourceUrlIssue } from "./request-schema";
 import type { CustomWidgetSecretKind } from "./schema-types";
 import { getCustomWidgetSecretRequirements } from "./secret-requirements";
@@ -15,7 +16,9 @@ export interface CustomWidgetSourceSetup {
  sourceName: string;
  suggestedBaseUrl: string;
  baseUrl: string;
-  networkScope: CustomWidgetSource["networkScope"];
+  networkScope: CustomJsxNetworkScope;
+  integrationKind?: string;
+  integrationId?: string;
  authType: "none" | "bearer" | "basic" | "apiKeyHeader" | "apiKeyQuery";
  credentialFields: Array<{
    kind: CustomWidgetSecretKind;
@@ -40,10 +43,18 @@ export function isCustomWidgetSourceUrlPlaceholder(baseUrl: string) {
 }

 export function customWidgetSourceRequiresUrlConfirmation(source: CustomWidgetSource) {
+  if (source.type === "integration") return !source.integrationId;
  return source.networkScope !== "public" || isCustomWidgetSourceUrlPlaceholder(source.baseUrl);
 }

 export function hasSameCustomWidgetSourceAuthentication(left: CustomWidgetSource, right: CustomWidgetSource) {
+  if (left.type === "integration" || right.type === "integration") {
+    return (
+      left.type === right.type &&
+      left.integrationKind === right.integrationKind &&
+      left.integrationId === right.integrationId
+    );
+  }
  if (typeof left.auth === "string" || typeof right.auth === "string") return left.auth === right.auth;
  return left.auth.type === right.auth.type && left.auth.name === right.auth.name;
 }
@@ -54,13 +65,15 @@ export function getCustomWidgetSourceSetups(
 ): CustomWidgetSourceSetup[] {
  const requirements = getCustomWidgetSecretRequirements(sources);
  return Object.entries(sources).map(([sourceId, source]) => {
-    const authType = typeof source.auth === "string" ? source.auth : source.auth.type;
+    const authType = getCustomWidgetSourceAuthType(source);
    return {
      sourceId,
      sourceName: source.name ?? sourceId,
-      suggestedBaseUrl: source.baseUrl,
-      baseUrl: source.baseUrl,
-      networkScope: source.networkScope,
+      suggestedBaseUrl: source.baseUrl ?? "",
+      baseUrl: source.baseUrl ?? "",
+      networkScope: source.networkScope ?? "private",
+      integrationKind: source.integrationKind,
+      integrationId: source.integrationId,
      authType,
      credentialFields: requirements
        .filter((requirement) => requirement.sourceId === sourceId)
@@ -81,12 +94,23 @@ export function getCustomWidgetSourceSetups(

 export function applyCustomWidgetSourceSetup(
  sources: Record<string, CustomWidgetSource>,
-  setup: Record<string, Pick<CustomWidgetSource, "baseUrl" | "networkScope">>,
+  setup: Record<string, { baseUrl?: string; networkScope?: CustomJsxNetworkScope; integrationId?: string }>,
 ) {
  return Object.fromEntries(
    Object.entries(sources).map(([sourceId, source]) => {
      const configured = setup[sourceId];
-      return [sourceId, configured ? { ...source, ...configured } : source];
+      if (!configured) return [sourceId, source];
+      if (source.type === "integration") {
+        return [sourceId, { ...source, integrationId: configured.integrationId }];
+      }
+      return [
+        sourceId,
+        {
+          ...source,
+          baseUrl: configured.baseUrl ?? source.baseUrl,
+          networkScope: configured.networkScope ?? source.networkScope,
+        },
+      ];
    }),
  );
 }
@@ -1,3 +1,6 @@
+import type { CustomWidgetHttpRequest, CustomWidgetHttpResponse } from "./request-types";
+import { assertCustomWidgetPathScope, resolveSameOriginTarget } from "./network-policy";
+
 type HeaderSetter = Pick<Headers, "set">;

 export const AUTH_HANDLERS: Record<
@@ -43,3 +46,54 @@ export function applyAuth(
    handler(headers, url, secretMap.apiKey, headerName ?? undefined);
  }
 }
+
+export async function performAuthenticatedRequest(
+  input: CustomWidgetHttpRequest,
+  signal: AbortSignal,
+  perform: (input: CustomWidgetHttpRequest, signal: AbortSignal) => Promise<CustomWidgetHttpResponse>,
+): Promise<CustomWidgetHttpResponse> {
+  const target = resolveSameOriginTarget(input.baseUrl, input.targetUrl);
+  if (input.pathPrefix !== undefined) assertCustomWidgetPathScope(target, input.pathPrefix);
+  if (input.resolveConnectionAsync) {
+    const connection = await withinDeadline(input.resolveConnectionAsync, signal);
+    const base = new URL(connection.baseUrl);
+    target.protocol = base.protocol;
+    target.host = base.host;
+    input = { ...input, ...connection, targetUrl: target };
+  }
+  let response = await perform(input, signal);
+  if (!isExpired(input, response)) return response;
+  response.ok = false;
+  response.status = 401;
+  response.statusText = "Integration session expired";
+  if (!input.auth?.refreshAsync) return response;
+  const auth = await withinDeadline(input.auth.refreshAsync, signal);
+  // An action may have reached the service. Refresh for its next explicit invocation.
+  if (input.kind === "action") return response;
+  input = { ...input, auth };
+  response = await perform(input, signal);
+  if (isExpired(input, response)) {
+    response.ok = false;
+    response.status = 401;
+    response.statusText = "Integration session expired";
+  }
+  return response;
+}
+
+function isExpired(input: CustomWidgetHttpRequest, response: CustomWidgetHttpResponse) {
+  return input.auth && (response.status === 401 || input.auth.isExpired?.(response));
+}
+
+async function withinDeadline<T>(callback: () => Promise<T>, signal: AbortSignal): Promise<T> {
+  signal.throwIfAborted();
+  let abort: (() => void) | undefined;
+  const aborted = new Promise<never>((_resolve, reject) => {
+    abort = () => reject(signal.reason);
+    signal.addEventListener("abort", abort, { once: true });
+  });
+  try {
+    return await Promise.race([callback(), aborted]);
+  } finally {
+    if (abort) signal.removeEventListener("abort", abort);
+  }
+}
@@ -39,3 +39,7 @@ export {
  resolveCustomWidgetRequestValues,
 } from "./request-manifest";
 export type { CustomJsxRuntimeParams } from "./request-manifest";
+
+export { redactResponseSecrets } from "./response";
+
+export { assertCustomWidgetPathScope } from "./network-policy";
@@ -1,4 +1,5 @@
 import { lookup } from "node:dns/promises";
+import type { ConnectionOptions } from "node:tls";
 import { BlockList, isIP } from "node:net";
 import type { LookupFunction } from "node:net";
 import { Agent } from "undici";
@@ -191,7 +192,11 @@ export function assertSafeStaticHeaders(headers: Record<string, string> | undefi
  }
 }

-export function createPinnedAgent(addresses: ResolvedAddress[], timeoutMs: number) {
+export function createPinnedAgent(
+  addresses: ResolvedAddress[],
+  timeoutMs: number,
+  tls?: Pick<ConnectionOptions, "ca" | "checkServerIdentity">,
+) {
  const customLookup: LookupFunction = (_hostname, options, callback) => {
    const family = options.family === 4 || options.family === 6 ? options.family : undefined;
    const candidates = family ? addresses.filter((entry) => entry.family === family) : addresses;
@@ -204,10 +209,42 @@ export function createPinnedAgent(addresses: ResolvedAddress[], timeoutMs: numbe
    else callback(null, selected.address, selected.family);
  };
  return new Agent({
-    connect: { lookup: customLookup },
+    connect: { ...tls, lookup: customLookup },
    connectTimeout: timeoutMs,
    headersTimeout: timeoutMs,
    bodyTimeout: timeoutMs,
    maxResponseSize: MAX_RESPONSE_BODY_BYTES,
  });
 }
+
+export function assertCustomWidgetPathScope(url: URL, pathPrefix: string) {
+  const prefix = decodePath(pathPrefix).replace(/\/+$/u, "");
+  const path = decodePath(url.pathname);
+  if (
+    path.includes("\\") ||
+    path.split("/").some((segment) => segment === "." || segment === "..") ||
+    (prefix && path !== prefix && !path.startsWith(`${prefix}/`))
+  ) {
+    throw new CustomWidgetDomainError({
+      code: "FORBIDDEN",
+      message: "Request must remain within the selected integration URL",
+    });
+  }
+}
+
+function decodePath(value: string) {
+  let path = value;
+  for (let pass = 0; pass < 4; pass += 1) {
+    let decoded: string;
+    try {
+      decoded = decodeURIComponent(path);
+    } catch {
+      return path;
+    }
+    if (decoded === path) return path;
+    path = decoded;
+  }
+  if (/%[0-9a-f]{2}/iu.test(path))
+    throw new CustomWidgetDomainError({ code: "FORBIDDEN", message: "Request path is excessively encoded" });
+  return path;
+}
@@ -1,3 +1,4 @@
+import { hasSameCustomWidgetSourceAuthentication } from "../core";
 import { customWidgetDefinitionSchema } from "../core";
 import type { CustomJsxRequest, CustomWidgetOptions, CustomWidgetSource } from "../core";
 import { CustomWidgetDomainError } from "./errors";
@@ -36,3 +37,9 @@ export function validatePreviewTemplateRevision(current: PreviewTemplateContext,
  }
  return parsed.data.template;
 }
+
+export function canConfigurePreviewSource(current: CustomWidgetSource, source: CustomWidgetSource) {
+  if (current.type === "integration" && source.type === "integration")
+    return current.integrationKind === source.integrationKind;
+  return hasSameCustomWidgetSourceAuthentication(current, source);
+}
@@ -1,3 +1,4 @@
+import { canConfigurePreviewSource } from "./preview-session-template";
 import { z } from "zod/v4";

 import {
@@ -5,7 +6,6 @@ import {
  customWidgetRequestsSchema,
  customWidgetSecretKinds,
  customWidgetSourcesSchema,
-  hasSameCustomWidgetSourceAuthentication,
 } from "../core";
 import type { CustomJsxRequest, CustomWidgetOptions, CustomWidgetSource } from "../core";
 import { CustomWidgetDomainError } from "./errors";
@@ -242,7 +242,7 @@ export class CustomWidgetPreviewSessionService {
      if (!currentSource) {
        throw new CustomWidgetDomainError({ code: "NOT_FOUND", message: "Preview source was not found" });
      }
-      if (!hasSameCustomWidgetSourceAuthentication(currentSource, source)) {
+      if (!canConfigurePreviewSource(currentSource, source)) {
        throw new CustomWidgetDomainError({
          code: "BAD_REQUEST",
          message: "Preview source authentication changed; create a new configuration request",
@@ -253,7 +253,7 @@ export class CustomWidgetPreviewSessionService {
        ...session,
        sources: {
          ...session.sources,
-          [sourceId]: { ...currentSource, baseUrl: source.baseUrl, networkScope: source.networkScope },
+          [sourceId]: source,
        },
        secrets: [
          ...session.secrets.filter((secret) => !replacements.has(`${secret.sourceId}:${secret.kind}`)),
@@ -2,11 +2,13 @@ import { Buffer } from "node:buffer";
 import { STATUS_CODES } from "node:http";
 import { Headers, Response } from "undici";

-import type { CustomJsxNetworkScope, CustomWidgetMethod } from "../core";
-import { applyAuth } from "./auth";
+import type { CustomWidgetHttpRequest, CustomWidgetHttpResponse } from "./request-types";
+export type { CustomWidgetAuthConfig, CustomWidgetHttpRequest, CustomWidgetHttpResponse } from "./request-types";
+import { applyAuth, performAuthenticatedRequest } from "./auth";
 import { CustomWidgetDomainError } from "./errors";
 import {
  assertSafeStaticHeaders,
+  assertCustomWidgetPathScope,
  createPinnedAgent,
  resolveAndValidateHost,
  resolveSameOriginTarget,
@@ -14,6 +16,7 @@ import {
 } from "./network-policy";
 import { closeDispatcher } from "./request-dispatcher-lifecycle";
 import { parseResponseBody } from "./response";
+import { redactResponseSecrets } from "./response";

 export {
  assertSafeStaticHeaders,
@@ -37,32 +40,6 @@ export const MAX_REQUEST_DURATION_MS = 45_000;
 const TIMEOUT_ERROR_CODES = new Set(["UND_ERR_CONNECT_TIMEOUT", "UND_ERR_HEADERS_TIMEOUT", "UND_ERR_BODY_TIMEOUT"]);
 const RESPONSE_TOO_LARGE_ERROR_CODE = "UND_ERR_RES_EXCEEDED_MAX_SIZE";

-export interface CustomWidgetAuthConfig {
-  type: string;
-  secrets: Array<{ kind: string; value: string }>;
-  headerName?: string | null;
-}
-
-export interface CustomWidgetHttpRequest {
-  baseUrl: string;
-  targetUrl?: string | URL;
-  method: CustomWidgetMethod;
-  body?: string;
-  staticHeaders?: Record<string, string>;
-  auth?: CustomWidgetAuthConfig;
-  networkScope: CustomJsxNetworkScope;
-  kind: "query" | "action";
-  cacheKey?: string;
-  cacheTtlSeconds?: number;
-  logError?: (event: { origin: string; method: CustomWidgetMethod; errorName: string; reason?: "timeout" }) => void;
-}
-
-export interface CustomWidgetHttpResponse {
-  ok: boolean;
-  status: number;
-  statusText: string;
-  data: unknown;
-}
 const cache = new Map<string, { expiresAt: number; response: CustomWidgetHttpResponse }>();
 const inFlight = new Map<string, Promise<CustomWidgetHttpResponse>>();
 let cacheEpoch = 0;
@@ -75,7 +52,8 @@ async function performRequest(input: CustomWidgetHttpRequest): Promise<CustomWid
  const controller = new AbortController();
  const timeout = setTimeout(() => controller.abort(), MAX_REQUEST_DURATION_MS);
  try {
-    return await performRequestWithinDeadline(input, controller.signal);
+    assertRequest(input);
+    return await performAuthenticatedRequest(input, controller.signal, performRequestWithinDeadline);
  } catch (error) {
    if (controller.signal.aborted) {
      throw new CustomWidgetDomainError({
@@ -107,12 +85,17 @@ async function performRequestWithinDeadline(
  const baseUrl = validateCustomWidgetUrl(input.baseUrl);
  let currentUrl = resolveSameOriginTarget(input.baseUrl, input.targetUrl);
  let currentMethod = input.method;
-  let currentBody = input.body;
+  let currentBody = input.auth?.transformBody ? input.auth.transformBody(input.body) : input.body;
+  assertRequest({ ...input, body: currentBody });
  const maxRedirects = input.kind === "query" ? MAX_QUERY_REDIRECTS : 0;
  for (let redirects = 0; ; redirects += 1) {
+    input.auth?.transformUrl?.(currentUrl);
+    resolveSameOriginTarget(input.baseUrl, currentUrl);
+    if (input.pathPrefix !== undefined) assertCustomWidgetPathScope(currentUrl, input.pathPrefix);
    const dispatcher = createPinnedAgent(
      await resolveAndValidateHost(currentUrl.hostname, input.networkScope, { signal: deadlineSignal }),
      REQUEST_TIMEOUT_MS,
+      input.tls,
    );
    const headers = buildHeaders(input, currentUrl, currentBody);
    const controller = new AbortController();
@@ -135,15 +118,22 @@ async function performRequestWithinDeadline(
          statusText: STATUS_CODES[responseData.statusCode] ?? "",
          headers: normalizeResponseHeaders(responseData.headers),
        });
-        result = {
-          kind: "response",
-          response: {
-            ok: response.ok,
-            status: response.status,
-            statusText: response.statusText,
-            data: await parseResponseBody(response),
-          },
+        const parsed = {
+          ok: response.ok,
+          status: response.status,
+          statusText: response.statusText,
+          data: await parseResponseBody(response),
        };
+        if (input.auth?.isExpired?.(parsed)) {
+          parsed.ok = false;
+          parsed.status = 401;
+          parsed.statusText = "Integration session expired";
+        }
+        parsed.data = redactResponseSecrets(parsed.data, [
+          ...(input.redactSecrets ?? []),
+          ...(input.auth?.secrets ?? []),
+        ]);
+        result = { kind: "response", response: parsed };
      } else {
        await responseData.body.dump();
        result = {
@@ -248,6 +238,8 @@ function buildHeaders(input: CustomWidgetHttpRequest, url: URL, body: string | u
  if (input.auth) {
    if (input.auth.type === "apiKeyHeader") assertSafeStaticHeaders({ [input.auth.headerName ?? "X-API-Key"]: "" });
    applyAuth(headers, url, input.auth.type, input.auth.secrets, input.auth.headerName);
+    for (const [name, value] of Object.entries(input.auth.headers ?? {})) headers.set(name, value);
+    for (const [name, value] of Object.entries(input.auth.query ?? {})) url.searchParams.set(name, value);
  }
  return headers;
 }
@@ -0,0 +1,43 @@
+import type { ConnectionOptions } from "node:tls";
+
+import type { CustomJsxNetworkScope, CustomWidgetMethod } from "../core";
+
+export interface CustomWidgetAuthConfig {
+  baseUrl?: string;
+  type: string;
+  secrets: Array<{ kind: string; value: string }>;
+  headerName?: string | null;
+  headers?: Record<string, string>;
+  query?: Record<string, string>;
+  transformUrl?(url: URL): void;
+  transformBody?(body: string | undefined): string;
+  isExpired?(response: CustomWidgetHttpResponse): boolean;
+  refreshAsync?(): Promise<CustomWidgetAuthConfig>;
+}
+
+export interface CustomWidgetHttpRequest {
+  resolveConnectionAsync?(): Promise<
+    Pick<CustomWidgetHttpRequest, "baseUrl" | "auth" | "tls" | "pathPrefix" | "redactSecrets">
+  >;
+  tls?: Pick<ConnectionOptions, "ca" | "checkServerIdentity">;
+  pathPrefix?: string;
+  redactSecrets?: CustomWidgetAuthConfig["secrets"];
+  baseUrl: string;
+  targetUrl?: string | URL;
+  method: CustomWidgetMethod;
+  body?: string;
+  staticHeaders?: Record<string, string>;
+  auth?: CustomWidgetAuthConfig;
+  networkScope: CustomJsxNetworkScope;
+  kind: "query" | "action";
+  cacheKey?: string;
+  cacheTtlSeconds?: number;
+  logError?: (event: { origin: string; method: CustomWidgetMethod; errorName: string; reason?: "timeout" }) => void;
+}
+
+export interface CustomWidgetHttpResponse {
+  ok: boolean;
+  status: number;
+  statusText: string;
+  data: unknown;
+}
@@ -1,3 +1,4 @@
+import { Buffer } from "node:buffer";
 import type { Response } from "undici";
 import { CustomWidgetDomainError } from "./errors";

@@ -63,3 +64,39 @@ export async function parseResponseBody(response: Response): Promise<unknown> {

 const tooLarge = () =>
  new CustomWidgetDomainError({ code: "PAYLOAD_TOO_LARGE", message: "Response exceeds the 1 MiB limit" });
+
+export function redactResponseSecrets(data: unknown, secrets: Array<{ kind: string; value: string }>): unknown {
+  if (secrets.length === 0) return data;
+  const values = secrets.map(({ value }) => value).filter(Boolean);
+  const username = secrets.find(({ kind }) => kind === "username")?.value;
+  const password = secrets.find(({ kind }) => kind === "password")?.value;
+  if (username && password) values.push(`${username}:${password}`);
+  const sensitive = [
+    ...new Set(
+      values.flatMap((value) => [
+        value,
+        JSON.stringify(value).slice(1, -1),
+        encodeURIComponent(value),
+        Buffer.from(value).toString("base64"),
+      ]),
+    ),
+  ].toSorted((a, b) => b.length - a.length);
+  const redact = (value: string) => {
+    for (const secret of sensitive) value = value.replaceAll(secret, "[REDACTED]");
+    return value;
+  };
+  const visit = (value: unknown): unknown => {
+    if (typeof value === "string") return redact(value);
+    if (
+      (typeof value === "number" || typeof value === "boolean" || value === null) &&
+      redact(String(value)) !== String(value)
+    )
+      return "[REDACTED]";
+    if (Array.isArray(value)) return value.map(visit);
+    if (value !== null && typeof value === "object") {
+      return Object.fromEntries(Object.entries(value).map(([key, child]) => [redact(key), visit(child)]));
+    }
+    return value;
+  };
+  return visit(data);
+}
@@ -22,7 +22,7 @@ const skillSourceDirectory = path.resolve(import.meta.dirname, "../../../../.age
 describe("authoring resources", () => {
  it("returns the complete portable skill and keeps every bundled source file in sync", () => {
    const skill = getCustomWidgetSkill();
-    expect(skill).toMatchObject({ name: "homarr-custom-widget", version: "2.9.0" });
+    expect(skill).toMatchObject({ name: "homarr-custom-widget", version: "2.10.0" });
    expect(skill.skillsShUrl).toContain("skills.sh/homarr-labs/homarr");
    expect(skill.sourceUrl).toContain("/tree/HEAD/.agents/skills/homarr-custom-widget");
    expect(skill.installCommand).toContain("--skill homarr-custom-widget");
@@ -1,9 +1,10 @@
+import type { ReactNode } from "react";
 import { Alert, Badge, Checkbox, Group, PasswordInput, Select, Stack, Text, TextInput } from "@mantine/core";
 import { IconCheck, IconKey, IconServer, IconX } from "@tabler/icons-react";

 import type {
  CustomWidgetSecretKind,
-  CustomWidgetSource,
+  CustomJsxNetworkScope,
  CustomWidgetSourceSetup,
  CustomWidgetSourceUrlIssue,
 } from "../core";
@@ -11,7 +12,8 @@ import { getCustomWidgetSourceSetupIssue } from "../core";

 export interface CustomWidgetSourceSetupValue {
  baseUrl: string;
-  networkScope: CustomWidgetSource["networkScope"];
+  networkScope: CustomJsxNetworkScope;
+  integrationId?: string;
  urlConfirmed: boolean;
  secrets: Partial<Record<CustomWidgetSecretKind, string>>;
 }
@@ -38,6 +40,7 @@ export interface CustomWidgetSourceSetupPanelProps {
  values: Record<string, CustomWidgetSourceSetupValue>;
  messages: CustomWidgetSourceSetupMessages;
  onChange(sourceId: string, value: CustomWidgetSourceSetupValue): void;
+  renderIntegrationSource?(setup: CustomWidgetSourceSetup, value: CustomWidgetSourceSetupValue): ReactNode;
 }

 export function createCustomWidgetSourceSetupValues(
@@ -48,6 +51,7 @@ export function createCustomWidgetSourceSetupValues(
      setup.sourceId,
      {
        baseUrl: setup.baseUrl,
+        integrationId: setup.integrationId,
        networkScope: setup.networkScope,
        urlConfirmed: !setup.requiresUrlConfirmation,
        secrets: {} as Partial<Record<CustomWidgetSecretKind, string>>,
@@ -62,6 +66,7 @@ export function isCustomWidgetSourceSetupReady(
 ) {
  return setups.every((setup) => {
    const value = values[setup.sourceId];
+    if (setup.integrationKind) return Boolean(value?.integrationId);
    return Boolean(value && !getCustomWidgetSourceSetupIssue(value) && value.urlConfirmed);
  });
 }
@@ -71,6 +76,7 @@ export function CustomWidgetSourceSetupPanel({
  values,
  messages,
  onChange,
+  renderIntegrationSource,
 }: CustomWidgetSourceSetupPanelProps) {
  if (setups.length === 0) return null;
  return (
@@ -84,6 +90,14 @@ export function CustomWidgetSourceSetupPanel({
      {setups.map((setup) => {
        const value = values[setup.sourceId] ?? createCustomWidgetSourceSetupValues([setup])[setup.sourceId];
        if (!value) return null;
+        if (setup.integrationKind) {
+          return (
+            <Stack key={setup.sourceId} gap="sm">
+              <Text fw={600}>{setup.sourceName}</Text>
+              {renderIntegrationSource?.(setup, value)}
+            </Stack>
+          );
+        }
        const issue = getCustomWidgetSourceSetupIssue(value);
        const missingCredentials = setup.credentialFields.filter(
          (field) => !field.configured && !value.secrets[field.kind]?.trim(),
@@ -143,7 +157,7 @@ export function CustomWidgetSourceSetupPanel({
                  networkScope &&
                  onChange(setup.sourceId, {
                    ...value,
-                    networkScope: networkScope as CustomWidgetSource["networkScope"],
+                    networkScope: networkScope as CustomJsxNetworkScope,
                  })
                }
              />
@@ -725,3 +725,8 @@ export const integrationCategories = [
 ] as const;

 export type IntegrationCategory = (typeof integrationCategories)[number];
+
+/** Integrations whose configured connection can serve HTTP requests. */
+export function isHttpIntegrationKind(kind: string): kind is Exclude<IntegrationKind, "truenas" | "mock"> {
+  return Object.hasOwn(integrationDefs, kind) && kind !== "truenas" && kind !== "mock";
+}
@@ -1,6 +1,7 @@
 import { ParseError } from "@homarr/common/server";
 import { fetchWithTrustedCertificatesAsync } from "@homarr/core/infrastructure/http";

+import type { IntegrationHttpAuthentication } from "../http-auth";
 import type { IntegrationTestingInput } from "../base/integration";
 import { Integration } from "../base/integration";
 import { TestConnectionError } from "../base/test-connection/test-connection-error";
@@ -10,6 +11,10 @@ import type { DnsHoleSummary } from "../interfaces/dns-hole-summary/dns-hole-sum
 import { filteringStatusSchema, statsResponseSchema, statusResponseSchema } from "./adguard-home-types";

 export class AdGuardHomeIntegration extends Integration implements DnsHoleSummaryIntegration {
+  public async getHttpAuthenticationAsync(): Promise<IntegrationHttpAuthentication> {
+    return { headers: { Authorization: `Basic ${this.getAuthorizationHeaderValue()}` } };
+  }
+
  public async getSummaryAsync(): Promise<DnsHoleSummary> {
    const headers = {
      Authorization: `Basic ${this.getAuthorizationHeaderValue()}`,
@@ -4,6 +4,8 @@ import { ResponseError } from "@homarr/common/server";
 import { fetchWithTrustedCertificatesAsync } from "@homarr/core/infrastructure/http";
 import { createLogger } from "@homarr/core/infrastructure/logs";

+import type { IntegrationHttpAuthentication } from "../http-auth";
+import { bearerAuth } from "../http-auth";
 import type { IntegrationTestingInput } from "../base/integration";
 import { Integration } from "../base/integration";
 import { TestConnectionError } from "../base/test-connection/test-connection-error";
@@ -14,11 +16,13 @@ import type { AnchorNote, AnchorNotesListInput, AnchorNoteSummary, AnchorNoteUpd
 const logger = createLogger({ module: "anchorIntegration" });

 export class AnchorIntegration extends Integration {
+  public async getHttpAuthenticationAsync(): Promise<IntegrationHttpAuthentication> {
+    return bearerAuth(this.integration);
+  }
+
  protected async testingAsync(input: IntegrationTestingInput): Promise<TestingResult> {
    const response = await input.fetchAsync(this.url("/api/notes", { limit: 1 }), {
-      headers: {
-        Authorization: `Bearer ${this.getSecretValue("apiKey")}`,
-      },
+      headers: (await this.getHttpAuthenticationAsync()).headers,
    });

    if (!response.ok) return TestConnectionError.StatusResult(response);
@@ -6,6 +6,7 @@ import { z } from "zod/v4";

 import { fetchWithTrustedCertificatesAsync } from "@homarr/core/infrastructure/http";

+import type { IntegrationHttpAuthentication } from "../http-auth";
 import type { IntegrationTestingInput } from "../base/integration";
 import { Integration } from "../base/integration";
 import { TestConnectionError } from "../base/test-connection/test-connection-error";
@@ -36,6 +37,10 @@ interface WarriorSnapshotState {
 }

 export class ArchiveTeamWarriorIntegration extends Integration {
+  public async getHttpAuthenticationAsync(): Promise<IntegrationHttpAuthentication> {
+    return { headers: this.createAuthHeaders() };
+  }
+
  protected async testingAsync(input: IntegrationTestingInput): Promise<TestingResult> {
    const response = await input.fetchAsync(this.url("/index.html"), {
      headers: this.createAuthHeaders(),
@@ -1,6 +1,7 @@
 import { ResponseError } from "@homarr/common/server";
 import { fetchWithTrustedCertificatesAsync } from "@homarr/core/infrastructure/http";

+import type { IntegrationHttpAuthentication } from "../http-auth";
 import type { IntegrationTestingInput } from "../base/integration";
 import { Integration } from "../base/integration";
 import { TestConnectionError } from "../base/test-connection/test-connection-error";
@@ -26,6 +27,10 @@ const mediaTypeCountField = {
 >;

 export class AudiobookshelfIntegration extends Integration {
+  public async getHttpAuthenticationAsync(): Promise<IntegrationHttpAuthentication> {
+    return { headers: this.getAuthHeaders(), redactValues: [] };
+  }
+
  protected async testingAsync(input: IntegrationTestingInput): Promise<TestingResult> {
    const healthResponse = await input.fetchAsync(this.url("/healthcheck"));

@@ -1,7 +1,9 @@
+import { isHttpIntegrationKind } from "@homarr/definitions";
 import type { IntegrationKind } from "@homarr/definitions";
 import { createLogger } from "@homarr/core/infrastructure/logs";
 import { ErrorWithMetadata } from "@homarr/core/infrastructure/logs/error";

+import { clientAuthentication } from "../http-auth";
 import type { Integration, IntegrationInput } from "./integration";

 const logger = createLogger({ module: "integrationFactory" });
@@ -162,3 +164,8 @@ export async function createIntegrationAsync(
    throw error;
  }
 }
+
+export async function getIntegrationHttpAuthenticationAsync(integration: IntegrationInput & { kind: IntegrationKind }) {
+  if (!isHttpIntegrationKind(integration.kind)) throw new Error("This integration does not use HTTP");
+  return clientAuthentication(() => createIntegrationAsync(integration));
+}
@@ -7,6 +7,7 @@ import { removeTrailingSlash } from "@homarr/common";
 import { createAxiosCertificateInstanceAsync, createCertificateAgentAsync } from "@homarr/core/infrastructure/http";
 import type { IntegrationKind, IntegrationSecretKind } from "@homarr/definitions";

+import type { IntegrationHttpAuthentication } from "../http-auth";
 import { HandleIntegrationErrors } from "./errors/decorator";
 import { TestConnectionError } from "./test-connection/test-connection-error";
 import type { TestingResult } from "./test-connection/test-connection-service";
@@ -36,6 +37,8 @@ export interface IntegrationTestingInput {
 export abstract class Integration {
  constructor(protected integration: IntegrationInput) {}

+  public abstract getHttpAuthenticationAsync(refresh?: boolean): Promise<IntegrationHttpAuthentication>;
+
  public get publicIntegration() {
    return {
      id: this.integration.id,
@@ -1,5 +1,6 @@
 import { fetchWithTrustedCertificatesAsync } from "@homarr/core/infrastructure/http";

+import type { IntegrationHttpAuthentication } from "../http-auth";
 import type { IntegrationTestingInput } from "../base/integration";
 import { Integration } from "../base/integration";
 import { TestConnectionError } from "../base/test-connection/test-connection-error";
@@ -8,6 +9,10 @@ import type { BazarrBadges } from "./bazarr-types";
 import { bazarrBadgesSchema, bazarrSystemStatusSchema } from "./bazarr-types";

 export class BazarrIntegration extends Integration {
+  public async getHttpAuthenticationAsync(): Promise<IntegrationHttpAuthentication> {
+    return { headers: this.getAuthHeaders(), redactValues: [] };
+  }
+
  protected async testingAsync(input: IntegrationTestingInput): Promise<TestingResult> {
    const response = await input.fetchAsync(this.url("/api/system/status"), {
      headers: this.getAuthHeaders(),
@@ -125,6 +125,12 @@ export const isSessionExpired = (session: BeszelSession, now = Date.now()) =>
  session.expiresAt !== undefined && session.expiresAt - sessionExpiryLeewayMs <= now;

 export class BeszelIntegration extends Integration {
+  public async getHttpAuthenticationAsync(refresh = false) {
+    if (refresh) await this.sessionStore.clearAsync();
+    const session = await this.authenticateAsync();
+    return { headers: { Authorization: session.token } };
+  }
+
  private readonly sessionStore: SessionStore<BeszelSession>;

  constructor(integration: IntegrationInput) {
@@ -1,6 +1,7 @@
 import { ResponseError } from "@homarr/common/server";
 import { fetchWithTrustedCertificatesAsync } from "@homarr/core/infrastructure/http";

+import type { IntegrationHttpAuthentication } from "../http-auth";
 import type { IntegrationTestingInput } from "../base/integration";
 import { Integration } from "../base/integration";
 import type { TestingResult } from "../base/test-connection/test-connection-service";
@@ -32,6 +33,10 @@ import {
 } from "./coolify-types";

 export class CoolifyIntegration extends Integration {
+  public async getHttpAuthenticationAsync(): Promise<IntegrationHttpAuthentication> {
+    return { headers: this.getAuthHeaders() };
+  }
+
  protected async testingAsync(input: IntegrationTestingInput): Promise<TestingResult> {
    const healthUrl = this.url("/api/health");
    const healthResponse = await input.fetchAsync(healthUrl, {});
@@ -5,6 +5,7 @@ import { z } from "zod/v4";

 import { fetchWithTrustedCertificatesAsync } from "@homarr/core/infrastructure/http";

+import type { IntegrationHttpAuthentication } from "../http-auth";
 import { createChannelEventHistoryOld } from "../../../redis/src/lib/channel";
 import type { IntegrationTestingInput } from "../base/integration";
 import { Integration } from "../base/integration";
@@ -14,6 +15,10 @@ import type { ISystemHealthMonitoringIntegration } from "../interfaces/health-mo
 import type { SystemHealthMonitoring } from "../interfaces/health-monitoring/health-monitoring-types";

 export class DashDotIntegration extends Integration implements ISystemHealthMonitoringIntegration {
+  public async getHttpAuthenticationAsync(): Promise<IntegrationHttpAuthentication> {
+    return {};
+  }
+
  protected async testingAsync(input: IntegrationTestingInput): Promise<TestingResult> {
    const response = await input.fetchAsync(this.url("/info"));
    if (!response.ok) return TestConnectionError.StatusResult(response);
@@ -4,6 +4,7 @@ import type { fetch as undiciFetch } from "undici";
 import { ResponseError } from "@homarr/common/server";
 import { fetchWithTrustedCertificatesAsync } from "@homarr/core/infrastructure/http";

+import type { IntegrationHttpAuthentication } from "../../http-auth";
 import { Integration } from "../../base/integration";
 import type { IntegrationTestingInput } from "../../base/integration";
 import type { TestingResult } from "../../base/test-connection/test-connection-service";
@@ -13,6 +14,27 @@ import type { DownloadClientItem } from "../../interfaces/downloads/download-cli
 import type { Aria2Download, Aria2GetClient } from "./aria2-types";

 export class Aria2Integration extends Integration implements IDownloadClientIntegration {
+  public async getHttpAuthenticationAsync(): Promise<IntegrationHttpAuthentication> {
+    if (!this.hasSecretValue("apiKey") || !this.getSecretValue("apiKey")) return {};
+    return {
+      transformBody: (body) => {
+        const authenticate = (value: unknown): unknown => {
+          if (Array.isArray(value)) return value.map(authenticate);
+          if (!value || typeof value !== "object") throw new Error("Expected a JSON-RPC request body");
+          const request = value as { method?: string; methodName?: string; params?: unknown[] };
+          const method = request.method ?? request.methodName;
+          const params = request.params ?? [];
+          if (!Array.isArray(params)) throw new Error("JSON-RPC params must be an array");
+          if (method === "system.multicall") return { ...request, params: [authenticate(params[0])] };
+          if (method === "system.listMethods" || method === "system.listNotifications") return request;
+          if (typeof params[0] === "string" && params[0].startsWith("token:")) params.shift();
+          return { ...request, params: [`token:${this.getSecretValue("apiKey")}`, ...params] };
+        };
+        return JSON.stringify(authenticate(JSON.parse(body ?? "null")));
+      },
+    };
+  }
+
  public async getClientJobsAndStatusAsync(input: { limit: number }): Promise<DownloadClientJobsAndStatus> {
    const client = this.getClient();
    const keys: (keyof Aria2Download)[] = [
@@ -17,6 +17,15 @@ import type { DownloadClientStatus } from "../../interfaces/downloads/download-c

@HandleIntegrationErrors([integrationOFetchHttpErrorHandler])
 export class DelugeIntegration extends Integration implements IDownloadClientIntegration {
+  public async getHttpAuthenticationAsync() {
+    const client = await this.getClientAsync();
+    await client.login();
+    if (!(await client.connected())) await client.connect();
+    const cookie = client.exportState().auth.cookieHeader;
+    if (!cookie) throw new Error("Integration authentication did not return a session");
+    return { headers: { Cookie: cookie } };
+  }
+
  protected async testingAsync(input: IntegrationTestingInput): Promise<TestingResult> {
    const client = await this.getClientAsync(input.dispatcher);
    const isSuccess = await client.login();
@@ -4,6 +4,8 @@ import type { fetch as undiciFetch } from "undici";
 import { ResponseError } from "@homarr/common/server";
 import { fetchWithTrustedCertificatesAsync } from "@homarr/core/infrastructure/http";

+import type { IntegrationHttpAuthentication } from "../../http-auth";
+import { basicAuth } from "../../http-auth";
 import { Integration } from "../../base/integration";
 import type { IntegrationTestingInput } from "../../base/integration";
 import type { TestingResult } from "../../base/test-connection/test-connection-service";
@@ -14,6 +16,10 @@ import type { DownloadClientStatus } from "../../interfaces/downloads/download-c
 import type { NzbGetClient } from "./nzbget-types";

 export class NzbGetIntegration extends Integration implements IDownloadClientIntegration {
+  public async getHttpAuthenticationAsync(): Promise<IntegrationHttpAuthentication> {
+    return basicAuth()(this.integration);
+  }
+
  protected async testingAsync(input: IntegrationTestingInput): Promise<TestingResult> {
    await this.nzbGetApiCallWithCustomFetchAsync(input.fetchAsync, "version");
    return {
@@ -1,3 +1,4 @@
+import type { IntegrationHttpAuthentication } from "../../http-auth";
 import { QBittorrent } from "@ctrl/qbittorrent";
 import dayjs from "dayjs";
 import type { Dispatcher } from "undici";
@@ -17,6 +18,17 @@ import type { DownloadClientStatus } from "../../interfaces/downloads/download-c

@HandleIntegrationErrors([integrationOFetchHttpErrorHandler])
 export class QBitTorrentIntegration extends Integration implements IDownloadClientIntegration {
+  public async getHttpAuthenticationAsync(): Promise<IntegrationHttpAuthentication> {
+    if (this.hasSecretValue("apiKey")) return { headers: { Authorization: `Bearer ${this.getSecretValue("apiKey")}` } };
+    const client = await this.getClientAsync();
+    const auth = client.exportState().auth;
+    if (!auth) return {};
+    return {
+      headers: { Cookie: `${auth.cookieName ?? "SID"}=${auth.sid}` },
+      isExpired: ({ status }) => status === 403,
+    };
+  }
+
  protected async testingAsync(input: IntegrationTestingInput): Promise<TestingResult> {
    const client = await this.getClientAsync(input.dispatcher);
    const isSuccess = await client.login();
@@ -5,6 +5,8 @@ import type { fetch as undiciFetch } from "undici";
 import { ResponseError } from "@homarr/common/server";
 import { fetchWithTrustedCertificatesAsync } from "@homarr/core/infrastructure/http";

+import type { IntegrationHttpAuthentication } from "../../http-auth";
+import { queryAuth } from "../../http-auth";
 import { Integration } from "../../base/integration";
 import type { IntegrationTestingInput } from "../../base/integration";
 import type { TestingResult } from "../../base/test-connection/test-connection-service";
@@ -17,6 +19,10 @@ import { historySchema, queueSchema } from "./sabnzbd-schema";
 dayjs.extend(duration);

 export class SabnzbdIntegration extends Integration implements IDownloadClientIntegration {
+  public async getHttpAuthenticationAsync(): Promise<IntegrationHttpAuthentication> {
+    return queryAuth("apikey")(this.integration);
+  }
+
  protected async testingAsync(input: IntegrationTestingInput): Promise<TestingResult> {
    //This is the one call that uses the least amount of data while requiring the api key
    await this.sabNzbApiCallWithCustomFetchAsync(input.fetchAsync, "translate", { value: "ping" });
@@ -6,6 +6,8 @@ import { fetchWithTrustedCertificatesAsync } from "@homarr/core/infrastructure/h
 import { createLogger } from "@homarr/core/infrastructure/logs";
 import { ErrorWithMetadata } from "@homarr/core/infrastructure/logs/error";

+import type { IntegrationHttpAuthentication } from "../../http-auth";
+import { apiKeyAuth } from "../../http-auth";
 import type { IntegrationTestingInput } from "../../base/integration";
 import { Integration } from "../../base/integration";
 import { TestConnectionError } from "../../base/test-connection/test-connection-error";
@@ -49,6 +51,10 @@ const logger = createLogger({ module: "slskd-integration" });
 * Slskd integration cannot pause or stop downloads, it can only list downloads.
 */
 export class SlskdIntegration extends Integration implements IDownloadClientIntegration {
+  public async getHttpAuthenticationAsync(): Promise<IntegrationHttpAuthentication> {
+    return apiKeyAuth(this.integration);
+  }
+
  // eslint-disable-next-line no-restricted-syntax
  public pauseQueueAsync(): Promise<void> {
    return Promise.resolve();
@@ -76,9 +82,7 @@ export class SlskdIntegration extends Integration implements IDownloadClientInte

  protected async testingAsync(input: IntegrationTestingInput): Promise<TestingResult> {
    const response = await input.fetchAsync(this.url("/api/v0/server"), {
-      headers: {
-        "X-API-Key": this.getSecretValue("apiKey"),
-      },
+      headers: (await this.getHttpAuthenticationAsync()).headers,
    });

    if (!response.ok) {
@@ -148,9 +152,7 @@ export class SlskdIntegration extends Integration implements IDownloadClientInte
  ): Promise<unknown> {
    const response = await fetchWithTrustedCertificatesAsync(this.url(path), {
      ...options,
-      headers: {
-        "X-API-Key": this.getSecretValue("apiKey"),
-      },
+      headers: (await this.getHttpAuthenticationAsync()).headers,
    });

    if (!response.ok) {
@@ -16,6 +16,20 @@ import type { DownloadClientStatus } from "../../interfaces/downloads/download-c

@HandleIntegrationErrors([integrationOFetchHttpErrorHandler])
 export class TransmissionIntegration extends Integration implements IDownloadClientIntegration {
+  public async getHttpAuthenticationAsync() {
+    const client = await this.getClientAsync();
+    await client.getSession();
+    const session = client.exportState().auth?.sessionId;
+    if (!session) throw new Error("Integration authentication did not return a session");
+    const credentials = Buffer.from(`${this.getSecretValue("username")}:${this.getSecretValue("password")}`).toString(
+      "base64",
+    );
+    return {
+      headers: { Authorization: `Basic ${credentials}`, "X-Transmission-Session-Id": session },
+      isExpired: (response: { status: number }) => response.status === 409,
+    };
+  }
+
  protected async testingAsync(input: IntegrationTestingInput): Promise<TestingResult> {
    const client = await this.getClientAsync(input.dispatcher);
    await client.getSession();
@@ -4,6 +4,8 @@ import { z } from "zod/v4";
 import { ResponseError } from "@homarr/common/server";
 import { fetchWithTrustedCertificatesAsync } from "@homarr/core/infrastructure/http";

+import type { IntegrationHttpAuthentication } from "../http-auth";
+import { headerAuth } from "../http-auth";
 import type { IntegrationTestingInput } from "../base/integration";
 import { Integration } from "../base/integration";
 import { TestConnectionError } from "../base/test-connection/test-connection-error";
@@ -90,6 +92,10 @@ const userSchema = z.object({
 });

 export class EmbyIntegration extends Integration implements IMediaServerIntegration, IMediaReleasesIntegration {
+  public async getHttpAuthenticationAsync(): Promise<IntegrationHttpAuthentication> {
+    return headerAuth("X-Emby-Token")(this.integration);
+  }
+
  private static readonly apiKeyHeader = "X-Emby-Token";
  private static readonly deviceId = "homarr-emby-integration";
  private static readonly authorizationHeaderValue = `Emby Client="Dashboard", Device="Homarr", DeviceId="${EmbyIntegration.deviceId}", Version="0.0.1"`;
@@ -1 +1,3 @@
-export { createIntegrationAsync } from "./base/creator";
+export { createIntegrationAsync, getIntegrationHttpAuthenticationAsync } from "./base/creator";
+
+export type { IntegrationHttpAuthentication } from "./http-auth";
@@ -4,6 +4,7 @@ import { z } from "zod/v4";
 import { ResponseError } from "@homarr/common/server";
 import { fetchWithTrustedCertificatesAsync } from "@homarr/core/infrastructure/http";

+import type { IntegrationHttpAuthentication } from "../http-auth";
 import type { IntegrationInput, IntegrationTestingInput } from "../base/integration";
 import { Integration } from "../base/integration";
 import type { SessionStore } from "../base/session-store";
@@ -14,6 +15,10 @@ import type { ISystemHealthMonitoringIntegration } from "../interfaces/health-mo
 import type { SystemHealthMonitoring } from "../types";

 export class GlancesIntegration extends Integration implements ISystemHealthMonitoringIntegration {
+  public async getHttpAuthenticationAsync(): Promise<IntegrationHttpAuthentication> {
+    return {};
+  }
+
  private readonly sessionStore: SessionStore<{ version: string }>;

  constructor(integration: IntegrationInput) {
@@ -1,6 +1,7 @@
 import { ResponseError } from "@homarr/common/server";
 import { fetchWithTrustedCertificatesAsync } from "@homarr/core/infrastructure/http";

+import type { IntegrationHttpAuthentication } from "../http-auth";
 import type { IntegrationTestingInput } from "../base/integration";
 import { Integration } from "../base/integration";
 import { TestConnectionError } from "../base/test-connection/test-connection-error";
@@ -16,6 +17,10 @@ import {
 import type { GluetunDnsStatus, GluetunPublicIp, GluetunVpnSettings, GluetunVpnStatus } from "./gluetun-types";

 export class GluetunIntegration extends Integration implements VpnSummaryIntegration {
+  public async getHttpAuthenticationAsync(): Promise<IntegrationHttpAuthentication> {
+    return { headers: this.getAuthHeaders() };
+  }
+
  protected async testingAsync(input: IntegrationTestingInput): Promise<TestingResult> {
    const authHeaders = this.getAuthHeaders();
    const url = this.url("/v1/vpn/status");
@@ -2,6 +2,7 @@ import { ResponseError } from "@homarr/common/server";
 import { fetchWithTrustedCertificatesAsync } from "@homarr/core/infrastructure/http";
 import { ImageProxy } from "@homarr/image-proxy";

+import type { IntegrationHttpAuthentication } from "../http-auth";
 import { Integration } from "../base/integration";
 import type { IntegrationTestingInput } from "../base/integration";
 import type { TestingResult } from "../base/test-connection/test-connection-service";
@@ -10,6 +11,10 @@ import type { INotificationsIntegration } from "../interfaces/notifications/noti
 import { gotifyApplicationsResponseSchema, gotifyMessagesResponseSchema } from "./gotify-schema";

 export class GotifyIntegration extends Integration implements INotificationsIntegration {
+  public async getHttpAuthenticationAsync(): Promise<IntegrationHttpAuthentication> {
+    return { headers: this.getHeaders() };
+  }
+
  public async testingAsync(input: IntegrationTestingInput): Promise<TestingResult> {
    await input.fetchAsync(this.url("/health"), { headers: this.getHeaders() });
    return { success: true };
@@ -5,6 +5,7 @@ import { fetchWithTrustedCertificatesAsync } from "@homarr/core/infrastructure/h
 import { createLogger } from "@homarr/core/infrastructure/logs";
 import { ErrorWithMetadata } from "@homarr/core/infrastructure/logs/error";

+import type { IntegrationHttpAuthentication } from "../http-auth";
 import type { IntegrationTestingInput } from "../base/integration";
 import { Integration } from "../base/integration";
 import { TestConnectionError } from "../base/test-connection/test-connection-error";
@@ -17,6 +18,10 @@ import { calendarEventSchema, calendarsSchema, entityStateSchema } from "./homea
 const logger = createLogger({ module: "homeAssistantIntegration" });

 export class HomeAssistantIntegration extends Integration implements ISmartHomeIntegration, ICalendarIntegration {
+  public async getHttpAuthenticationAsync(): Promise<IntegrationHttpAuthentication> {
+    return { headers: this.getAuthHeaders() };
+  }
+
  public async getEntityStateAsync(entityId: string) {
    try {
      const response = await this.getAsync(`/api/states/${entityId}`);
@@ -134,7 +139,10 @@ export class HomeAssistantIntegration extends Integration implements ISmartHomeI
   */
  private async postAsync(path: `/api/${string}`, body: Record<string, string>) {
    return await fetchWithTrustedCertificatesAsync(this.url(path), {
-      headers: this.getAuthHeaders(),
+      headers: {
+        ...this.getAuthHeaders(),
+        "Content-Type": "application/json",
+      },
      body: JSON.stringify(body),
      method: "POST",
    });
@@ -0,0 +1,79 @@
+import { Buffer } from "node:buffer";
+
+import type { IntegrationSecretKind } from "@homarr/definitions";
+
+import type { IntegrationInput } from "./base/integration";
+
+export interface IntegrationHttpAuthentication {
+  headers?: Record<string, string>;
+  redactValues?: string[];
+  query?: Record<string, string>;
+  baseUrl?: string;
+  transformUrl?(url: URL): void;
+  transformBody?(body: string | undefined): string;
+  isExpired?(response: { status: number; data: unknown }): boolean;
+  refreshAsync?(): Promise<IntegrationHttpAuthentication>;
+}
+
+function secret(input: IntegrationInput, kind: IntegrationSecretKind) {
+  const value = input.decryptedSecrets.find((entry) => entry.kind === kind)?.value;
+  if (!value) throw new Error(`Integration credential ${kind} is missing`);
+  return value;
+}
+
+export const headerAuth =
+  (name: string, prefix = "", kind: IntegrationSecretKind = "apiKey") =>
+  (input: IntegrationInput): IntegrationHttpAuthentication => ({
+    headers: { [name]: `${prefix}${secret(input, kind)}` },
+  });
+export const bearerAuth = headerAuth("Authorization", "Bearer ");
+export const apiKeyAuth = headerAuth("X-API-Key");
+export const basicAuth =
+  (
+    username: IntegrationSecretKind = "username",
+    password: IntegrationSecretKind = "password",
+    headers: Record<string, string> = {},
+  ) =>
+  (input: IntegrationInput): IntegrationHttpAuthentication => {
+    const credentials = Buffer.from(`${secret(input, username)}:${secret(input, password)}`).toString("base64");
+    return { headers: { ...headers, Authorization: `Basic ${credentials}` }, redactValues: [credentials] };
+  };
+export const queryAuth =
+  (name: string, kind: IntegrationSecretKind = "apiKey") =>
+  (input: IntegrationInput): IntegrationHttpAuthentication => ({ query: { [name]: secret(input, kind) } });
+export const clientAuthentication = async (
+  create: () => Promise<{ getHttpAuthenticationAsync(refresh?: boolean): Promise<IntegrationHttpAuthentication> }>,
+) =>
+  withAuthTimeout(async () => {
+    const client = await create();
+    const resolve = async (refresh = false): Promise<IntegrationHttpAuthentication> => {
+      const auth = await client.getHttpAuthenticationAsync(refresh);
+      const values = [...Object.values(auth.headers ?? {}), ...Object.values(auth.query ?? {})];
+      for (const [name, value] of Object.entries(auth.headers ?? {})) {
+        if (name.toLowerCase() === "cookie") {
+          for (const cookie of value.split(";")) values.push(cookie.slice(cookie.indexOf("=") + 1).trim());
+        }
+        if (name.toLowerCase() === "authorization") values.push(value.slice(value.indexOf(" ") + 1));
+      }
+      return {
+        ...auth,
+        redactValues: auth.redactValues ?? values,
+        refreshAsync: () => withAuthTimeout(() => resolve(true)),
+      };
+    };
+    return resolve();
+  });
+
+async function withAuthTimeout<T>(resolve: () => T | Promise<T>): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      Promise.resolve().then(resolve),
+      new Promise<never>((_resolve, reject) => {
+        timer = setTimeout(() => reject(new Error("Integration authentication timed out")), 10_000);
+      }),
+    ]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
Author	SHA1	Message	Date
ajnart	db4b6bf4b5	refactor: let integrations own HTTP authentication	2026-09-12 23:57:33 +02:00
ajnart	8157a43b9b	fix: make integration types searchable	2026-09-12 23:39:10 +02:00
ajnart	901fd3d940	feat: reuse authentication for all HTTP integrations	2026-09-12 23:33:23 +02:00
ajnart	879a4ae23c	fix: render integration sources in Workshop details	2026-09-12 22:45:52 +02:00
ajnart	d0529079ec	fix: remove unused request type import	2026-09-12 20:32:03 +02:00
ajnart	c2a587bda7	fix: share integration transport and enforce access	2026-09-12 20:26:39 +02:00
ajnart	52c82f72db	feat: reuse integrations in custom widgets	2026-09-12 20:17:07 +02:00
Thomas	c32a5317ca	fix: remove apps multi-select toggle (#6834 )	2026-09-12 16:34:03 +02:00
Thomas	f18033ddaa	fix: sync dev fixes into v2 and improve regression reports (#6821 ) Co-authored-by: Homarr Update Contributors <210161987+homarr-update-contributors[bot]@users.noreply.github.com> Co-authored-by: Crowdin Homarr <190541745+homarr-crowdin[bot]@users.noreply.github.com> Co-authored-by: Releases Homarr <175486441+homarr-releases[bot]@users.noreply.github.com> Co-authored-by: Thomas <thomas@ajnart.fr> Co-authored-by: homarr-releases[bot] <175486441+homarr-releases[bot]@users.noreply.github.com> Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com> Co-authored-by: homarr-update-contributors[bot] <210161987+homarr-update-contributors[bot]@users.noreply.github.com> Co-authored-by: homarr-crowdin[bot] <190541745+homarr-crowdin[bot]@users.noreply.github.com> Co-authored-by: Afonso Jorge Ramos <afonsojorgeramos@gmail.com> Co-authored-by: Danura30082 <danura30082+github@gmail.com> Co-authored-by: Kushie <122986913+kushiemoon-dev@users.noreply.github.com> Closes #6604	2026-09-12 15:31:04 +02:00
Thomas	ff2b589380	fix(board): refine container spacing and collapse layout (#6833 )	2026-09-12 15:23:50 +02:00
Thomas	9bc3802b3b	fix(wud): authenticate HTTP requests and validate container access (#6831 )	2026-09-12 10:57:36 +02:00