What the marketplace.json File Defines in OpenAI Plugins

The marketplace.json file acts as the central manifest for the OpenAI Plugins repository, defining the complete catalog of discoverable plugins along with their source paths, installation policies, and authentication rules.

The marketplace.json file serves as the single source of truth for plugin discovery in the OpenAI Plugins ecosystem. Located by default at .agents/plugins/marketplace.json, this JSON manifest enumerates all officially supported plugins that Codex and other OpenAI agents can load. Understanding its structure is essential for developers who want to register new plugins or build custom agents that consume the plugin catalog.

Structure of the marketplace.json File

The manifest consists of three primary sections that define the marketplace metadata and plugin inventory.

name and interface Fields

The name field specifies the logical identifier for the marketplace itself (e.g., "openai-curated"). The interface object contains UI-level metadata, including the displayName that surfaces in marketplace interfaces.

The plugins Array

Each entry in the plugins array is a plugin descriptor containing:

• name – The unique plugin identifier
• source – Location data with source: "local" and a relative path pointing to the plugin directory
• policy – Rules governing installation (e.g., "AVAILABLE") and authentication (e.g., "ON_INSTALL")
• category – High-level grouping for UI filtering (e.g., "Productivity")

How Plugin Discovery Uses marketplace.json

The plugin-discovery system leverages this manifest to perform three critical functions:

1. Enumerate supported plugins – Generates the complete list of agents available to OpenAI products like Codex
2. Resolve source directories – Maps plugin names to their physical locations so the runtime can load each plugin's .codex-plugin/plugin.json and associated assets
3. Apply security policies – Enforces installation and authentication rules that dictate when plugins are shown, how users grant permissions, and which products can access them (e.g., products: ["CODEX"])

Working with marketplace.json

Adding a New Plugin Entry

To register a new plugin, append an object to the plugins array in .agents/plugins/marketplace.json:

{
  "name": "my-awesome-plugin",
  "source": {
    "source": "local",
    "path": "./plugins/my-awesome-plugin"
  },
  "policy": {
    "installation": "AVAILABLE",
    "authentication": "ON_INSTALL"
  },
  "category": "Productivity"
}

The new plugin becomes immediately discoverable by any agent that reads the manifest.

Loading the Manifest in Node.js

Agents consume marketplace.json to discover available plugins programmatically. The following pattern mirrors how Codex internally handles plugin discovery:

import fs from 'fs';
import path from 'path';

const marketplacePath = path.join(
  process.env.HOME,
  '.agents',
  'plugins',
  'marketplace.json'
);
const marketplace = JSON.parse(fs.readFileSync(marketplacePath, 'utf8'));

for (const plugin of marketplace.plugins) {
  console.log(`Found plugin ${plugin.name} in ${plugin.source.path}`);
}

This snippet reads the manifest from the default location and iterates over every plugin entry.

Checking Installation Policies

You can query the manifest to determine if a plugin is available for installation:

function canInstall(pluginName) {
  const p = marketplace.plugins.find(p => p.name === pluginName);
  return p?.policy?.installation === 'AVAILABLE';
}

This function checks the policy.installation field to verify availability before attempting installation.

Related Files and Automation

Several utilities in the repository interact with marketplace.json:

• .agents/skills/plugin-creator/scripts/create_basic_plugin.py – Scaffolds new plugins and optionally updates marketplace.json with new entries
• .agents/skills/plugin-creator/references/plugin-json-spec.md – Documents marketplace file locations for personal versus repository-wide configurations
• README.md (lines 10-12) – Documents the default location and relationship to api_marketplace.json

Summary

• The marketplace.json file is the canonical manifest located at .agents/plugins/marketplace.json that defines all discoverable plugins in the OpenAI Plugins repository.
• It contains three main sections: name (marketplace identifier), interface (UI metadata), and plugins (array of plugin descriptors).
• Each plugin descriptor specifies the source path for loading, policy rules for installation and authentication, and category for organization.
• The discovery system uses this file to enumerate plugins, resolve their directories, and enforce access policies for OpenAI agents including Codex.

Frequently Asked Questions

Where is the marketplace.json file located in the OpenAI Plugins repository?

By default, marketplace.json resides in the .agents/plugins/ directory at the repository root. According to the repository's README.md, this location serves as the standard path for the central plugin catalog, though agents can also check user-specific directories like ~/.agents/plugins/ for personal marketplace configurations.

What fields are required when defining a plugin in marketplace.json?

Each plugin entry must include a name (unique identifier), a source object containing source: "local" and a relative path to the plugin directory, and a policy object defining installation status (typically "AVAILABLE") and authentication requirements (such as "ON_INSTALL"). The category field provides optional but recommended UI grouping.

How does Codex use the marketplace.json file for plugin discovery?

Codex and other OpenAI agents read marketplace.json to enumerate available plugins, resolve each plugin's source directory to load its .codex-plugin/plugin.json manifest, and apply installation policies that control which plugins appear in the UI and what permissions they require. This process is documented in the plugin-eval README (lines 143-148).

Can I manually edit marketplace.json to add custom plugins?

Yes, you can manually append plugin descriptors to the plugins array in .agents/plugins/marketplace.json, or use the provided Python utility at .agents/skills/plugin-creator/scripts/create_basic_plugin.py which automates the scaffolding and registration process. When editing manually, ensure the source.path points to a valid directory containing a proper .codex-plugin/plugin.json file.

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