114 lines
6.5 KiB
Plaintext
114 lines
6.5 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 and the `Cmd/Ctrl + K` command menu. Selecting
|
|
**Ask Homarr Assistant** in the command menu turns its search field into a prompt composer. Press
|
|
`Enter` to send the prompt in the background without opening the conversation.
|
|
|
|
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.
|
|
|
|
`Cmd/Ctrl + Shift + K` opens the compact conversation panel 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 and select a discovered model. Homarr displays the friendly model name but
|
|
stores and sends the provider's exact model ID.
|
|
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 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.
|
|
|
|
:::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,
|
|
helpful/not-helpful feedback, text-to-speech, and browser speech dictation when the browser supports it.
|
|
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.
|
|
|
|
Each completed response includes expandable request details when the provider reports them: input,
|
|
output, cached-input and reasoning tokens, context-window utilization, time to first output, total
|
|
duration, output speed, agent-step timing, and cost. OpenRouter-reported cost is labeled as reported.
|
|
OpenRouter responses also show the routed provider, generation identifier, and upstream inference cost when
|
|
the endpoint supplies those fields.
|
|
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. 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.
|
|
|
|
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.
|
|
|
|
:::
|