docs: simplify assistant guides

This commit is contained in:
ajnart committed 2026-08-14 11:32:11 +02:00
1 parent 1b658b631c
commit 3c6b2a5d49
2 files changed
+48 -72

No files matched your search

+34 -55
View File
@@ -8,82 +8,61 @@ tags:
# Assistant # Assistant
Homarr Assistant can answer questions about your Homarr instance and use Homarr tools on your behalf. It follows the Homarr Assistant can answer questions and manage Homarr for you. It uses the signed-in user's permissions and asks for
permissions of the signed-in user and asks for approval before it changes anything. approval before making changes.
![Homarr Assistant conversation with suggested prompts](/img/assistant/conversation.png) ![Homarr Assistant conversation with suggested prompts](/img/assistant/conversation.png)
## Open the assistant ## Set it up
- 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**. Open **Management → Assistant**.
![Assistant provider, credentials, and model configuration](/img/assistant/configuration.png) ![Assistant provider, credentials, and model configuration](/img/assistant/configuration.png)
1. Select a provider. 1. Select a provider and check its API URL.
2. Check the API base URL and add an API key if required. 2. Enter an API key when required, then save the connection.
3. Select **Save provider connection**. 3. Refresh the model list and select a model.
4. Refresh the model list and choose a model. 4. Enable the assistant and save.
5. Enable the assistant, then select **Save assistant**.
Homarr includes presets for OpenRouter, OpenAI, Claude, Gemini, xAI, Groq, Mistral, DeepSeek, Together AI, Ollama, and Choose a provider preset or use **Custom endpoint** with an OpenAI-compatible Chat Completions API. The
LM Studio. Use **Custom endpoint** for another OpenAI-compatible Chat Completions service. [Homarr provider](../workshop/homarr-provider) needs no administrator API key; users sign in to the Community Workshop
and receive a daily allowance.
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 :::info Local model servers
Inside a container, `localhost` means the Homarr container. Use the model server's container name, local DNS name, or Inside a container, `localhost` means the Homarr container. Use the model server's container name, local DNS name, or
host gateway address instead. host gateway address.
::: :::
## Approvals and data ## Use it
Read-only tools can run automatically. Changes show an approval card with the exact action before Homarr runs it. - Select **Assistant** in the user menu or press `Shift + A`.
Normal Homarr permissions still apply. - Ask from `Cmd/Ctrl + K`.
- Add the [Assistant widget](../widgets/assistant) to a board.
API keys and custom headers are encrypted in the Homarr database and are never returned to the browser. Prompts, The assistant can work with boards, apps, integrations, widgets, Custom Widgets, and connected services. Use `@` to
attachments, tool definitions, and tool results are sent to the configured model provider. Check that provider's data add Homarr items as context, `/` for shortcuts, and the paperclip for supported files.
policy before enabling the assistant.
Conversations are stored per user. Users can edit or retry messages, copy responses, export a conversation as Markdown, Each request includes the user's name, current page and board, home board, server time, browser time zone, and a small
and delete conversations. summary of accessible Homarr resources. Live status is fetched only when needed.
Each request includes the signed-in user's name, server time, current page and board, home board, browser time zone, ## Permissions and privacy
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 - Read-only actions can run automatically. Changes require approval.
- Homarr permissions apply to every tool call and mentioned item.
- API keys and custom headers are encrypted and never returned to the browser.
- Conversations are stored per user and can be exported or deleted.
Prompts, attachments, tool definitions, and tool results are sent to the selected model provider. Review that
provider's privacy policy before enabling the assistant.
## Troubleshooting
- **No models found:** check the base URL, model discovery path, and API key. You can enter a model ID manually. - **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. - **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. - **Tool calls stop:** select a model that supports streaming and tool calls.
- **A local endpoint cannot be reached:** check container networking and the endpoint's listen address. - **Local endpoint is unreachable:** check container networking and the server's listen address.
Homarr exposes its MCP-enabled procedures to external clients through the [MCP server](./mcp). MCP omits See [MCP](./mcp) for external AI clients and [Custom Widget agent authoring](./custom-widgets/agent-authoring) for the
`customWidget_*` tools for non-admin API keys, while the built-in assistant adds browser actions and optional widget authoring workflow.
OpenRouter web search. Custom Widget authors can find the full workflow in
[Agent authoring](./custom-widgets/agent-authoring).
+14 -17
View File
@@ -12,9 +12,8 @@ import { OpenCollectiveLink } from "@site/src/components/assistant-provider/open
# Homarr provider # Homarr provider
The Homarr provider gives Workshop users access to the **Homarr model** without an administrator API key. The Homarr The Homarr provider gives Community Workshop users access to the **Homarr model** without an administrator API key.
team selects a capable model based on quality, reliability, and cost, and can change the upstream model without The Homarr team chooses the upstream model based on quality, reliability, and cost.
changing the user-facing provider. Each user signs in with GitHub and receives a separate daily allowance.
## Set it up ## Set it up
@@ -26,27 +25,25 @@ changing the user-facing provider. Each user signs in with GitHub and receives a
## Daily allowance ## Daily allowance
- Each user starts with **50 request units per UTC day**. - Each user gets **50 request units per UTC day**.
- Each model request uses one unit. Agent tool loops can make multiple model requests. - Each model request uses one unit. A tool loop can use several units.
- Once Workshop forwards a request, it uses one unit even if the upstream later fails. This prevents failed requests - Forwarded requests count even if the model later fails.
from bypassing the shared cost and abuse limits. - Allowances reset at 00:00 UTC. A shared daily limit also applies.
- The allowance resets at 00:00 UTC.
The battery beside the model selector shows the remaining allowance and reset time. The Workshop server enforces the The battery beside the model selector shows the remaining allowance and reset time. Workshop enforces all limits on
limit before it sends a request to OpenRouter. its server; changing the browser clock cannot bypass them.
## Data and cost ## Privacy
The Workshop keeps the OpenRouter API key on its server. It does not send that key to Homarr or the browser. Workshop keeps the OpenRouter API key on its server. Homarr and the browser never receive it.
Prompts, attachments, tool definitions, and tool results are sent through OpenRouter to generate a response. The Prompts, attachments, tools, and tool results pass through Workshop and OpenRouter. Workshop does not retain this
Workshop proxy does not retain that content, responses, or per-request telemetry. It stores only the Workshop user, content or the responses. It stores only the user, UTC day, and counters needed to enforce allowances. OpenRouter is
UTC day, and counters required to enforce per-user and global daily allowances. Requests require OpenRouter routing configured for zero data retention with data collection disabled. Homarr does not use this content to train models.
with zero data retention and data collection disabled. Homarr does not use this content to train language models.
We would rather become millionaires in a more ethical manner. We would rather become millionaires in a more ethical manner.
The Homarr community pays for these requests. Donations help cover the cost. The community pays for these requests. Donations help cover the cost.
<OpenCollectiveLink /> <OpenCollectiveLink />