What Information Does a Marketplace JSON Entry Contain?

A marketplace JSON entry defines a single plugin's identity, source location, installation policy, authentication requirements, and optional UI metadata through a structured JSON object stored in .agents/plugins/marketplace.json.

The openai/plugins repository manages plugin distribution for OpenAI Codex through a centralized registry. Each marketplace JSON entry specifies the essential metadata required for the runtime to discover, validate, and surface plugins to users according to the source code definitions.

Core Structure of a Marketplace JSON Entry

The canonical source of truth resides in .agents/plugins/marketplace.json. According to the repository implementation, each entry follows a standardized schema containing six top-level keys that describe where the plugin's code lives, how it is installed, what authentication model it uses, and the functional category it belongs to.

The structure includes:

• name: Unique identifier for the plugin
• source: Code location and retrieval method configuration
• policy: Installation availability and authentication rules
• category: High-level functional classification
• interface: Optional user-facing display metadata

Required Fields in a Marketplace JSON Entry

name

The name field serves as the unique identifier for the plugin within the marketplace. This value must be distinct across all entries in .agents/plugins/marketplace.json and is used as the internal reference by the Codex runtime.

Example: "name": "linear"

source

The source object specifies where the plugin code resides and how to retrieve it. The object requires a source key indicating the retrieval method, with additional keys varying by type.

The repository supports three retrieval methods:

• local: References a directory inside the repository using a path relative to the repository root
• url: Points to an external Git repository via a url string
• git-subdir: Targets a specific subdirectory within a remote Git repository using both url and path keys

policy

The policy object governs the plugin's lifecycle and access controls through required and optional sub-fields:

• installation: Defines availability status. The value "AVAILABLE" allows users to discover and install the plugin through the marketplace interface.
• authentication: Specifies when user credentials are required. Values include "ON_INSTALL" (required during initial setup) or "ON_USE" (required at runtime when invoking the plugin).
• products (optional): Restricts the plugin to specific OpenAI products. For example, ["CODEX"] limits availability to the Codex environment.

category

The category field assigns a high-level classification for UI organization in the marketplace. Common values found in the source include "Productivity", "Developer Tools", "Communication", and "Creativity".

Optional Interface Metadata

displayName and UI Fields

The optional interface object contains user-facing presentation data. The primary field is displayName, which provides a human-readable label shown in the marketplace UI instead of the technical name value.

Additional UI metadata such as icons and descriptions may be included within this object to enhance the marketplace presentation, though these fields are not required for functional plugin operation.

Source Configuration Examples

Different source types require specific field combinations as implemented in the repository.

Local Plugin Configuration

For plugins stored within the openai/plugins repository itself:

{
  "name": "gmail",
  "source": {
    "source": "local",
    "path": "./plugins/gmail"
  },
  "policy": {
    "installation": "AVAILABLE",
    "authentication": "ON_INSTALL"
  },
  "category": "Communication"
}

Remote URL Plugin

For external Git repositories where the plugin resides at the root:

{
  "name": "crowdstrike-falcon-foundry",
  "source": {
    "source": "url",
    "url": "https://github.com/CrowdStrike/foundry-skills.git"
  },
  "policy": {
    "installation": "AVAILABLE",
    "authentication": "ON_INSTALL"
  },
  "category": "Developer Tools",
  "interface": {
    "displayName": "CrowdStrike Falcon Foundry"
  }
}

Git-Subdir Plugin

For repositories containing multiple plugins in specific subdirectories:

{
  "name": "qodo",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/qodo-ai/qodo-skills.git",
    "path": "codex-packages/qodo"
  },
  "policy": {
    "installation": "AVAILABLE",
    "authentication": "ON_INSTALL"
  },
  "category": "Developer Tools",
  "interface": {
    "displayName": "Qodo"
  }
}

Related Configuration Files

While .agents/plugins/marketplace.json serves as the master registry, the ecosystem includes supplementary files that support the marketplace infrastructure.

The file .agents/plugins/api_marketplace.json defines API-level capabilities and runtime validation schemas used by the Codex system to process marketplace requests. Additionally, individual plugin directories may contain plugins/*/.app.json files with application-specific metadata such as app IDs that may be referenced by the corresponding marketplace entries.

Summary

• Each marketplace JSON entry in openai/plugins is defined in .agents/plugins/marketplace.json and requires name, source, policy, and category fields.
• The source object supports three retrieval modes: local, url, and git-subdir, each requiring different location parameters (path for local/git-subdir, url for remote sources).
• Installation policies control availability through policy.installation (set to "AVAILABLE" to enable), while policy.authentication determines whether credentials are required "ON_INSTALL" or "ON_USE".
• Optional interface metadata provides human-readable displayName values and UI customization data to enhance marketplace presentation.
• The policy.products array can restrict plugins to specific OpenAI products such as ["CODEX"].

Frequently Asked Questions

What file contains the marketplace JSON entries for OpenAI plugins?

The master registry resides at .agents/plugins/marketplace.json in the openai/plugins repository. This file serves as the single source of truth for all plugins available through the Codex marketplace, containing the complete structured list of plugin metadata entries that the runtime uses for discovery and validation.

What is the difference between "url" and "git-subdir" source types?

The url source type points to the root of a Git repository, treating the entire repository content as the plugin source code. The git-subdir source type specifies both a repository url and a path subdirectory within that repository, allowing multiple plugins to reside in different folders of a single external repository while targeting only the relevant subdirectory for installation.

How do you restrict a plugin to specific OpenAI products?

Use the optional policy.products array field in the marketplace JSON entry. By including specific product identifiers such as ["CODEX"] in this array, the entry limits installation and usage to users of those designated OpenAI products, preventing the plugin from appearing in unsupported platforms or environments.

Is the interface field required for all marketplace entries?

No, the interface field is optional. While required fields including name, source, policy, and category must be present for the entry to function in the Codex runtime, the interface object only needs to be included when providing user-facing display metadata such as displayName, icons, or descriptions that enhance the marketplace presentation layer.

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