How Plugins Are Surfaced in the Codex Marketplace: A Technical Deep Dive

Plugins are surfaced in the marketplace through a declarative manifest system that merges JSON marketplace entries with individual plugin descriptors to populate the Codex UI and API endpoints.

The OpenAI plugins repository implements a dual-manifest architecture to discover and present plugins to users. Understanding how plugins are surfaced in the marketplace requires examining the relationship between central marketplace manifests and individual plugin metadata files.

The Core Marketplace Manifest Architecture

The Codex marketplace relies on two primary JSON configuration files that share an identical schema. These manifests serve as the authoritative registry for all available plugins.

Personal User-Level Marketplace

The personal marketplace lives at .agents/plugins/marketplace.json in the repository root, which corresponds to ~/.agents/plugins/marketplace.json in user environments. This file acts as the default registry for individual Codex instances, containing an array of plugin entries under the plugins key.

API-Focused Marketplace

For public programmatic access, the repository maintains .agents/plugins/api_marketplace.json. This manifest powers the /v1/plugins REST API endpoint and surfaces the same plugin catalog to external consumers. Both files specify name, interface, and plugins[] properties to define the marketplace scope.

The Four-Step Discovery Process

When Codex initializes, it executes a deterministic resolution pipeline to surface plugins from these manifests.

1. Manifest Loading

The system loads either the personal or API marketplace manifest depending on the context. In the openai/plugins source code, this corresponds to reading the top-level file ./.agents/plugins/marketplace.json or the API variant.

2. Plugin Entry Iteration

For each object in the plugins[] array, Codex reads the source.path property. This relative path points to a local plugin directory containing the detailed metadata.

3. Descriptor Resolution and Merging

Codex locates the companion plugin descriptor at {source.path}/.codex-plugin/plugin.json. For example, the Linear plugin descriptor resides at plugins/linear/.codex-plugin/plugin.json. The system then merges this descriptor data—including displayName, icons, longDescription, and privacy URLs—with the marketplace entry's policy and category metadata.

4. Marketplace Exposure

The merged objects populate the Plugin Store UI and the /v1/plugins API endpoint. This combined view represents the final marketplace item presented to users for browsing, installation, and authentication.

Policy Controls for Marketplace Visibility

The policy field in marketplace entries governs how plugins appear and behave:

• installation: "AVAILABLE" – Surfaces the plugin in the marketplace browse view, allowing users to install it.
• authentication: "ON_INSTALL" – Triggers authentication prompts immediately upon installation.
• authentication: "ON_USE" – Defers authentication until the plugin is first invoked.
• products: ["CODEX"] – Restricts visibility to specific Codex products, filtering the plugin from incompatible interfaces.

Remote Source Support

Beyond local directories, the marketplace supports remote sources through the source: "url" property. These entries still appear in marketplace.json but resolve to external git repositories at runtime, enabling third-party plugins to appear alongside official ones in the marketplace UI.

Practical Implementation Examples

Node.js Marketplace Loader

The following script mirrors Codex's internal discovery process, loading the personal marketplace and resolving plugin descriptors:

const fs = require('fs');
const path = require('path');

function loadMarketplace(manifestPath) {
  const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
  const plugins = manifest.plugins.map(p => {
    const pluginJsonPath = path.join(
      path.dirname(manifestPath), '..', p.source.path, '.codex-plugin', 'plugin.json'
    );
    const descriptor = JSON.parse(fs.readFileSync(pluginJsonPath, 'utf8'));
    return {
      name: p.name,
      displayName: descriptor.interface.displayName,
      category: p.category,
      policy: p.policy,
      description: descriptor.interface.longDescription,
    };
  });
  return plugins;
}

// Personal marketplace
const marketplace = loadMarketplace(path.resolve(__dirname, '.agents/plugins/marketplace.json'));
console.log(marketplace);

Querying the Public API Marketplace

To retrieve the same plugin list programmatically via the public endpoint:

curl https://api.openai.com/v1/plugins \
  -H "Authorization: Bearer $OPENAI_API_KEY"

The JSON response mirrors the merged view of api_marketplace.json and the individual plugin descriptors.

Summary

• Dual manifest system: .agents/plugins/marketplace.json for personal use and .agents/plugins/api_marketplace.json for API consumers.
• Descriptor merging: Each marketplace entry combines with {source.path}/.codex-plugin/plugin.json to create the final marketplace item.
• Policy-driven visibility: Fields like installation, authentication, and products control when and how users see plugins.
• Multi-interface exposure: The same discovery pipeline feeds both the Plugin Store UI and the /v1/plugins REST endpoint.
• Extensible sources: Remote URL sources allow external plugins to surface in the marketplace alongside local ones.

Frequently Asked Questions

How does Codex determine which plugins to show in the marketplace?

Codex reads the plugins array from either .agents/plugins/marketplace.json or .agents/plugins/api_marketplace.json. It filters entries based on the policy field—specifically checking installation status and products compatibility—then merges valid entries with their respective plugin.json descriptors before displaying them.

Can third-party plugins appear in the official Codex marketplace?

Yes. The manifest supports source: "url" entries pointing to external git repositories. As long as the remote plugin includes a valid .codex-plugin/plugin.json descriptor and the marketplace entry includes appropriate policy metadata, these plugins surface alongside official ones in the UI and API.

What is the difference between the personal and API marketplace files?

.agents/plugins/marketplace.json serves local Codex instances and individual users, while .agents/plugins/api_marketplace.json powers the public /v1/plugins endpoint. Both use identical JSON schemas but may contain different plugin subsets based on distribution requirements and access controls.

Where does the plugin description and icon come from?

Visual and descriptive metadata originates from the individual plugin descriptor at {source.path}/.codex-plugin/plugin.json, not the central marketplace manifest. Codex merges these details—such as displayName, longDescription, and icon URLs—with the policy and category data from the marketplace entry to create the final presentation object.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}