192 lines
13 KiB
Plaintext
192 lines
13 KiB
Plaintext
---
|
|
tags:
|
|
- Assistant
|
|
- AI
|
|
- Administration
|
|
- Security
|
|
---
|
|
|
|
# Assistant
|
|
|
|
Administrators can configure the instance-wide AI assistant from **Management → Assistant**.
|
|
It is available to signed-in users from the user menu, with `Shift + A`, and from the
|
|
`Cmd/Ctrl + K` command menu. **Ask Homarr Assistant** is always available as a local result in the default
|
|
search. Selecting it with an existing query sends that query in the background; selecting it without a
|
|
query turns the command-menu search field into a prompt composer. Press
|
|
`Enter` to send the prompt in the background without opening the conversation. The search field receives
|
|
focus whenever the command menu opens, including when it is opened by an assistant tool. Sending from the
|
|
command menu preserves any draft in the expanded conversation. The local result is temporarily disabled while
|
|
the assistant is responding or waiting for an approval.
|
|
|
|
While a response is running, a compact activity bar appears at the bottom of the page and the user-menu
|
|
avatar shows a thinking indicator. The activity bar can be opened to follow the response. Completed
|
|
responses add an unread count to the user menu until they are opened or dismissed. The expanded
|
|
conversation has a minimize action that returns it to the activity bar without interrupting a response.
|
|
|
|
`Shift + A` opens the compact conversation panel directly. The shortcut is ignored while typing in text
|
|
fields, selectors, and editable content.
|
|
|
|
The **Assistant** board widget embeds the same persisted conversation and full interaction surface directly
|
|
on a dashboard. By default it follows the current conversation. Widget settings can instead pin a specific
|
|
conversation; the conversation picker stays hidden until **Pinned conversation** is selected.
|
|
|
|
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.
|
|
|
|
The management page presents setup as three compact sections: provider and endpoint, credentials, then
|
|
model and availability. A status summary at the top shows whether the connection is ready, whether a key
|
|
is protected, which model is selected, and whether users can open the assistant.
|
|
|
|
1. Choose a provider preset or **Custom endpoint**, then confirm the API base URL. It usually ends in `/v1`.
|
|
2. Add an API key if the service requires bearer authentication. Additional authentication or routing
|
|
headers are available in the collapsed advanced section.
|
|
3. Save the provider connection.
|
|
4. Refresh the model list and select a discovered model. Homarr displays the friendly model name but
|
|
stores and sends the provider's exact model ID.
|
|
5. 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 when discovery is
|
|
disabled, unavailable, or returns no models.
|
|
|
|
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.
|
|
|
|
When a key is already stored, the page shows its protected state instead of an ambiguous empty password
|
|
field. **Replace key** starts a two-step flow: enter the new key, then review the provider, destination,
|
|
and impact before confirming. The existing key remains active until confirmation, and its value cannot be
|
|
restored after replacement. Removing only the API key also requires explicit confirmation. **Remove all
|
|
credentials** uses a separate destructive confirmation because it also clears the selected model and
|
|
disables the assistant.
|
|
|
|
:::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. The assistant stays out of the
|
|
page layout until it is opened. Users can start, revisit, and delete conversations from the
|
|
conversation menu in the floating panel.
|
|
|
|
Messages support copy, edit-and-resend, response regeneration and branch navigation, Markdown export,
|
|
and helpful/not-helpful feedback.
|
|
Selecting text in a message exposes a quote action that carries the selected passage into the next prompt.
|
|
Files returned by a compatible model can be downloaded directly from the message.
|
|
Assistant responses render GitHub-flavored Markdown, including headings, links, lists, task lists, tables,
|
|
quotes, inline code, and fenced code blocks. Line breaks are preserved, and Homarr repairs common streamed
|
|
responses where a provider returns escaped line breaks or places a bold-label list on one line.
|
|
Images up to 1 MB and text, Markdown, CSV, HTML, XML, or JSON documents up to 350 KB can be attached by
|
|
using the paperclip or dropping files onto the composer. A request can contain up to five attachments.
|
|
Image understanding depends on the selected model; document text is extracted locally by Homarr and sent
|
|
as part of the prompt.
|
|
|
|
Type `@` in the composer to add permission-checked context. The nested menu contains apps, integrations,
|
|
boards, widgets, and tools available to the current user. Homarr validates every referenced ID again on
|
|
the server before adding it to the model context. Type `/` for common prompt shortcuts. Both menus support
|
|
keyboard navigation and keep the active result visible while moving through long lists. The joined
|
|
controls below the composer open a searchable model picker and the thinking-level menu. Model selection
|
|
is stored on the conversation after a completed request. Thinking mode can be left on **Auto**, disabled,
|
|
or set from minimal through high; explicit levels are sent using the AI SDK's provider-neutral reasoning
|
|
setting and still depend on support from the chosen model and endpoint.
|
|
|
|
Each completed response includes a circular context-window meter. Select it to open request details when
|
|
the provider reports them: input, output, cached-input and reasoning tokens, used and remaining context,
|
|
time to first output, total duration, output speed, agent-step timing, and cost. OpenRouter-reported cost
|
|
is labeled as reported.
|
|
OpenRouter responses request inline usage and routing metadata. When request details are opened, Homarr also
|
|
loads the server-side generation record for each model step and briefly polls while OpenRouter finishes
|
|
processing it. The details separate Homarr's end-to-end timing from OpenRouter's provider latency,
|
|
generation time, and provider throughput, and can include normalized and native token counts, moderation
|
|
latency, cache discount, fallback count, service tier, data region, BYOK status, routed provider, generation
|
|
identifier, exact cost, and upstream inference cost. Provider credentials remain server-side; the browser
|
|
can request only generation identifiers already stored on a conversation owned by the signed-in user and
|
|
signed by the Homarr server for that user and conversation. Successful generation lookups are cached
|
|
briefly so polling and multi-step requests do not repeatedly query OpenRouter for the same record.
|
|
When a provider omits cost but model discovery includes prompt and completion pricing, Homarr labels the
|
|
calculated value as estimated. Missing provider data is shown as not reported rather than inferred.
|
|
|
|
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. The approval appears as a large **Approve and run** or **Deny** action;
|
|
the assistant does not require a second typed confirmation first. Tool cards expose their status, timing,
|
|
validated input, result, and error state without flooding the conversation with raw JSON by default.
|
|
Common collection and widget results are summarized inline as compact responsive cards, while the full
|
|
structured result remains available in the tool card details.
|
|
|
|
The shield control in the conversation header can enable automatic approvals for the current conversation.
|
|
While enabled, Homarr accepts every affirmative approval step as it arrives: protected mutations are approved,
|
|
presented app details and board changes are used, and structured questions with an explicitly categorized
|
|
**Confirm** answer choose that answer. Neutral choices such as selecting a board still wait for input because
|
|
they do not have a safe affirmative default. Automatic approvals turn off when you switch conversations, and
|
|
the shared approval tracker prevents the same call from being handled twice when both a board widget and the
|
|
floating assistant are visible.
|
|
|
|
When the assistant genuinely needs missing information or a choice, it can pause with a structured
|
|
question. Each proposed answer is visibly categorized as **Confirm**, **Decline**, or **Option**, so the effect
|
|
of automatic approval is unambiguous. Users can select one of the proposed answers or choose **Other** and
|
|
enter their own response. While a question is unanswered, its controls stay in a dedicated area immediately
|
|
above the composer instead of requiring the user to find the tool call in the transcript. The answered choice
|
|
then remains in the conversation history.
|
|
Submitting the answer resumes the same agent run automatically. The minimized activity bar shows the
|
|
question or approval that needs attention and opens directly back to the request. While an answer, app
|
|
form, or mutation approval is pending, the composer preserves its draft but does not replace the pending
|
|
tool call with a new message. If the provider stops before an interactive tool supplies complete arguments,
|
|
Homarr replaces the loading state with an explicit error and confirms that no change was made.
|
|
|
|
App creation uses Homarr's native app form inside the conversation. The form reuses the local icon picker,
|
|
including automatic matching and searches through the `icon.findIcons` procedure, before the final
|
|
`app.create` approval is requested. App fields are filled only after the complete tool input has arrived, so
|
|
streaming partial arguments cannot replace the proposed values with empty fields. The model is instructed not
|
|
to invent external icon CDN URLs.
|
|
|
|
Board appearance changes use a similar review flow. The assistant first reads the board's current settings,
|
|
including its complete custom stylesheet, and then opens an editable form with Custom CSS, Appearance,
|
|
Background, and General tabs. The form highlights how many fields were proposed, preserves settings the
|
|
assistant did not change, and returns only values that differ from the current board. Custom CSS can be
|
|
copied or restored before continuing, and Homarr warns when it contains an imported stylesheet or remote
|
|
resource URL. Continuing from the form opens the normal mutation approval before anything is saved.
|
|
|
|
Ask for changes such as “make the cards denser on my Home board,” “add a mobile CSS rule without removing
|
|
my existing styles,” or “change the board colors and disable app status checks.” The current user must have
|
|
modify permission on the selected board. The empty conversation includes an **Improve a dashboard** starter,
|
|
and `/style` prepares the same guided workflow from the composer.
|
|
|
|
Homarr also exposes a small set of browser-only actions to the assistant. These actions can navigate to
|
|
safe internal routes, refresh the current view, 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.
|
|
|
|
After an approved mutation completes, Homarr automatically refetches active page and dashboard data so
|
|
board items, settings, custom CSS, apps, and other visible results update without a full browser reload.
|
|
The refresh action in the conversation header performs the same safe refetch manually. It keeps the
|
|
conversation open while refreshing both client queries and server-rendered route data.
|
|
|
|
:::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.
|
|
|
|
:::
|