feat: configure custom widget sources
This commit is contained in:
43 files changed
+2361
-394
No files matched your search
@@ -93,6 +93,6 @@ Custom JSX v2 provides four HTTP discovery endpoints:
|
||||
- `GET /api/custom-widgets/components` returns the release-matched static component catalog.
|
||||
- `GET /api/custom-widgets/skill` returns the concise live `SKILL.md` plus skills.sh, source, and install metadata. Retrieve the schema, component catalog, and examples through their dedicated resources only when needed.
|
||||
|
||||
Call `customWidget_secretRequestUser` to create a temporary credential entry URL. Do not construct or save this URL.
|
||||
Call `customWidget_configurationRequestUser` to create a temporary API source setup URL where the user can confirm their server URL and enter credentials. Do not construct or save this URL.
|
||||
|
||||
Authenticated tRPC and MCP procedures support definition management, validation, previews, template patches, and credential writes. An exported definition does not contain credentials.
|
||||
@@ -60,14 +60,23 @@ These interfaces do not return an archive URL or archive hash.
|
||||
5. Create a preview session.
|
||||
6. Test the queries and actions.
|
||||
7. Open the preview URL with browser tools.
|
||||
8. Set the credential if the user supplied it.
|
||||
9. Otherwise, ask the user for the credential with the ten-minute Homarr credential URL.
|
||||
10. Inspect the redacted journal.
|
||||
11. Patch the definition until it is valid.
|
||||
12. Create the widget.
|
||||
8. Inspect the redacted journal and revise the local candidate until it is valid.
|
||||
9. Create the widget, including any source URLs and credentials the user already supplied.
|
||||
10. Otherwise, ask the user to configure the saved definition with the ten-minute Homarr source-setup URL.
|
||||
11. Create a final preview with the saved definition ID so Homarr loads its stored credentials, then test it again.
|
||||
12. Update the saved definition if the final verification finds a problem.
|
||||
13. Repeat the procedure for the next widget.
|
||||
|
||||
Each credential URL applies to one definition or preview, one source, and the required fields. The agent receives only the request status.
|
||||
Each source-configuration URL applies to one definition or preview and one source. The user confirms the server URL, network scope, and required credential fields directly in Homarr. The agent receives only request status and never receives plaintext credentials. Preview-scoped values expire with that preview; definition-scoped values persist.
|
||||
|
||||
Agents can install existing widgets without regenerating them:
|
||||
|
||||
1. Search with `customWidget_workshopSearch`.
|
||||
2. Inspect and validate a result with `customWidget_workshopGet`.
|
||||
3. Install it with `customWidget_workshopInstall`.
|
||||
4. Configure deployment-specific URLs and supplied credentials with `customWidget_sourceConfigure`.
|
||||
5. If the agent does not have those values, call `customWidget_configurationRequestUser` and wait for completion.
|
||||
6. Test the installed definition, then use `board_addItem` with kind `customApi` and the returned definition ID.
|
||||
|
||||
Homarr encrypts the plaintext immediately. Homarr does not return the plaintext.
|
||||
|
||||
|
||||
@@ -61,9 +61,17 @@ The workbench keeps one continuous layout with visual source, request, and optio
|
||||
|
||||
Exports, imports, Workshop, MCP, and storage all validate the same schema. Old formats are rejected. A missing definition only renders **Custom widget unavailable** inside its tile.
|
||||
|
||||
When adding widgets while editing a board, the Custom Widgets section always includes **Install from Workshop**. The Workshop and API source review open above the widget picker without closing it. After import, the new definition appears in the picker. Its tile waits for the board to be saved before server requests run and loads automatically after a successful save; no page reload is required.
|
||||
|
||||
## Import and Workshop
|
||||
|
||||
Import review shows origins, authentication modes, network scopes, methods, actions, and permissions. It also lets the user supply each required credential before import. Workshop publishes technically valid widgets immediately; users can vote or report them, and administrators can delete submissions.
|
||||
Import review shows origins, authentication modes, network scopes, methods, actions, and permissions. Every source has a suggested URL, but private and loopback sources must be confirmed or replaced for the current Homarr installation. The same screen accepts API keys, tokens, usernames, and passwords; credentials remain optional at install time and missing values stay visible on the Custom Widgets page.
|
||||
|
||||
For example, installing **Tautulli Activity** asks for both the user's Tautulli URL and API key. A stable public source such as PokéAPI keeps its published URL without creating unnecessary setup work.
|
||||
|
||||
Workshop publishes technically valid widgets immediately; users can vote or report them, and administrators can delete submissions. Publishers should replace personal private-network hosts with a clear service placeholder before publishing.
|
||||
|
||||
Connected agents can search, inspect, and install Workshop widgets with `customWidget_workshopSearch`, `customWidget_workshopGet`, and `customWidget_workshopInstall`. After installation they can set a source URL and credentials with `customWidget_sourceConfigure`, or create a secure user-facing setup URL with `customWidget_configurationRequestUser`. Secret values are never returned through MCP.
|
||||
|
||||
## Bundled examples
|
||||
|
||||
|
||||
@@ -177,13 +177,14 @@ Then, read the live schema and component resources. These resources describe the
|
||||
5. Test named requests with `customWidget_previewQuery` and `customWidget_previewAction`.
|
||||
6. Open the returned preview URL.
|
||||
7. Examine `customWidget_previewJournal`.
|
||||
8. Change the definition with `customWidget_templatePatch` or `customWidget_update`.
|
||||
9. Set a supplied credential with `customWidget_secretSet`.
|
||||
10. Otherwise, call `customWidget_secretRequestUser` to create a ten-minute Homarr entry URL.
|
||||
11. Call `customWidget_create`.
|
||||
12. Repeat this procedure for the next Custom Widget.
|
||||
8. Revise the local candidate and create another preview session until it is ready.
|
||||
9. Call `customWidget_create`, supplying any credentials and deployment-specific source URLs the user already provided.
|
||||
10. If the user must enter the source URL or credentials, call `customWidget_configurationRequestUser` with the new definition ID and wait for completion.
|
||||
11. Create a final preview with that definition ID so Homarr loads its stored credentials, then test it again.
|
||||
12. Use `customWidget_update` or `customWidget_templatePatch` for any final saved-definition corrections.
|
||||
13. Repeat this procedure for the next Custom Widget.
|
||||
|
||||
The agent receives the credential request status. The agent does not receive the plaintext credential.
|
||||
The agent receives the configuration-request status. The agent does not receive plaintext credentials. A preview-scoped setup URL configures only that temporary preview; use a definition-scoped URL when the values must persist.
|
||||
|
||||
Discovery resources:
|
||||
|
||||
@@ -210,7 +211,11 @@ The Custom Widget tools are:
|
||||
- `customWidget_previewAction`
|
||||
- `customWidget_previewJournal`
|
||||
- `customWidget_secretSet`
|
||||
- `customWidget_secretRequestUser`
|
||||
- `customWidget_sourceConfigure`
|
||||
- `customWidget_configurationRequestUser`
|
||||
- `customWidget_workshopSearch`
|
||||
- `customWidget_workshopGet`
|
||||
- `customWidget_workshopInstall`
|
||||
- `customWidget_getAuthoringPrompt`
|
||||
- `customWidget_getSkill`
|
||||
|
||||
|
||||
Reference in new issue
Block a user