For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.

Expose the agentregistry plugin catalog as a private Claude Code plugin marketplace.

Solo Enterprise for agentregistry can serve its plugin catalog as a Claude Code-compatible plugin marketplace. When enabled, Claude Code and other AI coding assistants can browse and install plugins directly from your private registry, without going through a public marketplace.

The registry exposes a read-only marketplace.json endpoint at:

GET http://localhost:12121/plugin-marketplace/marketplace.json

Access control

Every request to the /plugin-marketplace/marketplace.json path goes through the same access control layers as the rest of the registry catalog.

• Layer 1 authentication. A request to the plugin marketplace requires a valid bearer token. Requests with an expired or invalid token get a 401 Unauthorized HTTP response.
• Layer 2: User authorization. The endpoint enforces the AccessPolicy rules that you set up for the registry. Users see only the plugins that they have registry:read access to.

Limitations

• Plugin names in the marketplace are namespaced as namespace.plugin-name, such as default.my-plugin to avoid collisions across namespaces. Plugins that you publish without a metadata.namespace field are automatically created in the default namespace. Note that arctl get plugins does not show the namespace that the plugin was stored in.
• Only git-sourced plugins where the registry server was able to resolve the git source and pin it to a commit appear in the marketplace. OCI-sourced plugins are not included in the marketplace.json format. Plugins that are still resolving or failed to resolve are silently omitted.

Before you begin

1. Set up an OIDC provider so that users can authenticate with the registry.

2. Install Solo Enterprise for agentregistry and the arctl CLI.

3. Port-forward the Solo Enterprise for agentregistry server on port 12121 if you have not done so already. The registry is not exposed externally by default, so you need port-forwarding to reach it from your local machine.

   kubectl -n agentregistry-system port-forward svc/agentregistry-enterprise-server 12121:12121

4. Publish at least one plugin.
5. Create an AccessPolicy that grants registry:read access on the plugins that you want to be visible in the marketplace. For more information about how the registry authenticates and authorizes requests, see About access control.
6. If you plan to register the marketplace with Claude Code, expose the registry through an ingress gateway that terminates HTTPS in front of it. To test the marketplace without Claude Code, you can run a curl request against the marketplace endpoint on the localhost address that you port-forwarded.

Enable the marketplace endpoint

The marketplace endpoint is disabled by default. Enable it by setting the AGENT_REGISTRY_PLUGIN_MARKETPLACE_COMPAT_ENABLED environment variable to true on the registry server.

1. Upgrade the Helm release to pass the environment variable to the registry server.

   helm upgrade -i agentregistry \
     oci://us-docker.pkg.dev/solo-public/agentregistry-enterprise/helm/agentregistry-enterprise \
     --namespace agentregistry-system \
     --version 2026.9.0 \
     --reuse-values \
     --set-string "extraEnvVars[0].name=AGENT_REGISTRY_PLUGIN_MARKETPLACE_COMPAT_ENABLED" \
     --set-string "extraEnvVars[0].value=true"

   Warning

   The extraEnvVars[0] syntax writes to the first entry in the list. If your release already sets other extra environment variables, add this variable to your Helm values file instead, so that you do not overwrite an existing entry.

2. Verify that the registry server restarted with the new environment variable.

   kubectl -n agentregistry-system get deploy agentregistry-enterprise-server \
     -o jsonpath='{.spec.template.spec.containers[0].env[?(@.name=="AGENT_REGISTRY_PLUGIN_MARKETPLACE_COMPAT_ENABLED")].value}'

   Example output:

   true
   

3. Confirm that the endpoint now enforces authentication. A request without a bearer token is rejected with a 401 HTTP response.

   curl -i http://localhost:12121/plugin-marketplace/marketplace.json

   Example output:

   HTTP/1.1 401 Unauthorized
   

4. Repeat the request with a bearer token from a user who has registry:read permissions on at least one plugin, and confirm that the response lists only the plugins that the role can read.

   curl -sS -H "Authorization: Bearer $(arctl user info --show-tokens | jq -r '.access_token')" \
     http://localhost:12121/plugin-marketplace/marketplace.json | jq -r '.plugins[].name'

   Example output:

   default.hello-plugin
   

Register the plugin marketplace in Claude Code

