# How to Publish Your Developed Plugin to the Codex Marketplace

> Publish your custom plugin to the Codex Marketplace! Follow our guide to create a manifest, register your plugin, and merge changes to the openai plugins repository.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: how-to-guide
- Published: 2026-06-29

---

**To publish your plugin to the Codex Marketplace, create a directory under `plugins/`, add a valid [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) manifest, register the entry in [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json), and merge your changes into the `main` branch of the `openai/plugins` repository.**

The `openai/plugins` repository hosts the official Codex Marketplace, which functions as a conventional Git-based index that Codex-enabled tools scan to discover available extensions. When you publish your developed plugin by submitting a manifest and registering it in the marketplace index, it becomes immediately discoverable by all Codex CLI users.

## Create the Plugin Directory

Begin by creating a new folder under the `plugins/` directory in the repository root. The marketplace scanner monitors this directory to identify available plugins.

For example, if your plugin is named "my-awesome-plugin", create:

```

plugins/my-awesome-plugin/

```

## Add the Required Plugin Manifest

Inside your plugin directory, create the file [`plugins/my-awesome-plugin/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/my-awesome-plugin/.codex-plugin/plugin.json). This manifest tells Codex how to load the plugin and what commands or skills it provides.

The file must contain required fields including `name`, `description`, `version`, `author`, and `entryPoints`. Here is a minimal valid example:

```json
{
  "name": "my-awesome-plugin",
  "shortDescription": "A demo plugin for Codex",
  "description": "Provides a simple command that echoes back the user's input.",
  "version": "0.1.0",
  "author": "Your Name <you@example.com>",
  "entryPoints": {
    "commands": [
      {
        "name": "echo",
        "description": "Echo back the supplied text",
        "script": "scripts/echo.js"
      }
    ]
  }
}

```

*See a real-world implementation in the Zoom plugin at [`plugins/zoom/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/zoom/.codex-plugin/plugin.json).*

## Register in the Marketplace Index

To make your plugin discoverable, add an entry to the central marketplace index file [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json). This file serves as the canonical list of all publicly available plugins.

Add a JSON object pointing to your plugin directory:

```json
[
  {
    "name": "my-awesome-plugin",
    "path": "plugins/my-awesome-plugin"
  }
]

```

## Validate with Repository CI

Verify your manifest conforms to repository standards before submitting by running the linting suite:

```bash
npm test

```

The repository also runs a CI workflow defined in [`.github/workflows/ci.yml`](https://github.com/openai/plugins/blob/main/.github/workflows/ci.yml) on each pull request. This prevents malformed plugins from breaking the marketplace index.

## Submit and Merge Your Changes

Commit your changes to the `main` branch or open a pull request. Once the PR is merged, the CI pipeline automatically publishes the updated marketplace. Because the marketplace is a live-updating Git repository, merging makes your plugin immediately available to all Codex-enabled environments.

## Test Your Plugin Locally

Optionally verify functionality before publishing using the Codex CLI:

```bash

# From the repository root

codex-cli plugin install plugins/my-awesome-plugin

# Verify the plugin appears in the list

codex-cli plugin list

```

This confirms the plugin loads correctly before you submit it to the public index.

## Optional: API-Key Marketplace Registration

If you want your plugin discoverable only when users authenticate with an API key, also add an entry to [`.agents/plugins/api_marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/api_marketplace.json). This separate index handles authenticated-only plugins while [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json) remains for public access.

## Summary

- **Create a directory** under `plugins/` for your plugin files.
- **Add a manifest** at [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) with required metadata including `name`, `version`, `author`, and `entryPoints`.
- **Register publicly** by adding an entry to [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json).
- **Validate** your changes with `npm test` or the CI workflow in [`.github/workflows/ci.yml`](https://github.com/openai/plugins/blob/main/.github/workflows/ci.yml).
- **Merge to `main`** to make the plugin live in the Codex Marketplace.
- **Test locally** using `codex-cli plugin install` before submitting.

## Frequently Asked Questions

### What fields are required in the plugin.json manifest?

The [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) manifest must include `name`, `description`, `version`, `author`, and `entryPoints`. The `entryPoints` object defines the plugin's capabilities, such as commands. Refer to the example in [`plugins/zoom/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/zoom/.codex-plugin/plugin.json) for a complete implementation.

### How long does it take for my plugin to appear in the marketplace after merging?

Your plugin becomes available immediately after your pull request is merged into the `main` branch. The Codex Marketplace is a Git-based index that updates automatically when the CI pipeline processes the merged changes.

### Can I publish private plugins that require API key authentication?

Yes. In addition to registering in [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json), add an entry to [`.agents/plugins/api_marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/api_marketplace.json). This secondary index is specifically for plugins that should only appear when users authenticate with an API key.

### How do I update an existing plugin in the marketplace?

Modify the plugin files in your existing `plugins/<plugin-name>/` directory and update the `version` field in [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json). After merging these changes to `main`, the marketplace updates automatically. You do not need to modify the marketplace index files unless you change the plugin path or name.