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

> Discover how plugins surface in the Codex Marketplace via a declarative manifest system. This technical deep dive explains the JSON merging process that populates the UI and API.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: deep-dive
- Published: 2026-09-11

---

**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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/./.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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:

```javascript
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:

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

```

The JSON response mirrors the merged view of [`api_marketplace.json`](https://github.com/openai/plugins/blob/main/api_marketplace.json) and the individual plugin descriptors.

## Summary

- **Dual manifest system**: [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json) for personal use and [`.agents/plugins/api_marketplace.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json) or [`.agents/plugins/api_marketplace.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json) serves local Codex instances and individual users, while [`.agents/plugins/api_marketplace.json`](https://github.com/openai/plugins/blob/main/.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.