diff --git a/apps/docs/docs/management/assistant.mdx b/apps/docs/docs/management/assistant.mdx
index 9d544fe60..eda61c6d7 100644
--- a/apps/docs/docs/management/assistant.mdx
+++ b/apps/docs/docs/management/assistant.mdx
@@ -1,312 +1,82 @@
---
+description: Configure and use Homarr Assistant.
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 user menu, with `Shift + A`, and from the
-`Cmd/Ctrl + K` command menu. **Ask Homarr Assistant** is always available as a local result in the default
-search. Selecting it with an existing query sends that query in the background; selecting it without a
-query turns the command-menu search field into a prompt composer. Press
-`Enter` to send the prompt in the background without opening the conversation. The search field receives
-focus whenever the command menu opens, including when it is opened by an assistant tool. Sending from the
-command menu preserves any draft in the expanded conversation. The local result is temporarily disabled while
-the assistant is responding or waiting for an approval.
+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.
-While a response is running, a compact activity bar appears at the bottom of the page and the user-menu
-avatar shows a thinking indicator. The activity bar can be opened to follow the response. Completed
-responses add an unread count to the user menu until they are opened or dismissed. The expanded
-conversation has a minimize action that returns it to the activity bar without interrupting a response.
-Its adjacent close action hides the panel without leaving an activity bar behind. Both window actions use
-subtle buttons with an icon, tooltip, and accessible label.
-The transcript follows streamed output while it is already at the bottom, including fast responses. Scrolling
-up releases that follow state until **Scroll to latest** is selected or the user returns to the bottom.
+
-`Shift + A` opens the compact conversation panel directly. The shortcut is ignored while typing in text
-fields, selectors, and editable content.
+## Open the assistant
-The **Assistant** board widget embeds the same persisted conversation and full interaction surface directly
-on a dashboard. By default it follows the current conversation. Widget settings can instead pin a specific
-conversation; the conversation picker stays hidden until **Pinned conversation** is selected.
-The Shift+A panel is non-modal: opening it focuses its composer, but it does not capture focus from the board.
-Users can continue typing in an Assistant widget or interacting with other dashboard controls while the panel
-is open. Every visible assistant surface keeps its own draft, attachment list, selection, and focus while sharing
-the same persisted conversation. Switching conversations restores the draft that belongs to that surface and
-conversation instead of copying text into another widget or the floating panel.
+- 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.
-When the assistant is unavailable, its command-menu result remains visible but disabled and explains that
-an administrator must configure and enable it.
+You can minimize a conversation while it works. The activity bar shows its progress and the user menu shows unread
+responses.
-The assistant uses the assistant-ui runtime for **AI SDK v7**. Homarr tracks the newest mutually compatible
-package set permitted by its supply-chain release-age policy. Persisted message rows can still report the upstream
-codec name `ai-sdk/v6`; assistant-ui's current v7 adapter deliberately retains that identifier for its compatible
-UI-message wire format. It does not mean the application is running AI SDK v6.
+## What it can do
-## Configure a model provider
+- 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.
-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.
+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.
-The **Homarr provider** offers one community-funded model, DeepSeek V4 Flash Latest, without an administrator API key.
-Users authorize it with their existing Community Workshop GitHub session. A compact battery beside the model selector
-shows their remaining daily request allowance and the UTC reset time. See
-[Homarr provider](../workshop/homarr-provider) for its
-quota, privacy, live activity, and funding details.
+## Configure the assistant
-The management page presents setup as three compact sections: provider and endpoint, credentials, then
-model and availability. A status summary at the top shows whether the connection is ready, whether a key
-is protected, and which model is selected. Redundant active-state badges are omitted when the setup is ready.
+Open **Management → Assistant**.
-1. Choose a provider preset or **Custom endpoint**, then confirm the API base URL. It usually ends in `/v1`.
-2. Add an API key if the service requires bearer authentication. Additional authentication or routing
- headers are available in the collapsed advanced section.
-3. Save the provider connection.
-4. Refresh the model list and select a discovered model. Homarr displays the friendly model name but
- stores and sends the provider's exact model ID. Context-window sizes use compact labels such as `1M`.
-5. 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 when discovery is
-disabled, unavailable, or returns no models.
+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**.
-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. This prevents credentials for one service from being sent
-to another endpoint.
+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.
-When a key is already stored, the page shows its protected state instead of an ambiguous empty password
-field. Removing the API key requires explicit confirmation. Save that removal before entering and saving a
-different key.
+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.
-:::info Container networking
+:::info Local model servers
-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.
+Inside a container, `localhost` means the Homarr container. Use the model server's container name, local DNS name, or
+host gateway address instead.
:::
-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.
+## Approvals and data
-OpenRouter web search is an opt-in option in the model section. It registers OpenRouter's model-callable
-[`openrouter:web_search` server tool](https://openrouter.ai/docs/guides/features/server-tools/web-search)
-alongside Homarr's tools, so OpenRouter performs each search without
-exposing the stored credential to the browser. The model decides when live research is needed and can use the
-grounded results and source links in responses or dashboard notes. Homarr limits each assistant request to
-three searches with five results per search. OpenRouter charges web-search usage separately from model tokens.
-Completed responses show a compact web-search activity card when OpenRouter reports search usage. OpenRouter
-does not expose these server-side searches as ordinary client-executed tool calls, so Homarr shows the reported
-search count and the safe title and URL from each returned `url_citation` annotation instead. Citation excerpts
-stay in the provider response and are not persisted in the activity card.
+Read-only tools can run automatically. Changes show an approval card with the exact action before Homarr runs it.
+Normal Homarr permissions still apply.
-The option is also available for custom endpoints that forward OpenRouter's server-tools request format. This
-supports OpenRouter proxies, including the future Homarr Router provider. Leave it disabled for ordinary
-OpenAI-compatible endpoints because the `openrouter:*` tool type is not part of the standard OpenAI API.
+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 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 are stored per user. Users can edit or retry messages, copy responses, export a conversation as Markdown,
+and delete conversations.
-## Conversations and tools
+## If setup does not work
-Conversations and messages are stored per user in the Homarr database. The assistant stays out of the
-page layout until it is opened. Users can start, revisit, and delete conversations from the
-conversation menu in the floating panel.
+- **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.
-Messages support copy, edit-and-resend, response regeneration and branch navigation, Markdown export,
-and helpful/not-helpful feedback. The conversation menu also provides a compact export action beside delete for
-each conversation. Its debugging-oriented Markdown includes every stored user, assistant, reasoning, tool, error,
-branch-parent, and server-metadata record while redacting secret-looking fields and embedded attachment data.
-The per-response export uses the same tool-aware format instead of assistant-ui's text-only copy representation.
-Selecting text in a message exposes a quote action that carries the selected passage into the next prompt.
-Files returned by a compatible model can be downloaded directly from the message.
-Assistant responses render GitHub-flavored Markdown, including headings, links, lists, task lists, tables,
-quotes, inline code, and fenced code blocks. Line breaks are preserved, and Homarr repairs common streamed
-responses where a provider returns escaped line breaks or places a bold-label list on one line.
-Completed fenced code blocks use language-aware syntax highlighting; a streaming block stays plain until its
-content is stable. Safe same-origin links are prefetched and use client-side navigation, so opening a returned
-preview, editor, board, or other Homarr item does not unload the assistant. External links keep their normal
-external-browser behavior.
-Fenced `mermaid` blocks render as diagrams in the current color scheme using Mermaid's strict security mode;
-invalid diagrams fall back to their source instead of breaking the response.
-When Homarr's icon search returns an image URL, visual result tables render that actual icon in a compact
-image column instead of substituting an emoji. Assistant-provided Markdown images accept safe relative,
-HTTP, and HTTPS sources and load without forwarding the Homarr page as the referrer. Image message parts
-render through assistant-ui's image primitive in a bounded responsive preview with an accessible loading state,
-a filename caption when available, and an in-place retry when the source fails.
-Images up to 1 MB and text, Markdown, CSV, HTML, XML, or JSON documents up to 350 KB can be attached by
-using the paperclip, dropping files onto the composer, or pasting an image with `Cmd/Ctrl + V`. Attachment
-previews stay local to the composer where they were added and show upload state, file type, and a removable image
-thumbnail or document tile. A request can contain up to five attachments.
-Image understanding depends on the selected model; document text is extracted locally by Homarr and sent
-as part of the prompt.
-
-Type `@` in the composer to add permission-checked context. The nested menu contains apps, integrations,
-boards, widgets, and tools available to the current user. Homarr validates every referenced ID again on
-the server before adding it to the model context. Selected references appear as compact, typed pills in the
-composer and sent message, while preserving assistant-ui's underlying directive syntax for the model. When the
-assistant cites one of those references in its own response, Homarr renders the same typed pill and uses the
-stored app or integration icon when one is available. Type `/`
-for common prompt shortcuts. Both menus support keyboard navigation and keep the active result visible while
-moving through long lists. The selector below the composer combines searchable, provider-grouped models with
-their description, context size and image-input capability, plus the thinking-level control. Model selection is
-stored on the conversation after a completed request. Thinking mode can be left on **Auto**, disabled, or set
-from minimal through high; explicit levels are sent using the AI SDK's provider-neutral reasoning setting and
-still depend on support from the chosen model and endpoint. Reasoning text is shown live when the provider streams
-it through assistant-ui's grouped-parts and chain-of-thought primitives. The compact **Thinking** trace groups
-adjacent reasoning with ordinary tool calls, shows each tool's status, duration and safe human-readable target,
-and expands raw input, output and result previews only on request. Approval and question tools remain full-width
-outside the trace. The disclosure renders Markdown, can be opened or closed without interrupting the response,
-and keeps the user's collapsed state when another message starts. A compact dot matrix distinguishes an initial
-thinking pass from response streaming and settles into waiting, success, or error states in the minimized activity
-bar. The state always keeps its text label, and the animation is disabled when the operating system requests
-reduced motion.
-
-A circular context ring beside the model selector gives a quick glance at cumulative conversation usage without
-expanding the composer toolbar. Its accessible label includes cumulative tokens and cost when available, while
-its popover keeps the latest complete context reading as a new response starts and lists every request
-turn with its model, provider, input, output, cached-input and reasoning tokens, context use, duration, speed,
-agent steps, routing details, and cost when reported. Before usage is available, the control remains a compact
-ring instead of showing a redundant missing-data label. Closing and reopening the popover reads persisted
-conversation metadata instead of resetting the display to zero. A larger ring inside the popover breaks the latest
-reported context into used, remaining and total capacity plus input, cached-input, output and reasoning tokens.
-
-Each assistant response places a small provider logo in the same stable action toolbar as copy, export,
-feedback, and regenerate. Hovering the logo shows the provider, exact model, timing, throughput, and cost without
-adding another metadata row to the transcript. Branch navigation occupies its own adjacent group, so switching
-between response versions never pushes the response actions off-screen.
-
-OpenRouter responses request inline usage and routing metadata. Opening detailed turn data also loads the
-server-side generation record for its model steps and briefly polls while OpenRouter finishes processing it.
-The details separate Homarr's end-to-end timing from OpenRouter's provider latency, generation time, and provider
-throughput, and can include normalized and native token counts, moderation latency, cache discount, fallback count,
-service tier, data region, BYOK status, routed provider, generation identifier, exact cost, and upstream inference
-cost. Provider credentials remain server-side; the browser can request only generation identifiers already stored
-on a conversation owned by the signed-in user and signed by the Homarr server for that user and conversation.
-Successful generation lookups are cached briefly so polling and multi-step requests do not repeatedly query
-OpenRouter for the same record.
-When a provider omits cost but model discovery includes prompt and completion pricing, Homarr labels the
-calculated value as estimated. Missing provider data is shown as not reported rather than inferred.
-
-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. The approval appears as a large **Approve and run** or **Deny** action;
-the assistant does not require a second typed confirmation first. Tool cards expose their status, timing,
-validated input, result, and error state without flooding the conversation with raw JSON by default.
-Common collection and widget results are summarized inline as compact responsive cards, while the full
-structured result remains available in the tool card details. Icon searches show the returned image variants,
-file formats, and repositories instead of the size of the complete icon catalog. Their trace uses a readable
-activity such as **Looking for “homarr” icons** instead of exposing the internal MCP procedure name.
-
-Large tool-driven requests can use up to 32 agent steps and a larger response budget within one request, so
-multi-item dashboard changes normally finish without requiring a follow-up “Continue” message. OpenRouter calls
-Homarr tools sequentially to prevent routed models from interleaving or truncating parallel JSON arguments, while
-every mutation still pauses for its normal approval. A safely recoverable truncated icon-search object is repaired
-before validation; incomplete search strings and all mutation inputs are never guessed.
-Homarr also normalizes internal tool results to the model's JSON-compatible message format before continuing an
-agent loop. Rich server values such as dates cannot invalidate the next model step, and an interrupted tool call
-without a result is omitted when the conversation resumes instead of making the entire prompt fail.
-
-The assistant can create a formatted dashboard note by adding a **Notebook** widget. Ask it for a note with
-headings, lists, tasks, links, emphasis, tables, or images; it generates compatible rich-text content, shows
-the native widget configuration form and standard mutation approval, then places the widget in the next
-available dashboard position. The generated content is retained even though the Notebook content field is
-normally hidden from widget settings.
-
-Automatic placement checks every responsive layout and treats both widgets and complete container footprints
-as occupied. New assistant-created items use the first free position in the main canvas instead of overlapping
-existing content or being placed in a gutter.
-
-Every assistant-created dashboard widget now passes through Homarr's native widget editor before it is added.
-The form fills widget defaults, validates widget-specific options, and only offers compatible integrations that
-the current user can use. Required integrations cannot be left empty, single-integration widgets cannot receive
-multiple integrations, and the reviewed values are passed unchanged into the final approval-gated mutation.
-
-Custom-widget tools let an administrator list, inspect, create, and update definitions. The custom-widget
-form's **Design with AI** action sends a focused request into the current conversation, where the assistant
-can propose the matching mutation and use the same approval controls. Existing stored secret values are
-reported only as configured/not configured and are preserved on update unless replacements are explicitly
-provided. For Custom Widget requests, Homarr lazily adds the complete installed skill, all bundled schema,
-runtime and security references, and the current JSON Schema to the trusted authoring context. This avoids an
-extra provider round trip for the large `customWidget_getSkill` and `customWidget_schema` results. If the model
-discovers the Custom Widget workflow mid-response, Homarr promotes the same resources before its next step and
-removes the now-redundant resource calls from provider history. Multiline JSX uses `templateLines` to avoid fragile
-streamed JSON escaping. Custom Widget authoring tools are mandatory: the assistant validates the complete candidate,
-creates a preview from that exact version, executes every returned preview query, checks the actual HTTP status and
-response shape, and repeats the entire validation and preview sequence after any material JSX, request, source, option,
-or binding change. It only reports a widget as validated, working, created, or placed when the corresponding tool result
-proves that checkpoint. Large widgets are saved from the exact final tested preview session, so the approved create step
-does not stream the complete JSX a second time. When the request already names a board, that board is carried into the
-create result and placement continues without asking the user to select it again. Preview and saved-definition results
-include safe Homarr paths that open in the assistant without a page reload. When placement is still a choice, the
-assistant uses the structured question UI instead of ending with a prose question.
-
-The authoring phase limits broad component-document retrieval and then moves into validation with the smallest useful
-reference set. Supplied samples and successful preview responses are treated as binding contracts: the assistant is
-instructed to render the requested fields, guard optional nested data, preserve every returned item, expose freshness
-when timestamps are available, and provide a refresh path for recoverable empty or error states.
-
-The shield control in the conversation header can enable automatic approvals for the current conversation.
-While enabled, Homarr accepts every affirmative approval step as it arrives: protected mutations are approved,
-presented app details and board changes are used, and structured questions with an explicitly categorized
-**Confirm** answer choose that answer. Neutral choices such as selecting a board still wait for input because
-they do not have a safe affirmative default. Automatic approvals turn off when you switch conversations, and
-the shared approval tracker prevents the same call from being handled twice when both a board widget and the
-floating assistant are visible.
-
-When the assistant genuinely needs missing information or a choice, it can pause with a structured
-question. Each proposed answer is visibly categorized as **Confirm**, **Decline**, or **Option**, so the effect
-of automatic approval is unambiguous. Users can select one of the proposed answers or choose **Other** and
-enter their own response. While a question is unanswered, its controls stay in a dedicated area immediately
-above the composer instead of requiring the user to find the tool call in the transcript. The question temporarily
-uses the available conversation body, with its own scrolling when necessary, rather than squeezing a long option
-list into a short dock beside part of the transcript. The answered choice then remains in the conversation history.
-Submitting the answer resumes the same agent run automatically. The minimized activity bar shows the
-question or approval that needs attention and opens directly back to the request. While an answer, app
-form, or mutation approval is pending, the composer preserves its draft but does not replace the pending
-tool call with a new message. If the provider stops before an interactive tool supplies complete arguments,
-Homarr replaces the loading state with an explicit error and confirms that no change was made.
-
-App creation uses Homarr's native app form inside the conversation. The form reuses the local icon picker,
-including automatic matching and searches through the `icon.findIcons` procedure, before the final
-`app.create` approval is requested. App fields are filled only after the complete tool input has arrived, so
-streaming partial arguments cannot replace the proposed values with empty fields. The model is instructed not
-to invent external icon CDN URLs.
-
-Board appearance changes use a similar review flow. The assistant first reads the board's current settings,
-including its complete custom stylesheet, and then opens an editable form with Custom CSS, Appearance,
-Background, and General tabs. The form highlights how many fields were proposed, preserves settings the
-assistant did not change, and returns only values that differ from the current board. Custom CSS can be
-copied or restored before continuing, and Homarr warns when it contains an imported stylesheet or remote
-resource URL. Continuing from the form opens the normal mutation approval before anything is saved.
-
-Ask for changes such as “make the cards denser on my Home board,” “add a mobile CSS rule without removing
-my existing styles,” or “change the board colors and disable app status checks.” The current user must have
-modify permission on the selected board. The empty conversation includes an **Improve a dashboard** starter,
-and `/style` prepares the same guided workflow from the composer.
-
-Homarr also exposes a small set of browser-only actions to the assistant. These actions can navigate to
-safe internal routes, refresh the current view, 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.
-
-After an approved mutation completes, Homarr automatically refetches active page and dashboard data so
-board items, settings, custom CSS, apps, and other visible results update without a full browser reload.
-The refresh action in the conversation header performs the same safe refetch manually. It keeps the
-conversation open while refreshing both client queries and server-rendered route data.
-
-:::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.
-
-:::
+Homarr exposes the same tool set to external clients through the [MCP server](./mcp). Custom Widget authors can find
+the full workflow in [Agent authoring](./custom-widgets/agent-authoring).
diff --git a/apps/docs/docs/workshop/homarr-provider.mdx b/apps/docs/docs/workshop/homarr-provider.mdx
index 92192aa3a..c6ef59d43 100644
--- a/apps/docs/docs/workshop/homarr-provider.mdx
+++ b/apps/docs/docs/workshop/homarr-provider.mdx
@@ -13,69 +13,41 @@ import { OpenCollectiveLink } from "@site/src/components/assistant-provider/open
# Homarr provider
-The Homarr provider gives Workshop users access to **DeepSeek V4 Flash Latest**. It uses an OpenAI-compatible proxy in
-the [Community Workshop](/docs/workshop). A Homarr administrator can select this provider without an API key. Each user
-signs in to the Workshop with GitHub. The Workshop session authorizes the user's requests.
+The Homarr provider gives Workshop users access to **DeepSeek V4 Flash Latest** without an administrator API key.
+Each user signs in with GitHub and receives a separate daily allowance.
+
+
+
+## Set it up
+
+1. Open **Management → Assistant**.
+2. Select **Homarr** as the provider.
+3. Save the provider connection.
+4. Select the available model, enable the assistant, and save.
+5. Open the assistant and sign in to the Workshop when asked.
+
+## Daily allowance
+
+- Each user starts with **50 request units per UTC day**.
+- A model request uses one unit.
+- Each completed Homarr tool call uses one additional unit.
+- 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
+limit before it sends a request to OpenRouter.
-## Allowance
+## Data and cost
-- Each user gets **50 request units per UTC day** by default.
-- A model request uses one unit.
-- Each completed Homarr tool call uses one additional unit.
-- A request that reaches the upstream uses its reserved units even when the upstream fails. Invalid requests rejected
- by the Workshop before forwarding do not use units.
-- The limit resets at 00:00 UTC.
-- The battery icon beside the model selector shows the remaining units. Select it to see the limit, reset time,
- Workshop account, and status.
-- The server stores a separate limit for each user. A change to the global default applies only to new users.
+The Workshop keeps the OpenRouter API key on its server. It does not send that key to Homarr or the browser.
-The remaining count shown in Homarr is informational. The Workshop server authenticates the user and reserves request
-units in a database transaction before it contacts OpenRouter. Concurrent or direct API requests cannot spend more
-than the stored allowance.
+Prompts, attachments, tool definitions, and tool results are sent to OpenRouter to generate a response. The Workshop
+does not store this content. It stores only request status, model, usage, duration, cost, and timestamps.
-## Security and cost controls
-
-The proxy owns the upstream model and routing configuration. It removes client-supplied fallback models, providers,
-routes, plugins, transforms, and user identifiers before forwarding a request. It also forces one completion, disables
-parallel tool calls, caps OpenRouter web search, and limits every response to **32,768 output tokens**.
-
-Input uses a conservative **256k token ceiling**. The Workshop enforces this with a 256 KiB serialized request limit,
-because a byte can encode at most one input token. This deliberately rejects some large attachments before they reach
-the theoretical token limit. It prevents a browser or direct API client from hiding an oversized prompt behind an
-optimistic client-side token estimate.
-
-Only OpenAI function tools and Homarr's bounded `openrouter:web_search` server tool are accepted. The response stream
-has an independent byte limit in case an upstream ignores the requested output ceiling. Upstream error bodies are not
-forwarded to users.
-
-## Privacy
-
-The proxy does not store prompts, messages, attachments, tool inputs, tool outputs, or response text. Private records
-store only the Workshop user ID, status, model ID, request units, token totals, duration, cost, and timestamps. The
-public feed is read-only. It contains operational data but does not contain a user ID or GitHub account.
-
-The Workshop server stores the OpenRouter API key. It does not send this key to a Homarr instance or browser. A Homarr
-server sends the user's Workshop token only to the configured Workshop origin.
-
-Prompts, attachments, tool definitions, and tool results are forwarded to the configured OpenRouter-compatible
-upstream so it can generate the response. That upstream's data-handling policy applies. The Workshop proxy does not
-log or persist this content.
-
-The open-source proxy can limit authenticated use, but it cannot prevent one person from creating several eligible
-Workshop accounts. Operators should also set a hard OpenRouter credit limit and monitor the anonymous activity feed.
-
-## Costs
-
-The Homarr community pays for provider requests. Donations help cover these costs.
+The Homarr community pays for these requests. Donations help cover the cost.
-## Share your results
-
-Publish useful Custom Widgets in the [Community Workshop](pathname:///workshop). Include the prompt, API source, and
-screenshots. This information helps other users test and improve the widget.
-
-Workshop operators can configure the proxy, its upstream, and its default allowance in the
+Workshop operators can change the upstream, default allowance, and security limits in the
[Workshop operator guide](./operator#homarr-provider-proxy).
diff --git a/apps/docs/docs/workshop/index.mdx b/apps/docs/docs/workshop/index.mdx
index 5aaeebd0d..cf5682b88 100644
--- a/apps/docs/docs/workshop/index.mdx
+++ b/apps/docs/docs/workshop/index.mdx
@@ -9,87 +9,45 @@ tags:
# Community Workshop
-:::warning Experimental feature
+The [Community Workshop](pathname:///workshop) is where Homarr users share Custom Widgets and dashboard CSS.
-This feature is experimental and will probably change. If you encounter bugs, need more capabilities, or find something confusing, tell us in the [official discussion thread](https://github.com/homarr-labs/homarr/discussions/categories/custom-widgets). Your feedback directly shapes what comes next. Happy hacking!
+:::warning Experimental
+
+Workshop content is made by the community. Review it before installation and back up your Homarr instance.
:::
-The [Community Workshop](pathname:///workshop) is where Homarr users share and discover
-**custom CSS themes** and **custom widgets**. You can browse submissions, upvote the ones
-you like, report abuse, and install entries directly into your own Homarr instance.
+## Find and install content
-The central `homarr.dev` Workshop is a public community. Browsing it on the website is public. Browsing, installing,
-publishing, or importing Workshop content **inside a Homarr instance is restricted to Homarr administrators**.
+Browse the Workshop by type, date, popularity, or recent activity. Each submission includes its source, screenshots,
+author, revision, comments, and reports.
-:::warning
+Administrators can install content without leaving Homarr:
-The Workshop contains community-made content. Moderation is not a security boundary, and PocketBase does not interpret
-or validate submission content. Always review widget capabilities, network origins, actions, and CSS before installing.
-Homarr's installation-time validator is definitive and can reject content that the public service accepted earlier.
-Back up your instance before installing untrusted content.
+- **Custom Widgets:** open **Management → Custom Widgets**, then select **Import from Workshop**.
+- **Custom CSS:** open a board's **Settings → Custom CSS**, then select **Import from Workshop**.
-:::
+Homarr shows the complete source and required permissions before installation. Widget credentials are entered in your
+Homarr instance and are never included in a Workshop submission.
-## Browsing and voting
+## Share your work
-- Filter by **Widgets** or **CSS**, show or hide outdated entries, and sort by popularity, creation date, recent updates, or discussion activity.
-- Sign in with **GitHub** to upvote/downvote, submit your own creations, or report a submission.
-- Each submission shows its title, description, linked GitHub author, revision, optional screenshots, comments, and full content. Widget pages also summarize API sources, actions, options, network access, and required credentials before installation.
-- A new submission receives one real upvote owned by its author. Votes remain unique per user and submission.
-- Open report counts are public on submission cards so visitors can make an informed installation decision. The submission author and Workshop moderators can read each report category and explanation; reporter identities remain moderator-only.
-- Signed-in moderators see a **Moderation** button in the Workshop header. The moderation queue is sorted by open report count and lets moderators inspect every report, dismiss it, or delete the submission. Reports do not automatically remove a submission.
-- The manual **Outdated** badge warns visitors that a submission may need an update.
+1. Sign in to the Workshop with GitHub.
+2. Select **Share yours**.
+3. Choose **Custom Widget** or **Custom CSS**.
+4. Add the source, a short description, screenshots, and a changelog.
+5. Review and publish the submission.
-## Comments
+Export Custom Widget JSON from **Management → Custom Widgets → Export**. You can edit a submission later without
+changing its Workshop URL.
-Comments are publicly readable and appear in chronological conversation bubbles with the author's avatar and GitHub profile. Signed-in users can post; authors can edit or delete their own comments, and Workshop moderators can delete any comment. Failed posts keep the text you typed. When SMTP and `WORKSHOP_PUBLIC_ORIGIN` are configured, the submission author receives one email for a comment from another user. Self-comments, edits, and deletions do not send mail.
+## Voting, comments, and reports
-## Submitting
+Signed-in users can vote, comment, and report submissions. Authors can edit their own comments and submissions.
+Workshop moderators can review reports, remove comments, and delete unsafe content. Reports do not remove a submission
+automatically.
-1. Sign in with GitHub.
-2. Click **Share yours** and choose the type:
- - **Custom widget** — paste the JSON exported from **Manage → Custom Widgets → Export**.
- It must match the `homarr-custom-widget-v2` schema (validated before submission).
- - **Custom CSS** — paste your stylesheet (max 16384 characters).
-3. Review the widget JSON or CSS in the syntax-aware editor, then add a title, description, optional screenshots, and changelog.
-4. Submit the entry.
+A Workshop moderator manages the public community. This is separate from the administrator role on a Homarr instance.
-Custom widget JSON is normalized to readable multi-line formatting when it is published, and the Workshop detail page
-also formats older compact submissions before displaying them.
-
-Community members can report submissions as outdated or no longer working, malicious, spam, copyright-infringing,
-inappropriate, or another concern. An outdated report does not automatically mark or remove the submission.
-
-Submissions are published immediately. Reported entries are reviewed and may be removed.
-Authors can edit a submission later to publish a new revision. The edit form can keep or remove existing screenshots and add new PNG, JPG, or WebP images without changing the Workshop URL.
-
-When SMTP and `WORKSHOP_PUBLIC_ORIGIN` are configured, every current Workshop moderator receives an email when a report is submitted. If a moderator deletes the reported submission, its author receives a separate removal email. Author self-deletion does not send a moderation email.
-
-:::info Separate roles
-
-A Workshop moderator is a user with PocketBase's internal `isAdmin` field. This role moderates the central community
-and is unrelated to a Homarr instance administrator.
-
-:::
-
-## Submission guidelines
-
-Submissions must be useful to Homarr users and safe to install. Do not submit content that is
-malicious, deceptive, illegal, hateful, sexually explicit, gore, gambling-focused, spam, or content
-that primarily promotes unrelated products or services.
-
-## Installing into Homarr
-
-You can install workshop entries without leaving Homarr:
-
-- **Custom widgets (Homarr administrators only)** — go to **Manage → Custom Widgets**, or use **Import from Workshop** in the
- board widget picker. Choose **Install widget**, review the complete source and capabilities, then confirm API sources and any local secrets in the second modal step.
-- **Custom CSS from Workshop (Homarr administrators only)** — open a board's **Settings → Custom CSS**, click **Import from Workshop**, choose a theme, review its full CSS in the second same-size modal step, and click **Import CSS** once. The board setting is still saved separately.
-
-Alternatively, open a submission in the Workshop and use **Download widget JSON** or **Copy CSS**. The submission page shows the matching manual installation steps before the source code.
-
-Custom Widget imports detect required bearer, basic, header, or query credentials. You can enter them during import or explicitly defer them; secret values are never stored in Workshop content. Missing credentials remain visible on the local Custom Widget afterward.
-
-Deployment, environment variables, backups, and service architecture are covered in the
-[Workshop operator guide](./operator).
+Deployment and server configuration are in the [Workshop operator guide](./operator). Local setup is in
+[Workshop development](./development).
diff --git a/apps/docs/static/img/assistant/configuration.png b/apps/docs/static/img/assistant/configuration.png
new file mode 100644
index 000000000..95dfc58d1
Binary files /dev/null and b/apps/docs/static/img/assistant/configuration.png differ
diff --git a/apps/docs/static/img/assistant/conversation.png b/apps/docs/static/img/assistant/conversation.png
new file mode 100644
index 000000000..5ce559b3d
Binary files /dev/null and b/apps/docs/static/img/assistant/conversation.png differ
diff --git a/apps/docs/static/img/assistant/homarr-provider.png b/apps/docs/static/img/assistant/homarr-provider.png
new file mode 100644
index 000000000..a1090dd34
Binary files /dev/null and b/apps/docs/static/img/assistant/homarr-provider.png differ
diff --git a/apps/nextjs/src/app/api/assistant/chat/assistant-execution-policy.spec.ts b/apps/nextjs/src/app/api/assistant/chat/assistant-execution-policy.spec.ts
index 9eefbc960..1d75483d4 100644
--- a/apps/nextjs/src/app/api/assistant/chat/assistant-execution-policy.spec.ts
+++ b/apps/nextjs/src/app/api/assistant/chat/assistant-execution-policy.spec.ts
@@ -5,7 +5,7 @@ import { assistantExecutionPolicy } from "./assistant-execution-policy";
describe("assistantExecutionPolicy", () => {
test("allows a sizeable batch of tool calls to finish in one request", () => {
expect(assistantExecutionPolicy.maxSteps).toBeGreaterThanOrEqual(32);
- expect(assistantExecutionPolicy.maxOutputTokens).toBeGreaterThanOrEqual(65_536);
+ expect(assistantExecutionPolicy.maxOutputTokens).toBe(32_768);
expect(assistantExecutionPolicy.totalTimeoutMs).toBeGreaterThan(assistantExecutionPolicy.stepTimeoutMs);
expect(assistantExecutionPolicy.toolTimeoutMs).toBeGreaterThanOrEqual(60_000);
});
diff --git a/apps/nextjs/src/app/api/assistant/chat/assistant-execution-policy.ts b/apps/nextjs/src/app/api/assistant/chat/assistant-execution-policy.ts
index 799bf36d9..08d7cedcb 100644
--- a/apps/nextjs/src/app/api/assistant/chat/assistant-execution-policy.ts
+++ b/apps/nextjs/src/app/api/assistant/chat/assistant-execution-policy.ts
@@ -1,6 +1,6 @@
export const assistantExecutionPolicy = {
maxSteps: 32,
- maxOutputTokens: 65_536,
+ maxOutputTokens: 32_768,
totalTimeoutMs: 240_000,
stepTimeoutMs: 60_000,
toolTimeoutMs: 60_000,
diff --git a/apps/nextjs/src/app/api/assistant/chat/route.ts b/apps/nextjs/src/app/api/assistant/chat/route.ts
index ce09bc9b3..399914eb2 100644
--- a/apps/nextjs/src/app/api/assistant/chat/route.ts
+++ b/apps/nextjs/src/app/api/assistant/chat/route.ts
@@ -72,6 +72,7 @@ export const maxDuration = 300;
const assistantRequestMaxBytes = 12_000_000;
const logger = createLogger({ module: "assistant" });
+const getAssistantLogErrorType = (error: unknown) => (error instanceof Error ? error.name : typeof error);
const getToolApprovalSecret = () =>
Buffer.from(
hkdfSync("sha256", Buffer.from(env.SECRET_ENCRYPTION_KEY, "hex"), "", "assistant-tool-approval", 32),
@@ -435,7 +436,7 @@ export async function POST(request: Request) {
} catch (error) {
logger.warn("Rejected an unsafe Homarr provider endpoint", {
provider: configuration.provider,
- error,
+ errorType: getAssistantLogErrorType(error),
});
return Response.json({ error: "The Homarr provider endpoint is not configured safely." }, { status: 503 });
}
@@ -462,7 +463,7 @@ export async function POST(request: Request) {
requestId,
provider: configuration.provider,
modelId: requestedModelId,
- error: modelLookup.error,
+ errorType: getAssistantLogErrorType(modelLookup.error),
});
}
const selectedModel = modelLookup.model;
@@ -536,7 +537,7 @@ export async function POST(request: Request) {
} catch (error) {
logger.error("Assistant tool call failed", {
toolName: mcpTool.name,
- error: error instanceof Error ? error.message : String(error),
+ errorType: getAssistantLogErrorType(error),
});
return { error: getSafeAssistantToolError(error, { toolName: mcpTool.name }) };
}
@@ -747,7 +748,7 @@ export async function POST(request: Request) {
requestId,
provider: configuration.provider,
modelId,
- error: error instanceof Error ? error.message : String(error),
+ errorType: getAssistantLogErrorType(error),
});
},
onFinish: async () => {
@@ -759,7 +760,7 @@ export async function POST(request: Request) {
} catch (error) {
logger.error("Failed to update assistant conversation metadata", {
threadId: thread.id,
- error: error instanceof Error ? error.message : String(error),
+ errorType: getAssistantLogErrorType(error),
});
}
},
@@ -866,7 +867,7 @@ export async function POST(request: Request) {
});
} catch (error) {
logger.error("Assistant response could not start", {
- error: error instanceof Error ? error.message : String(error),
+ errorType: getAssistantLogErrorType(error),
});
return Response.json(
{
diff --git a/apps/workshop/homarr_provider.go b/apps/workshop/homarr_provider.go
index 873501373..d172afcfb 100644
--- a/apps/workshop/homarr_provider.go
+++ b/apps/workshop/homarr_provider.go
@@ -23,18 +23,27 @@ import (
const (
homarrProviderModelID = "homarr/deepseek-v4-flash-latest"
openRouterModelID = "~deepseek/deepseek-v4-flash-latest"
+ maxChatInputTokens = 256 * 1024
+ maxChatOutputTokens = 32 * 1024
defaultDailyLimit = 50
maxProviderRequestUnits = 1000
- maxChatRequestBytes = 8 << 20
- maxChatResponseBytes = 8 << 20
- maxUpstreamErrorBytes = 1 << 20
- openRouterDefaultURL = "https://openrouter.ai/api/v1"
- providerRequestTimeout = 5 * time.Minute
+ // Do not trust a client-side token estimate. Applying the same numeric ceiling to
+ // the complete serialized payload is deliberately stricter than a tokenizer-based
+ // limit and also bounds attachments and tool schemas.
+ maxChatRequestBytes = maxChatInputTokens
+ maxChatResponseBytes = 8 << 20
+ maxUpstreamErrorBytes = 1 << 20
+ maxWebSearchResults = 5
+ maxWebSearchUses = 3
+ openRouterDefaultURL = "https://openrouter.ai/api/v1"
+ providerRequestTimeout = 5 * time.Minute
)
var errProviderResponseTooLarge = errors.New("provider response is too large")
-var clientControlledRoutingFields = []string{"models", "provider", "route", "plugins", "transforms"}
+var clientControlledRoutingFields = []string{
+ "models", "provider", "route", "plugins", "transforms", "extra_body", "extra_headers",
+}
type homarrProvider struct {
apiKey string
@@ -97,8 +106,9 @@ func newHomarrProviderFromEnv() (*homarrProvider, error) {
baseURL = openRouterDefaultURL
}
parsedURL, err := url.Parse(baseURL)
- if err != nil || parsedURL.Host == "" || (parsedURL.Scheme != "https" && parsedURL.Scheme != "http") {
- return nil, errors.New("HOMARR_AI_OPENROUTER_BASE_URL must be an absolute HTTP(S) URL")
+ if err != nil || parsedURL.Host == "" || (parsedURL.Scheme != "https" && parsedURL.Scheme != "http") ||
+ parsedURL.User != nil || parsedURL.RawQuery != "" || parsedURL.Fragment != "" {
+ return nil, errors.New("HOMARR_AI_OPENROUTER_BASE_URL must be an absolute HTTP(S) URL without credentials, a query, or a fragment")
}
dailyLimit := defaultDailyLimit
@@ -136,7 +146,7 @@ func (provider *homarrProvider) models(event *core.RequestEvent) error {
"name": "DeepSeek V4 Flash Latest",
"description": "Fast agentic model provided by the community-funded Homarr provider.",
"owned_by": "homarr",
- "context_length": 1_048_576,
+ "context_length": maxChatInputTokens,
"supported_parameters": []string{
"tools", "tool_choice", "reasoning", "include_reasoning", "structured_outputs",
},
@@ -183,7 +193,9 @@ func (provider *homarrProvider) chat(event *core.RequestEvent) error {
if err := json.Unmarshal(body, &payload); err != nil {
return event.JSON(http.StatusBadRequest, openAIError("The request body is not valid OpenAI chat JSON."))
}
- sanitizeProviderPayload(payload)
+ if err := sanitizeProviderPayload(payload); err != nil {
+ return event.JSON(http.StatusBadRequest, openAIError(err.Error()))
+ }
upstreamBody, err := json.Marshal(payload)
if err != nil {
return event.JSON(http.StatusBadRequest, openAIError("The request body could not be prepared."))
@@ -208,7 +220,7 @@ func (provider *homarrProvider) chat(event *core.RequestEvent) error {
bytes.NewReader(upstreamBody),
)
if err != nil {
- provider.finishActivityWithRefund(event.App, privateRequest, publicActivity, "failed", requestUsage{}, startedAt, requestUnits)
+ provider.finishActivity(event.App, privateRequest, publicActivity, "failed", requestUsage{}, startedAt)
return event.JSON(http.StatusInternalServerError, openAIError("The Homarr provider request could not be prepared."))
}
upstreamRequest.Header.Set("Authorization", "Bearer "+provider.apiKey)
@@ -220,7 +232,7 @@ func (provider *homarrProvider) chat(event *core.RequestEvent) error {
upstreamResponse, err := provider.httpClient.Do(upstreamRequest)
if err != nil {
- provider.finishActivityWithRefund(event.App, privateRequest, publicActivity, "failed", requestUsage{}, startedAt, requestUnits)
+ provider.finishActivity(event.App, privateRequest, publicActivity, "failed", requestUsage{}, startedAt)
return event.JSON(http.StatusBadGateway, openAIError("The model endpoint could not be reached."))
}
defer func() { _ = upstreamResponse.Body.Close() }()
@@ -239,17 +251,15 @@ func (provider *homarrProvider) chat(event *core.RequestEvent) error {
contentType = "application/json"
}
if upstreamResponse.StatusCode < 200 || upstreamResponse.StatusCode >= 300 {
- errorBody, _ := io.ReadAll(io.LimitReader(upstreamResponse.Body, maxUpstreamErrorBytes))
- provider.finishActivityWithRefund(event.App, privateRequest, publicActivity, "failed", requestUsage{}, startedAt, requestUnits)
- event.Response.Header().Set("X-Homarr-Quota-Remaining", strconv.Itoa(min(snapshot.Limit, snapshot.Remaining+requestUnits)))
- return event.Blob(upstreamResponse.StatusCode, contentType, errorBody)
+ provider.finishActivity(event.App, privateRequest, publicActivity, "failed", requestUsage{}, startedAt)
+ return event.JSON(upstreamResponse.StatusCode, openAIError("The model endpoint rejected the request."))
}
if requestBody.Stream {
capture := newSSEUsageCapture()
event.Response.Header().Set("Content-Type", contentType)
event.Response.WriteHeader(upstreamResponse.StatusCode)
- _, copyErr := io.Copy(flushingWriter{event.Response}, io.TeeReader(upstreamResponse.Body, capture))
+ _, copyErr := copyBounded(flushingWriter{event.Response}, io.TeeReader(upstreamResponse.Body, capture), maxChatResponseBytes)
provider.finishActivity(event.App, privateRequest, publicActivity, statusForError(copyErr), capture.Usage(), startedAt)
return nil
}
@@ -264,12 +274,72 @@ func (provider *homarrProvider) chat(event *core.RequestEvent) error {
return event.Blob(upstreamResponse.StatusCode, contentType, responseBody)
}
-func sanitizeProviderPayload(payload map[string]any) {
+func sanitizeProviderPayload(payload map[string]any) error {
for _, field := range clientControlledRoutingFields {
delete(payload, field)
}
+ delete(payload, "max_completion_tokens")
+ delete(payload, "metadata")
+ delete(payload, "user")
+ if reasoning, ok := payload["reasoning"].(map[string]any); ok {
+ delete(reasoning, "max_tokens")
+ }
+
+ if rawTools, exists := payload["tools"]; exists {
+ tools, ok := rawTools.([]any)
+ if !ok {
+ return errors.New("The request tools are not valid.")
+ }
+ sanitizedTools := make([]any, 0, len(tools))
+ webSearchAdded := false
+ for _, rawTool := range tools {
+ tool, ok := rawTool.(map[string]any)
+ if !ok {
+ return errors.New("The request contains an unsupported tool.")
+ }
+ switch tool["type"] {
+ case "function":
+ sanitizedTools = append(sanitizedTools, tool)
+ case "openrouter:web_search":
+ if !webSearchAdded {
+ sanitizedTools = append(sanitizedTools, map[string]any{
+ "type": "openrouter:web_search",
+ "parameters": map[string]any{
+ "max_results": maxWebSearchResults,
+ "max_uses": maxWebSearchUses,
+ },
+ })
+ webSearchAdded = true
+ }
+ default:
+ return errors.New("The request contains an unsupported tool.")
+ }
+ }
+ payload["tools"] = sanitizedTools
+ }
+
payload["model"] = openRouterModelID
+ payload["max_tokens"] = maxChatOutputTokens
+ payload["n"] = 1
+ payload["parallel_tool_calls"] = false
payload["usage"] = map[string]any{"include": true}
+ return nil
+}
+
+func copyBounded(writer io.Writer, reader io.Reader, limit int64) (int64, error) {
+ written, err := io.Copy(writer, io.LimitReader(reader, limit))
+ if err != nil {
+ return written, err
+ }
+ var extra [1]byte
+ read, err := reader.Read(extra[:])
+ if read > 0 {
+ return written, errProviderResponseTooLarge
+ }
+ if err != nil && !errors.Is(err, io.EOF) {
+ return written, err
+ }
+ return written, nil
}
func readBoundedBody(reader io.Reader, limit int64) ([]byte, error) {
@@ -393,18 +463,6 @@ func (provider *homarrProvider) finishActivity(
status string,
usage requestUsage,
startedAt time.Time,
-) {
- provider.finishActivityWithRefund(app, privateRequest, publicActivity, status, usage, startedAt, 0)
-}
-
-func (provider *homarrProvider) finishActivityWithRefund(
- app core.App,
- privateRequest *core.Record,
- publicActivity *core.Record,
- status string,
- usage requestUsage,
- startedAt time.Time,
- refundUnits int,
) {
durationMs := max(0, int(provider.now().UTC().Sub(startedAt).Milliseconds()))
err := app.RunInTransaction(func(txApp core.App) error {
@@ -430,9 +488,6 @@ func (provider *homarrProvider) finishActivityWithRefund(
if !requestBelongsToQuotaDay(quota.GetString("day"), startedAt) {
return nil
}
- if refundUnits > 0 {
- quota.Set("used", max(0, quota.GetInt("used")-refundUnits))
- }
quota.Set("inputTokens", quota.GetInt("inputTokens")+usage.InputTokens)
quota.Set("outputTokens", quota.GetInt("outputTokens")+usage.OutputTokens)
quota.Set("totalTokens", quota.GetInt("totalTokens")+usage.TotalTokens)
diff --git a/apps/workshop/homarr_provider_test.go b/apps/workshop/homarr_provider_test.go
index ea29f2558..e46d0a4a9 100644
--- a/apps/workshop/homarr_provider_test.go
+++ b/apps/workshop/homarr_provider_test.go
@@ -10,15 +10,34 @@ import (
func TestSanitizeProviderPayload(t *testing.T) {
payload := map[string]any{
- "model": homarrProviderModelID,
- "models": []string{"attacker/model"},
- "provider": map[string]any{"order": []string{"attacker"}},
- "route": "fallback",
- "plugins": []string{"web"},
- "transforms": []string{"middle-out"},
- "messages": []any{map[string]any{"role": "user", "content": "hello"}},
+ "model": homarrProviderModelID,
+ "models": []string{"attacker/model"},
+ "provider": map[string]any{"order": []string{"attacker"}},
+ "route": "fallback",
+ "plugins": []string{"web"},
+ "transforms": []string{"middle-out"},
+ "max_tokens": 1_000_000,
+ "max_completion_tokens": 1_000_000,
+ "n": 100,
+ "parallel_tool_calls": true,
+ "extra_body": map[string]any{"provider": map[string]any{"order": []string{"attacker"}}},
+ "extra_headers": map[string]any{"Authorization": "Bearer attacker"},
+ "metadata": map[string]any{"user": "private-user-id"},
+ "reasoning": map[string]any{"effort": "high", "max_tokens": 1_000_000},
+ "user": "private-user-id",
+ "tools": []any{
+ map[string]any{"type": "function", "function": map[string]any{"name": "board_list"}},
+ map[string]any{
+ "type": "openrouter:web_search",
+ "parameters": map[string]any{"max_results": 1000, "max_uses": 1000},
+ },
+ map[string]any{"type": "openrouter:web_search"},
+ },
+ "messages": []any{map[string]any{"role": "user", "content": "hello"}},
+ }
+ if err := sanitizeProviderPayload(payload); err != nil {
+ t.Fatal(err)
}
- sanitizeProviderPayload(payload)
for _, field := range clientControlledRoutingFields {
if _, exists := payload[field]; exists {
t.Fatalf("client-controlled routing field %q was forwarded", field)
@@ -27,12 +46,44 @@ func TestSanitizeProviderPayload(t *testing.T) {
if payload["model"] != openRouterModelID {
t.Fatalf("unexpected upstream model: %v", payload["model"])
}
+ if payload["max_tokens"] != maxChatOutputTokens || payload["n"] != 1 || payload["parallel_tool_calls"] != false {
+ t.Fatalf("unsafe generation controls were forwarded: %#v", payload)
+ }
+ if _, exists := payload["max_completion_tokens"]; exists {
+ t.Fatal("client max_completion_tokens was forwarded")
+ }
+ if _, exists := payload["user"]; exists {
+ t.Fatal("client user identifier was forwarded")
+ }
+ if _, exists := payload["metadata"]; exists {
+ t.Fatal("client metadata was forwarded")
+ }
+ reasoning := payload["reasoning"].(map[string]any)
+ if _, exists := reasoning["max_tokens"]; exists || reasoning["effort"] != "high" {
+ t.Fatalf("reasoning budget was not bounded safely: %#v", reasoning)
+ }
+ tools := payload["tools"].([]any)
+ if len(tools) != 2 {
+ t.Fatalf("unexpected sanitized tool count: %d", len(tools))
+ }
+ webSearch := tools[1].(map[string]any)
+ parameters := webSearch["parameters"].(map[string]any)
+ if parameters["max_results"] != maxWebSearchResults || parameters["max_uses"] != maxWebSearchUses {
+ t.Fatalf("web search limits were not enforced: %#v", parameters)
+ }
usage, err := json.Marshal(payload["usage"])
if err != nil || string(usage) != `{"include":true}` {
t.Fatalf("unexpected usage options: %s, %v", usage, err)
}
}
+func TestSanitizeProviderPayloadRejectsUnsupportedServerTools(t *testing.T) {
+ payload := map[string]any{"tools": []any{map[string]any{"type": "openrouter:computer"}}}
+ if err := sanitizeProviderPayload(payload); err == nil {
+ t.Fatal("expected unsupported server tool to be rejected")
+ }
+}
+
func TestCountRequestUnits(t *testing.T) {
tests := []struct {
name string
@@ -111,6 +162,18 @@ func TestProviderEnvironment(t *testing.T) {
if _, err := newHomarrProviderFromEnv(); err == nil {
t.Fatal("expected invalid daily limit to fail")
}
+
+ t.Setenv("HOMARR_AI_DAILY_REQUEST_LIMIT", "50")
+ for _, unsafeURL := range []string{
+ "https://user:password@router.example/v1",
+ "https://router.example/v1?key=secret",
+ "https://router.example/v1#fragment",
+ } {
+ t.Setenv("HOMARR_AI_OPENROUTER_BASE_URL", unsafeURL)
+ if _, err := newHomarrProviderFromEnv(); err == nil {
+ t.Fatalf("expected unsafe upstream URL %q to fail", unsafeURL)
+ }
+ }
}
func TestReadBoundedBody(t *testing.T) {
@@ -123,6 +186,20 @@ func TestReadBoundedBody(t *testing.T) {
}
}
+func TestCopyBounded(t *testing.T) {
+ var target strings.Builder
+ written, err := copyBounded(&target, strings.NewReader("1234"), 4)
+ if err != nil || written != 4 || target.String() != "1234" {
+ t.Fatalf("unexpected bounded copy: %q, %d, %v", target.String(), written, err)
+ }
+
+ target.Reset()
+ written, err = copyBounded(&target, strings.NewReader("12345"), 4)
+ if err != errProviderResponseTooLarge || written != 4 || target.String() != "1234" {
+ t.Fatalf("expected bounded copy failure, got %q, %d, %v", target.String(), written, err)
+ }
+}
+
func TestRequestBelongsToQuotaDay(t *testing.T) {
startedAt := time.Date(2026, 8, 12, 1, 30, 0, 0, time.FixedZone("CEST", 2*60*60))
if !requestBelongsToQuotaDay("2026-08-11", startedAt) {
diff --git a/apps/workshop/tests/openrouter-mock.mjs b/apps/workshop/tests/openrouter-mock.mjs
index 4ea4074d0..5d2315362 100644
--- a/apps/workshop/tests/openrouter-mock.mjs
+++ b/apps/workshop/tests/openrouter-mock.mjs
@@ -28,11 +28,34 @@ const server = createServer(async (request, response) => {
json(response, 400, { error: { message: "Unexpected upstream model" } });
return;
}
+ if (body.max_tokens !== 32_768 || body.n !== 1 || body.parallel_tool_calls !== false) {
+ json(response, 400, { error: { message: "Unsafe generation controls reached the upstream" } });
+ return;
+ }
+ if (
+ "max_completion_tokens" in body ||
+ "user" in body ||
+ "metadata" in body ||
+ "extra_body" in body ||
+ "extra_headers" in body ||
+ "max_tokens" in (body.reasoning ?? {})
+ ) {
+ json(response, 400, { error: { message: "Private or unbounded request fields reached the upstream" } });
+ return;
+ }
const forbiddenRoutingField = ["models", "provider", "route", "plugins", "transforms"].find((field) => field in body);
if (forbiddenRoutingField) {
json(response, 400, { error: { message: `Client routing field was forwarded: ${forbiddenRoutingField}` } });
return;
}
+ const webSearchTools = body.tools?.filter((tool) => tool.type === "openrouter:web_search") ?? [];
+ if (
+ webSearchTools.length > 1 ||
+ webSearchTools.some((tool) => tool.parameters?.max_results !== 5 || tool.parameters?.max_uses !== 3)
+ ) {
+ json(response, 400, { error: { message: "Unbounded web search controls reached the upstream" } });
+ return;
+ }
if (body.messages?.some((message) => message.content === "upstream failure")) {
json(response, 503, { error: { message: "Simulated upstream failure" } });
return;
diff --git a/apps/workshop/tests/workshop.integration.mjs b/apps/workshop/tests/workshop.integration.mjs
index e1c5f8171..3213cef42 100644
--- a/apps/workshop/tests/workshop.integration.mjs
+++ b/apps/workshop/tests/workshop.integration.mjs
@@ -136,11 +136,23 @@ const modelList = await request("/api/ai/v1/models");
if (
modelList.object !== "list" ||
modelList.data.length !== 1 ||
- modelList.data[0].id !== "homarr/deepseek-v4-flash-latest"
+ modelList.data[0].id !== "homarr/deepseek-v4-flash-latest" ||
+ modelList.data[0].context_length !== 256 * 1024
) {
throw new Error("The Homarr provider must advertise exactly one model");
}
await expectStatus("/api/ai/usage", {}, 401);
+await expectStatus(
+ "/api/ai/v1/chat/completions",
+ {
+ method: "POST",
+ body: JSON.stringify({
+ model: "homarr/deepseek-v4-flash-latest",
+ messages: [{ role: "user", content: "unauthenticated" }],
+ }),
+ },
+ 401,
+);
const initialUsage = await request("/api/ai/usage", { headers: authorSession.headers });
const initialReset = new Date(initialUsage.resetsAt);
@@ -173,6 +185,19 @@ await expectStatus(
},
400,
);
+
+await expectStatus(
+ "/api/ai/v1/chat/completions",
+ {
+ method: "POST",
+ headers: authorSession.headers,
+ body: JSON.stringify({
+ model: "homarr/deepseek-v4-flash-latest",
+ messages: [{ role: "user", content: "x".repeat(256 * 1024) }],
+ }),
+ },
+ 413,
+);
const usageAfterRejectedRequest = await request("/api/ai/usage", { headers: authorSession.headers });
if (usageAfterRejectedRequest.used !== 0) {
throw new Error("A rejected oversized request-unit batch consumed allowance");
@@ -266,6 +291,20 @@ const toolResponse = await fetch(`${baseUrl}/api/ai/v1/chat/completions`, {
route: "fallback",
plugins: ["web"],
transforms: ["middle-out"],
+ max_tokens: 1_000_000,
+ max_completion_tokens: 1_000_000,
+ n: 100,
+ parallel_tool_calls: true,
+ extra_body: { provider: { order: ["attacker"] } },
+ extra_headers: { Authorization: "Bearer attacker" },
+ metadata: { user: "must-not-reach-openrouter" },
+ reasoning: { effort: "high", max_tokens: 1_000_000 },
+ user: "must-not-reach-openrouter",
+ tools: [
+ { type: "function", function: { name: "board_list" } },
+ { type: "openrouter:web_search", parameters: { max_results: 1000, max_uses: 1000 } },
+ { type: "openrouter:web_search" },
+ ],
}),
});
if (!toolResponse.ok || toolResponse.headers.get("x-homarr-quota-remaining") !== "46") {
@@ -286,12 +325,20 @@ const upstreamFailure = await fetch(`${baseUrl}/api/ai/v1/chat/completions`, {
stream: false,
}),
});
-if (upstreamFailure.status !== 503 || upstreamFailure.headers.get("x-homarr-quota-remaining") !== "46") {
- throw new Error("Failed upstream requests must refund their Homarr provider allowance");
+if (upstreamFailure.status !== 503 || upstreamFailure.headers.get("x-homarr-quota-remaining") !== "45") {
+ throw new Error("Every request forwarded upstream must consume Homarr provider allowance");
+}
+const upstreamFailureBody = await upstreamFailure.text();
+if (upstreamFailureBody.includes("Simulated upstream failure")) {
+ throw new Error("Upstream error details must not be exposed to clients");
}
const afterFailureUsage = await request("/api/ai/usage", { headers: authorSession.headers });
-if (afterFailureUsage.used !== 4 || afterFailureUsage.remaining !== 46) {
- throw new Error(`Failed upstream request was charged: ${JSON.stringify(afterFailureUsage)}`);
+if (afterFailureUsage.used !== 5 || afterFailureUsage.remaining !== 45) {
+ throw new Error(`Forwarded upstream failure escaped quota accounting: ${JSON.stringify(afterFailureUsage)}`);
+}
+const visitorUsage = await request("/api/ai/usage", { headers: visitorSession.headers });
+if (visitorUsage.used !== 0 || visitorUsage.remaining !== 50) {
+ throw new Error(`Provider allowance leaked across users: ${JSON.stringify(visitorUsage)}`);
}
const publicActivities = await request("/api/collections/assistant_activity/records?sort=-created&perPage=10");
@@ -343,7 +390,7 @@ if (retainedRequest.id !== requestToRetain.id || retainedRequest.publicActivity)
}
const quotas = await request("/api/collections/assistant_quotas/records?perPage=20", { headers: rootHeaders });
const authorQuota = quotas.items.find((item) => item.user === author.id);
-if (!authorQuota || authorQuota.dailyLimit !== 50 || authorQuota.used !== 4 || authorQuota.totalTokens !== 38) {
+if (!authorQuota || authorQuota.dailyLimit !== 50 || authorQuota.used !== 5 || authorQuota.totalTokens !== 38) {
throw new Error(`Private provider quota is incorrect: ${JSON.stringify(authorQuota)}`);
}
diff --git a/e2e/assistant-docs-screenshots.spec.ts b/e2e/assistant-docs-screenshots.spec.ts
new file mode 100644
index 000000000..58389f66a
--- /dev/null
+++ b/e2e/assistant-docs-screenshots.spec.ts
@@ -0,0 +1,101 @@
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+
+import { chromium, expect } from "@playwright/test";
+import { describe, test } from "vitest";
+
+import * as sqliteSchema from "../packages/db/schema/sqlite";
+import { createHomarrContainer } from "./shared/create-homarr-container";
+import { createSqliteDbFileAsync } from "./shared/e2e-db";
+import { seedAdminUserAsync } from "./shared/seed-admin-user";
+
+const adminCredentials = {
+ username: "admin",
+ password: "Comp(exP4sswOrd",
+};
+
+// This is an opt-in documentation asset generator, not part of the normal E2E gate.
+// Run it explicitly with UPDATE_DOCS_SCREENSHOTS=true when the documented UI changes.
+describe.skipIf(process.env.UPDATE_DOCS_SCREENSHOTS !== "true")("Assistant documentation screenshots", () => {
+ test("captures the management page and conversation panel", async () => {
+ const { db, localMountPath } = await createSqliteDbFileAsync();
+ await seedAdminUserAsync(db, adminCredentials);
+ await db.insert(sqliteSchema.assistantConfigurations).values({
+ id: "default",
+ enabled: true,
+ provider: "openrouter",
+ baseUrl: "https://openrouter.ai/api/v1",
+ modelDiscoveryPath: null,
+ encryptedApiKey: "encrypted.key",
+ modelId: "deepseek/deepseek-v4-flash",
+ });
+
+ const outputDirectory = path.resolve("apps/docs/static/img/assistant");
+ await mkdir(outputDirectory, { recursive: true });
+
+ const homarrContainer = await createHomarrContainer({
+ environment: { AUTH_PROVIDERS: "credentials" },
+ mounts: { "/appdata": localMountPath },
+ }).start();
+ const baseUrl = `http://${homarrContainer.getHost()}:${homarrContainer.getMappedPort(7575)}`;
+ const browser = await chromium.launch();
+ const context = await browser.newContext({
+ colorScheme: "dark",
+ deviceScaleFactor: 1,
+ viewport: { width: 1440, height: 1000 },
+ });
+ const page = await context.newPage();
+
+ try {
+ await page.goto(`${baseUrl}/auth/login`);
+ await page.getByLabel("Username").fill(adminCredentials.username);
+ await page.locator("#password").fill(adminCredentials.password);
+ await page.getByRole("button", { name: "Login" }).click();
+ await expect(page).not.toHaveURL(/\/auth\/login/, { timeout: 30_000 });
+
+ await page.goto(`${baseUrl}/manage/assistant`);
+ await expect(page.getByRole("heading", { name: "Assistant" })).toBeVisible();
+ await expect(page.getByText("Connection ready")).toBeVisible();
+ await page
+ .getByRole("main")
+ .first()
+ .screenshot({
+ animations: "disabled",
+ path: path.join(outputDirectory, "configuration.png"),
+ });
+
+ await page.goto(baseUrl);
+ await expect(page.getByRole("main").first()).toBeVisible();
+ await page.locator("body").click({ position: { x: 12, y: 12 } });
+ await page.keyboard.press("Shift+A");
+ const assistantDialog = page.getByRole("dialog", { name: "Homarr Assistant" });
+ await expect(assistantDialog).toBeVisible();
+ await assistantDialog.screenshot({
+ animations: "disabled",
+ path: path.join(outputDirectory, "conversation.png"),
+ });
+
+ await db.update(sqliteSchema.assistantConfigurations).set({
+ provider: "homarr",
+ baseUrl: "https://homarr.dev/api/ai/v1",
+ modelDiscoveryPath: "/models",
+ encryptedApiKey: null,
+ modelId: "~deepseek/deepseek-v4-flash-latest",
+ });
+ await page.goto(`${baseUrl}/manage/assistant`);
+ await expect(page.getByRole("heading", { name: "Assistant" })).toBeVisible();
+ await expect(page.getByText("Homarr", { exact: true }).first()).toBeVisible();
+ await expect(page.getByRole("button", { name: "Refresh models" })).toBeVisible({ timeout: 15_000 });
+ const mainBox = await page.getByRole("main").first().boundingBox();
+ if (!mainBox) throw new Error("Assistant management page has no visible main content");
+ await page.screenshot({
+ animations: "disabled",
+ path: path.join(outputDirectory, "homarr-provider.png"),
+ clip: { ...mainBox, height: Math.min(mainBox.height, 1_090) },
+ });
+ } finally {
+ await browser.close();
+ await homarrContainer.stop();
+ }
+ }, 120_000);
+});