77 lines
3.6 KiB
Plaintext
77 lines
3.6 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 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.
|
|
|
|
:::
|