feat: promote assistant configuration
This commit is contained in:
1 parent
c0445cdca2
commit
cba2df72e2
13 files changed
+219
-23
No files matched your search
@@ -0,0 +1,76 @@
|
||||
---
|
||||
tags:
|
||||
- Assistant
|
||||
- AI
|
||||
- Administration
|
||||
- Security
|
||||
---
|
||||
|
||||
# Homarr Assistant
|
||||
|
||||
Administrators can configure the instance-wide AI assistant from **Management → Assistant**.
|
||||
It is available to signed-in users from the header, the user menu, and the `Cmd/Ctrl + K` command menu.
|
||||
`Cmd/Ctrl + Shift + K` opens it directly.
|
||||
|
||||
When the assistant is unavailable, its command-menu result remains visible but disabled and explains that
|
||||
an administrator must configure and enable it.
|
||||
|
||||
## Configure a model provider
|
||||
|
||||
Homarr includes presets for OpenRouter, OpenAI, Anthropic Claude, Google Gemini, xAI, Groq, Mistral AI,
|
||||
DeepSeek, Together AI, Ollama, and LM Studio. Provider icons make the presets easy to identify. A custom
|
||||
preset connects any other service that implements the OpenAI Chat Completions API.
|
||||
|
||||
1. Choose a provider preset or **Custom endpoint**.
|
||||
2. Confirm the API base URL. It usually ends in `/v1`.
|
||||
3. Add an API key if the service requires bearer authentication.
|
||||
4. Add any provider-specific authentication or routing headers.
|
||||
5. Save the provider connection.
|
||||
6. Refresh the model list or enter an exact model ID manually.
|
||||
7. Enable the assistant and save the configuration.
|
||||
|
||||
The model discovery path defaults to `/models` and is appended to the API base URL. Leave it blank when
|
||||
the service does not expose model discovery. A manual model ID can still be used.
|
||||
|
||||
API keys and additional header values are encrypted in the Homarr database. They are decrypted only on
|
||||
the server for discovery and model requests, and they are never returned to the browser. Changing the
|
||||
provider or base URL clears existing credentials unless replacements are submitted with the change. This
|
||||
prevents credentials for one service from being sent to another endpoint.
|
||||
|
||||
:::info Container networking
|
||||
|
||||
For a containerized Homarr installation, `localhost` refers to the Homarr container. Use a resolvable
|
||||
container name, internal DNS name, or host gateway address to reach Ollama, LM Studio, or another local
|
||||
model server.
|
||||
|
||||
:::
|
||||
|
||||
The configured endpoint must support streaming Chat Completions and structured tool calls for the full
|
||||
assistant experience. Model discovery alone does not guarantee tool support, except when OpenRouter
|
||||
explicitly advertises the model's `tools` capability.
|
||||
|
||||
The Claude preset uses Anthropic's OpenAI SDK compatibility layer. Anthropic describes that layer as
|
||||
suited to testing and comparison rather than as its full native API; unsupported OpenAI fields may be
|
||||
ignored. Streaming responses and tool calls are supported, which are the capabilities Homarr Assistant
|
||||
uses. Choose OpenRouter or another provider when you prefer a provider-neutral production endpoint.
|
||||
|
||||
## Conversations and tools
|
||||
|
||||
Conversations and messages are stored per user in the Homarr database. Users can start, revisit, archive,
|
||||
and delete conversations from the assistant panel.
|
||||
|
||||
The assistant can use the same internal tool definitions as the [Homarr MCP server](./mcp).
|
||||
Each tool call runs as the signed-in user, so normal Homarr permission checks still apply. Read-only
|
||||
procedures can run during the agent loop. Mutating procedures require an explicit approval in the
|
||||
conversation before they execute.
|
||||
|
||||
Homarr also exposes a small set of browser-only actions to the assistant. These actions can navigate to
|
||||
safe internal routes and open Homarr interfaces such as the command menu and media request search.
|
||||
They never receive provider credentials and cannot navigate to arbitrary external URLs.
|
||||
|
||||
:::warning
|
||||
|
||||
Assistant prompts and selected tool results are sent to the configured model endpoint. Review that
|
||||
service's privacy and retention terms before enabling this feature for an instance.
|
||||
|
||||
:::
|
||||
@@ -12,7 +12,7 @@ Homarr exposes a [Model Context Protocol](https://modelcontextprotocol.io) serve
|
||||
|
||||
With MCP, you can ask your AI assistant to manage apps, integrations, users, boards, Docker containers, media servers, DNS settings, and more - all through Homarr's existing tRPC API, now exposed as 50+ AI-callable tools.
|
||||
|
||||
The optional [Homarr Assistant](./settings#homarr-assistant) uses these same tool definitions internally.
|
||||
The optional [Homarr Assistant](./assistant) uses these same tool definitions internally.
|
||||
Unlike external MCP clients, it uses the current Homarr session directly and asks for in-conversation
|
||||
approval before running mutating procedures.
|
||||
|
||||
|
||||
+18
-9
@@ -10,6 +10,7 @@ import {
|
||||
Card,
|
||||
Divider,
|
||||
Group,
|
||||
Image,
|
||||
LoadingOverlay,
|
||||
PasswordInput,
|
||||
Select,
|
||||
@@ -18,7 +19,6 @@ import {
|
||||
Switch,
|
||||
Text,
|
||||
TextInput,
|
||||
Title,
|
||||
Tooltip,
|
||||
} from "@mantine/core";
|
||||
import {
|
||||
@@ -26,7 +26,6 @@ import {
|
||||
IconDatabaseSearch,
|
||||
IconKey,
|
||||
IconPlus,
|
||||
IconRobot,
|
||||
IconShieldLock,
|
||||
IconTool,
|
||||
IconTrash,
|
||||
@@ -41,7 +40,16 @@ import { useScopedI18n } from "@homarr/translation/client";
|
||||
|
||||
type HeaderEntry = { id: number; name: string; value: string };
|
||||
|
||||
export const AssistantSettings = () => {
|
||||
const ProviderIcon = ({ providerId, size = 20 }: { providerId: AssistantProvider; size?: number }) => {
|
||||
const iconUrl = assistantProviderPresets[providerId].iconUrl;
|
||||
return iconUrl ? (
|
||||
<Image src={iconUrl} alt="" aria-hidden w={size} h={size} fit="contain" />
|
||||
) : (
|
||||
<IconWorld size={size} aria-hidden />
|
||||
);
|
||||
};
|
||||
|
||||
export const AssistantConfiguration = () => {
|
||||
const t = useScopedI18n("management.page.settings.section.assistant");
|
||||
const utils = clientApi.useUtils();
|
||||
const { data: configuration, isLoading } = clientApi.assistant.getAdminConfiguration.useQuery();
|
||||
@@ -200,12 +208,6 @@ export const AssistantSettings = () => {
|
||||
|
||||
return (
|
||||
<Stack>
|
||||
<Group gap="sm">
|
||||
<IconRobot size={26} />
|
||||
<Title order={2}>{t("title")}</Title>
|
||||
</Group>
|
||||
<Text c="dimmed">{t("description")}</Text>
|
||||
|
||||
<Card pos="relative" withBorder>
|
||||
<LoadingOverlay visible={pending} />
|
||||
<Stack gap="lg">
|
||||
@@ -234,6 +236,13 @@ export const AssistantSettings = () => {
|
||||
data={providerOptions}
|
||||
searchable
|
||||
allowDeselect={false}
|
||||
leftSection={<ProviderIcon providerId={provider} />}
|
||||
renderOption={({ option }) => (
|
||||
<Group gap="sm" wrap="nowrap">
|
||||
<ProviderIcon providerId={option.value as AssistantProvider} />
|
||||
<Text size="sm">{option.label}</Text>
|
||||
</Group>
|
||||
)}
|
||||
/>
|
||||
<TextInput
|
||||
label={t("baseUrl.title")}
|
||||
@@ -0,0 +1,39 @@
|
||||
import { notFound } from "next/navigation";
|
||||
import { Stack, Text, Title } from "@mantine/core";
|
||||
|
||||
import { auth } from "@homarr/auth/next";
|
||||
import { getScopedI18n } from "@homarr/translation/server";
|
||||
|
||||
import { DynamicBreadcrumb } from "~/components/navigation/dynamic-breadcrumb";
|
||||
import { AssistantConfiguration } from "./_components/assistant-configuration";
|
||||
|
||||
export async function generateMetadata() {
|
||||
const t = await getScopedI18n("management.page.settings.section.assistant");
|
||||
return {
|
||||
title: `${t("title")} • Homarr`,
|
||||
};
|
||||
}
|
||||
|
||||
export default async function AssistantPage() {
|
||||
const session = await auth();
|
||||
|
||||
if (!session?.user.permissions.includes("admin")) {
|
||||
notFound();
|
||||
}
|
||||
|
||||
const t = await getScopedI18n("management.page.settings.section.assistant");
|
||||
return (
|
||||
<>
|
||||
<DynamicBreadcrumb />
|
||||
<Stack>
|
||||
<div>
|
||||
<Title order={1}>{t("title")}</Title>
|
||||
<Text c="dimmed" maw="70ch">
|
||||
{t("description")}
|
||||
</Text>
|
||||
</div>
|
||||
<AssistantConfiguration />
|
||||
</Stack>
|
||||
</>
|
||||
);
|
||||
}
|
||||
@@ -21,6 +21,7 @@ import {
|
||||
IconMailForward,
|
||||
IconPhotoFilled,
|
||||
IconPointerFilled,
|
||||
IconRobot,
|
||||
IconSearch,
|
||||
IconSettingsFilled,
|
||||
IconUserFilled,
|
||||
@@ -198,6 +199,12 @@ export default async function ManageLayout({ children }: PropsWithChildren) {
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
label: t("items.assistant"),
|
||||
href: "/manage/assistant",
|
||||
icon: IconRobot,
|
||||
hidden: !session?.user.permissions.includes("admin"),
|
||||
},
|
||||
{
|
||||
label: t("items.settings"),
|
||||
href: "/manage/settings",
|
||||
|
||||
@@ -259,7 +259,7 @@ export const AssistantProvider = ({ children }: PropsWithChildren) => {
|
||||
const t = useScopedI18n("common.assistant");
|
||||
const session = useSession();
|
||||
const [opened, setOpened] = useState(false);
|
||||
const { data } = clientApi.assistant.getAvailability.useQuery(undefined, {
|
||||
const { data, isLoading: isAvailabilityLoading } = clientApi.assistant.getAvailability.useQuery(undefined, {
|
||||
enabled: session.status === "authenticated",
|
||||
staleTime: 60_000,
|
||||
});
|
||||
@@ -268,19 +268,32 @@ export const AssistantProvider = ({ children }: PropsWithChildren) => {
|
||||
const open = useCallback(() => setOpened(true), []);
|
||||
const close = useCallback(() => setOpened(false), []);
|
||||
const toggle = useCallback(() => setOpened((current) => !current), []);
|
||||
useHotkeys([[hotkeys.openAssistant, open]]);
|
||||
const openIfEnabled = useCallback(() => {
|
||||
if (enabled) {
|
||||
open();
|
||||
}
|
||||
}, [enabled, open]);
|
||||
useHotkeys([[hotkeys.openAssistant, openIfEnabled]]);
|
||||
|
||||
const spotlightItem = useMemo(
|
||||
() => ({
|
||||
id: "homarr-assistant",
|
||||
name: t("spotlight"),
|
||||
icon: "/logo/logo.png",
|
||||
interaction: () => ({ type: "javaScript" as const, onSelect: open }),
|
||||
description: enabled
|
||||
? t("spotlightDescription")
|
||||
: session.status !== "authenticated"
|
||||
? t("unavailable.signIn")
|
||||
: isAvailabilityLoading
|
||||
? t("unavailable.checking")
|
||||
: t("unavailable.notConfigured"),
|
||||
unavailable: !enabled,
|
||||
interaction: () => (enabled ? { type: "javaScript" as const, onSelect: open } : { type: "none" as const }),
|
||||
}),
|
||||
[open, t],
|
||||
[enabled, isAvailabilityLoading, open, session.status, t],
|
||||
);
|
||||
useRegisterSpotlightContextResults("homarr-assistant", enabled ? [spotlightItem] : [], [enabled, spotlightItem]);
|
||||
useRegisterSpotlightContextActions("homarr-assistant", enabled ? [spotlightItem] : [], [enabled, spotlightItem]);
|
||||
useRegisterSpotlightContextResults("homarr-assistant", [spotlightItem], [spotlightItem]);
|
||||
useRegisterSpotlightContextActions("homarr-assistant", [spotlightItem], [spotlightItem]);
|
||||
|
||||
const value = useMemo(() => ({ enabled, opened, open, close, toggle }), [close, enabled, open, opened, toggle]);
|
||||
|
||||
|
||||
Reference in new issue
Block a user