docs: simplify assistant guides
This commit is contained in:
ajnart committed
1 parent
1b658b631c
commit
3c6b2a5d49
2 files changed
+48
-72
No files matched your search
@@ -8,82 +8,61 @@ tags:
|
||||
|
||||
# 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.
|
||||
Homarr Assistant can answer questions and manage Homarr for you. It uses the signed-in user's permissions and asks for
|
||||
approval before making changes.
|
||||
|
||||
|
||||
|
||||
## 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
|
||||
## Set it up
|
||||
|
||||
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**.
|
||||
1. Select a provider and check its API URL.
|
||||
2. Enter an API key when required, then save the connection.
|
||||
3. Refresh the model list and select a model.
|
||||
4. Enable the assistant and save.
|
||||
|
||||
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.
|
||||
Choose a provider preset or use **Custom endpoint** with an OpenAI-compatible Chat Completions API. The
|
||||
[Homarr provider](../workshop/homarr-provider) needs no administrator API key; users sign in to the Community Workshop
|
||||
and receive a daily allowance.
|
||||
|
||||
:::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.
|
||||
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.
|
||||
Normal Homarr permissions still apply.
|
||||
- Select **Assistant** in the user menu or press `Shift + A`.
|
||||
- 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,
|
||||
attachments, tool definitions, and tool results are sent to the configured model provider. Check that provider's data
|
||||
policy before enabling the assistant.
|
||||
The assistant can work with boards, apps, integrations, widgets, Custom Widgets, and connected services. Use `@` to
|
||||
add Homarr items as context, `/` for shortcuts, and the paperclip for supported files.
|
||||
|
||||
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 user's name, current page and board, home board, server time, browser time zone, and a small
|
||||
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,
|
||||
and a bounded snapshot of the Homarr resources they can access. Live service and system status is loaded with tools
|
||||
only when needed.
|
||||
## Permissions and privacy
|
||||
|
||||
## 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.
|
||||
- **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.
|
||||
- **Assistant is unavailable:** enable it and save the configuration.
|
||||
- **Tool calls stop:** select a model that supports streaming and tool calls.
|
||||
- **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
|
||||
`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).
|
||||
See [MCP](./mcp) for external AI clients and [Custom Widget agent authoring](./custom-widgets/agent-authoring) for the
|
||||
widget authoring workflow.
|
||||
@@ -12,9 +12,8 @@ import { OpenCollectiveLink } from "@site/src/components/assistant-provider/open
|
||||
|
||||
# Homarr provider
|
||||
|
||||
The Homarr provider gives Workshop users access to the **Homarr model** without an administrator API key. The Homarr
|
||||
team selects a capable model based on quality, reliability, and cost, and can change the upstream model without
|
||||
changing the user-facing provider. Each user signs in with GitHub and receives a separate daily allowance.
|
||||
The Homarr provider gives Community Workshop users access to the **Homarr model** without an administrator API key.
|
||||
The Homarr team chooses the upstream model based on quality, reliability, and cost.
|
||||
|
||||
## Set it up
|
||||
|
||||
@@ -26,27 +25,25 @@ changing the user-facing provider. Each user signs in with GitHub and receives a
|
||||
|
||||
## Daily allowance
|
||||
|
||||
- Each user starts with **50 request units per UTC day**.
|
||||
- Each model request uses one unit. Agent tool loops can make multiple model requests.
|
||||
- Once Workshop forwards a request, it uses one unit even if the upstream later fails. This prevents failed requests
|
||||
from bypassing the shared cost and abuse limits.
|
||||
- The allowance resets at 00:00 UTC.
|
||||
- Each user gets **50 request units per UTC day**.
|
||||
- Each model request uses one unit. A tool loop can use several units.
|
||||
- Forwarded requests count even if the model later fails.
|
||||
- Allowances reset at 00:00 UTC. A shared daily limit also applies.
|
||||
|
||||
The battery beside the model selector shows the remaining allowance and reset time. The Workshop server enforces the
|
||||
limit before it sends a request to OpenRouter.
|
||||
The battery beside the model selector shows the remaining allowance and reset time. Workshop enforces all limits on
|
||||
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
|
||||
Workshop proxy does not retain that content, responses, or per-request telemetry. It stores only the Workshop user,
|
||||
UTC day, and counters required to enforce per-user and global daily allowances. Requests require OpenRouter routing
|
||||
with zero data retention and data collection disabled. Homarr does not use this content to train language models.
|
||||
Prompts, attachments, tools, and tool results pass through Workshop and OpenRouter. Workshop does not retain this
|
||||
content or the responses. It stores only the user, UTC day, and counters needed to enforce allowances. OpenRouter is
|
||||
configured for zero data retention with data collection disabled. Homarr does not use this content to train models.
|
||||
|
||||
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 />
|
||||
|
||||
|
||||
Reference in new issue
Block a user