docs: simplify assistant guides
This commit is contained in:
1 parent
1b658b631c
commit
3c6b2a5d49
2 files changed
+48
-72
No files matched your search
@@ -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.
|
||||||
|
|
||||||

|

|
||||||
|
|
||||||
## 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**.
|
||||||
|
|
||||||

|

|
||||||
|
|
||||||
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).
|
|
||||||
@@ -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 />
|
||||||
|
|
||||||
|
|||||||
Reference in new issue
Block a user