Custom OpenAnalyst Plugin Setup

Use this guide when you need to install or enable a custom OpenAnalyst plugin for a 10x handle or workspace.

This is an end-user setup guide, not a plugin authoring guide. It assumes the plugin already exists, has been approved or trusted, and is ready to install into OpenAnalyst.

When to use this guide

Use this when:

• 10x has enabled a custom OpenAnalyst plugin for your handle, workspace, or project.
• You need to install a 10x-hosted plugin from the OpenAnalyst plugin catalog.
• You have an advanced BYO plugin source, such as an npm package, local path, or file URL, and you understand the trust boundary.
• You need to verify whether a plugin is visible, installed, loaded, and rendering correctly.

Do not use this guide for hosted MCP tools. If you want to expose tools to ChatGPT, OpenAI, or another MCP client, use MCP Builder and Hosted Tools instead.

Do not use this guide to update hosted 10x skills through the control-plane API. For JWT-backed hosted skill metadata, runtime, publish, and delete operations, use JWT Skill Management.

What is being set up

10x and OpenAnalyst split responsibility:

Think about setup in four states:

A plugin is not usable just because it is visible in a catalog. It must be installed locally, the workspace must be reloaded, and the plugin app must appear in OpenAnalyst.

Before you start

You need:

• Access to https://app.10x.in.
• The correct 10x handle, workspace, or project selected.
• OpenAnalyst launched or paired from the 10x/Smartwork flow. Use Smartwork and OpenAnalyst Access if pairing is not complete.
• A trusted plugin source.

Path A: 10x-hosted custom plugin

Use this path for the normal 10x-approved flow.

1. Open the correct 10x context

   Open https://app.10x.in, sign in, and select the handle, workspace, or Smartwork project that should receive the plugin.

2. Launch or pair OpenAnalyst

   Start OpenAnalyst from the browser flow or finish desktop pairing. The selected 10x context should be available to the local runtime after launch.

3. Open plugin settings or catalog

   In OpenAnalyst, open the plugin settings/catalog surface. Hosted 10x entries are displayed through the local OpenAnalyst catalog, even when 10x is the source of the hosted decision.

4. Install the approved plugin

   Select the custom plugin that 10x has enabled for your context. Confirm the install approval prompt. Hosted installs should use the approved catalog entry instead of copying arbitrary package metadata.

5. Reload the workspace

   Reload or restart the active workspace after install. Installing changes local config; loading the plugin happens after the workspace refreshes.

6. Open the plugin app

   Open the new plugin app from the OpenAnalyst app list. Confirm the page renders and shows the expected handle, workspace, or missing-context notice.

Path B: BYO/local plugin

Use this path only when support, your team, or the plugin creator has given you a trusted package source.

BYO/local plugins are outside the hosted 10x catalog guarantee. You are approving local executable plugin code directly.

1. Confirm the plugin source

   Verify the exact npm package, local path, or file URL you intend to install. Do not install from a mutable or unknown source.

2. Choose project or global scope

   Use project scope when the plugin should apply only to one workspace. Use global scope only when you want the plugin available across local OpenAnalyst workspaces.

3. Approve the local install

   OpenAnalyst requires explicit approval for non-built-in plugin installs. Confirm only after checking the source and intended scope.

4. Reload the workspace

   Reload or restart the workspace so OpenAnalyst can load the newly installed plugin.

5. Verify the app appears

   Open the app list and confirm the custom plugin appears. If it is installed but not visible, use the troubleshooting section below.

What good looks like

A healthy setup has these signals:

• The plugin is visible for the correct account, handle, workspace, or project.
• The install flow requires explicit user approval.
• The workspace was reloaded after install.
• The plugin appears in the OpenAnalyst app list.
• The plugin page renders with the expected app title and content.
• If 10x context is missing, the plugin shows a clear notice instead of a misleading empty table or zero-count dashboard.
• Risky actions such as publish, delete, refund, or external write ask for confirmation before they run.

For 10x-backed plugins, the browser UI should never show, store, or ask you to paste the runtime token used by the plugin server.

Optional validation checks

These checks are for support, advanced users, or local validation. They target the local OpenAnalyst runtime, not the hosted 10x catalog resolver.

Set OPENANALYST_LOCAL_URL to the local OpenAnalyst server URL support gives you.

Check the local catalog

curl "$OPENANALYST_LOCAL_URL/plugin/catalog"

Expected result: the response includes the plugin entry if it is visible locally.

Check installed plugins

curl "$OPENANALYST_LOCAL_URL/plugin/installed"

Expected result: the response includes the plugin after install approval.

Check loaded plugin apps

curl "$OPENANALYST_LOCAL_URL/plugin/apps"

Expected result: the response includes the custom plugin app id after workspace reload.

Check the plugin page manifest

Replace PLUGIN_APP_ID with the app id shown by /plugin/apps.

curl "$OPENANALYST_LOCAL_URL/plugin/apps/PLUGIN_APP_ID/page"

Expected result: the response includes a descriptor and a view. If the plugin needs 10x context and the context is missing, the view should explain that with a visible notice.

Check risky action confirmation

Only run this against a safe test record support has approved.

curl -X POST "$OPENANALYST_LOCAL_URL/plugin/apps/PLUGIN_APP_ID/action/ACTION_ID" \
  -H "Content-Type: application/json" \
  -d '{"blockId":"BLOCK_ID","rowId":"ROW_ID","confirmed":false}'

Expected result: risky actions reject the request until confirmation is supplied.

Troubleshooting

Related guides

• Smartwork and OpenAnalyst Access
• Apps and MCP Tools
• MCP Builder and Hosted Tools
• JWT Skill Management
• Provider-Backed MCP Bindings
• Troubleshooting and Support