Because the marketplace endpoint requires a bearer token for authentication, you cannot use the claude plugin marketplace add <url> command to register the plugin in Claude Code as the command does not attach an Authorization header to requests that are sent to the marketplace endpoint. Instead, you must configure the marketplace in the Claude Code settings file directly by using a headersHelper command that supplies a fresh token on each request.

1. Save the HTTPS URL that Claude Code uses to reach the marketplace endpoint in an environment variable. Use the ingress or gateway host that you set up in Before you begin, not the localhost address that you port-forwarded earlier. Claude Code sends the Authorization header only to an https:// URL.

   export AR_MARKETPLACE_URL=https://registry.example.com/plugin-marketplace/marketplace.json

2. Create a script that prints the Authorization header as a JSON object, and make it executable. Claude Code runs this script before it fetches the plugins from the marketplace.json endpoint.

   mkdir -p ~/.claude/scripts
   cat > ~/.claude/scripts/agentregistry-marketplace-headers.sh <<'EOF'
   #!/usr/bin/env bash
   set -euo pipefail
   arctl user whoami >/dev/null 2>&1 || true
   arctl user info --show-tokens | jq -cr '{Authorization: ("Bearer " + .access_token)}' \
     || { echo "No valid session. Run 'arctl user login' and try again." >&2; exit 1; }
   EOF
   chmod +x ~/.claude/scripts/agentregistry-marketplace-headers.sh

   Note

   Claude Code runs the headersHelper value as a shell command, and waits up to 10 seconds for it to print one line of JSON to stdout. Make sure to set the headersHelper field to the path of that shell script. Do not add the content of that script to that field as Claude Code caps the headersHelper field at 500 characters.

3. Add the marketplace to the extraKnownMarketplaces block in your Claude Code settings. Use ~/.claude/settings.json to make the marketplace available in every project. Do not use a project .claude/settings.json for this entry, because Claude Code honors it only after you accept the workspace trust dialog for that folder, and removes environment variables such as ARCTL_TOKEN_FILE from the headersHelper command. The following example merges the entry into ~/.claude/settings.json with jq, so that an existing extraKnownMarketplaces entry, or any other setting in the file, is preserved. Run these commands in the same shell session as step 1, so that $AR_MARKETPLACE_URL is still set.

   settings_path=~/.claude/settings.json
   test -f "$settings_path" || echo '{}' > "$settings_path"
   tmp=$(mktemp)
   jq --arg url "$AR_MARKETPLACE_URL" \
     '.extraKnownMarketplaces.agentregistry.source = {
       source: "url",
       url: $url,
       headersHelper: "~/.claude/scripts/agentregistry-marketplace-headers.sh"
     }' "$settings_path" > "$tmp" && mv "$tmp" "$settings_path"
   jq '.extraKnownMarketplaces.agentregistry' "$settings_path"

   Example output:

   {
     "source": {
       "source": "url",
       "url": "https://registry.example.com/plugin-marketplace/marketplace.json",
       "headersHelper": "~/.claude/scripts/agentregistry-marketplace-headers.sh"
     }
   }
   

   Setting	Description
   source	The marketplace source type. Use url to point Claude Code at a marketplace.json file that the registry serves.
   url	The HTTPS URL of the marketplace endpoint. Claude Code sends the Authorization header only to an https:// URL.
   headersHelper	The path to the script that prints the Authorization header. Give an absolute path, or a path relative to ~/.claude, because Claude Code runs the command from its configuration directory.

4. Start or restart Claude Code, then confirm that it registered the marketplace and fetched the catalog.

   claude plugin marketplace list

   Example output:

   Configured marketplaces:
   
     ❯ agentregistry
       Source: URL (https://registry.example.com/plugin-marketplace/marketplace.json)
   

   If the marketplace does not appear in this list, open an interactive Claude Code session and check the /plugin path before you continue troubleshooting. The interactive session triggers a plugin reload.

5. Install a plugin from the catalog. Use the name that the plugin has in the marketplace. Note that you must include the namespace, such as default.hello-plugin.

   claude plugin install default.hello-plugin@agentregistry

   Example output:

   ✔ Successfully installed plugin: default.hello-plugin@agentregistry (scope: user)
   

6. Verify that the plugin is installed and enabled.

   claude plugin list

   Example output:

   Installed plugins:
   
     ❯ default.hello-plugin@agentregistry
       Version: 1.0.0
       Scope: user
       Status: ✔ enabled
   

claude plugin marketplace update agentregistry