90 lines
4.0 KiB
Plaintext
90 lines
4.0 KiB
Plaintext
---
|
|
description: Configure and use Homarr Assistant.
|
|
tags:
|
|
- Assistant
|
|
- AI
|
|
- Administration
|
|
---
|
|
|
|
# Assistant
|
|
|
|
Homarr Assistant can answer questions about your Homarr instance and use Homarr tools on your behalf. It follows the
|
|
permissions of the signed-in user and asks for approval before it changes anything.
|
|
|
|
|
|
|
|
## Open the assistant
|
|
|
|
- Select **Assistant** in the user menu.
|
|
- Press `Shift + A` from anywhere in Homarr.
|
|
- Type a question in `Cmd/Ctrl + K`, then select **Ask Homarr Assistant**.
|
|
- Add the **Assistant** widget to a board for a permanent conversation view.
|
|
|
|
You can minimize a conversation while it works. The activity bar shows its progress and the user menu shows unread
|
|
responses.
|
|
|
|
## What it can do
|
|
|
|
- Find and update boards, apps, integrations, widgets, and dashboard settings.
|
|
- Check downloads, media, Docker containers, service health, and other connected integrations.
|
|
- Create formatted notes and Custom Widgets.
|
|
- Search the web when OpenRouter web search is enabled.
|
|
- Show tool activity, reasoning summaries, usage, time, and cost when the provider reports them.
|
|
|
|
Use `@` to add an app, board, integration, widget, or tool as context. Use `/` for common prompts. You can also paste or
|
|
attach images and text files when the selected model supports them.
|
|
|
|
## Configure the assistant
|
|
|
|
Open **Management → Assistant**.
|
|
|
|
|
|
|
|
1. Select a provider.
|
|
2. Check the API base URL and add an API key if required.
|
|
3. Select **Save provider connection**.
|
|
4. Refresh the model list and choose a model.
|
|
5. Enable the assistant, then select **Save assistant**.
|
|
|
|
Homarr includes presets for OpenRouter, OpenAI, Claude, Gemini, xAI, Groq, Mistral, DeepSeek, Together AI, Ollama, and
|
|
LM Studio. Use **Custom endpoint** for another OpenAI-compatible Chat Completions service.
|
|
|
|
The [Homarr provider](../workshop/homarr-provider) does not require an administrator API key. Each user signs in to the
|
|
Community Workshop and receives a separate daily allowance. A shared Workshop daily quota also applies, so requests
|
|
can be rejected after that shared quota is exhausted.
|
|
|
|
:::info Local model servers
|
|
|
|
Inside a container, `localhost` means the Homarr container. Use the model server's container name, local DNS name, or
|
|
host gateway address instead.
|
|
|
|
:::
|
|
|
|
## Approvals and data
|
|
|
|
Read-only tools can run automatically. Changes show an approval card with the exact action before Homarr runs it.
|
|
Normal Homarr permissions still apply.
|
|
|
|
API keys and custom headers are encrypted in the Homarr database and are never returned to the browser. Prompts,
|
|
attachments, tool definitions, and tool results are sent to the configured model provider. Check that provider's data
|
|
policy before enabling the assistant.
|
|
|
|
Conversations are stored per user. Users can edit or retry messages, copy responses, export a conversation as Markdown,
|
|
and delete conversations.
|
|
|
|
Each request includes the signed-in user's name, server time, current page and board, home board, browser time zone,
|
|
and a bounded snapshot of the Homarr resources they can access. Live service and system status is loaded with tools
|
|
only when needed.
|
|
|
|
## If setup does not work
|
|
|
|
- **No models found:** check the base URL, model discovery path, and API key. You can enter a model ID manually.
|
|
- **The assistant is unavailable:** enable it and save the configuration.
|
|
- **A model stops during a tool call:** use a model that supports streaming and structured tool calls.
|
|
- **A local endpoint cannot be reached:** check container networking and the endpoint's listen address.
|
|
|
|
Homarr exposes its MCP-enabled procedures to external clients through the [MCP server](./mcp). MCP omits
|
|
`customWidget_*` tools for non-admin API keys, while the built-in assistant adds browser actions and optional
|
|
OpenRouter web search. Custom Widget authors can find the full workflow in
|
|
[Agent authoring](./custom-widgets/agent-authoring).
|