# How OpenAI Manages and Deploys New Plugins: The Complete Codex Workflow

> Discover OpenAI's plugin management workflow: automated scaffolding, marketplace registration, and runtime deployment. Learn how they deploy new Codex plugins efficiently.

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

---

**OpenAI manages and deploys new Codex plugins through a standardized three-phase workflow: automated scaffolding via the Plugin Creator skill, registration in a marketplace.json index, and runtime deployment using Vercel CLI or containerized platforms with OIDC authentication.**

The `openai/plugins` repository implements a file-system-based convention that governs how OpenAI manages and deploys new plugins from initial concept to production. This architecture ensures every plugin adheres to a strict manifest schema, enabling the Codex UI to render capabilities uniformly while maintaining security through short-lived tokens rather than static API keys.

## Phase 1: Scaffolding with the Plugin Creator Skill

New plugins begin with the **Plugin Creator** skill, an automated scaffolding system defined in [`.agents/skills/plugin-creator/SKILL.md`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/SKILL.md). When developers invoke the creation script, it generates a minimal directory layout and writes the canonical [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) manifest.

Run the scaffolding command from the repository root:

```bash
python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py my-plugin \
  --with-marketplace

```

This command creates the following structure:

```text
my-plugin/
├── .codex-plugin/
│   └── plugin.json          # Manifest per plugin-json-spec.md

├── skills/
├── hooks/
├── assets/
├── .app.json
└── .mcp.json

```

The generated [`/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main//.codex-plugin/plugin.json) conforms to the JSON schema specified in [`.agents/skills/plugin-creator/references/plugin-json-spec.md`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/references/plugin-json-spec.md). This manifest declares the plugin's interface, capabilities, and category, ensuring the Codex UI can discover and render it correctly.

Example auto-generated manifest:

```json
{
  "name": "my-plugin",
  "version": "0.1.0",
  "description": "Brief plugin description",
  "author": {
    "name": "Author Name",
    "email": "author@example.com",
    "url": "https://github.com/author"
  },
  "homepage": "https://docs.example.com/plugin",
  "repository": "https://github.com/author/plugin",
  "license": "MIT",
  "keywords": ["example", "plugin"],
  "skills": "./skills/",
  "interface": {
    "displayName": "My Plugin",
    "shortDescription": "Short description for subtitle",
    "category": "Productivity",
    "capabilities": ["Interactive"]
  }
}

```

## Phase 2: Marketplace Registration

After scaffolding, the plugin must be indexed in a **marketplace.json** file so the Codex UI can discover it. The skill automatically updates the appropriate marketplace based on scope:

- **Personal plugins**: Register in `~/.agents/plugins/marketplace.json`
- **Repository-wide plugins**: Register in `<repo-root>/.agents/plugins/marketplace.json`

Each marketplace entry contains the source path, installation policy, authentication timing, and category. The `policy` block controls availability states including `AVAILABLE`, `INSTALLED_BY_DEFAULT`, or hidden status, allowing OpenAI to manage plugin rollouts granularly.

Example marketplace entry added by the `--with-marketplace` flag:

```json
{
  "name": "openai-curated",
  "interface": { "displayName": "ChatGPT Official" },
  "plugins": [
    {
      "name": "my-plugin",
      "source": { 
        "source": "local", 
        "path": "./plugins/my-plugin" 
      },
      "policy": { 
        "installation": "AVAILABLE", 
        "authentication": "ON_INSTALL" 
      },
      "category": "Productivity"
    }
  ]
}

```

The marketplace specification in [`.agents/skills/plugin-creator/references/plugin-json-spec.md`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/references/plugin-json-spec.md) defines all required fields for registry entries, ensuring consistency across the ecosystem.

## Phase 3: Runtime Deployment

The final phase pushes the plugin's runtime code to a hosting platform. The repository provides **Vercel-specific deployment documentation** in [`plugins/vercel/vercel.md`](https://github.com/openai/plugins/blob/main/plugins/vercel/vercel.md) that illustrates the standard rollout process using preview and production environments.

Deploy using the Vercel CLI workflow:

```bash

# From the plugin root directory

vercel                 # Creates a preview deployment

vercel --prod         # Promotes preview to production

```

This deployment method utilizes **short-lived OIDC tokens** (`VERCEL_OIDC_TOKEN`) rather than long-lived API keys, automatically handled by the Vercel authentication flow as documented in the Vercel deployment guide. For specialized requirements, individual plugin families include tailored deployment documentation—for example, the Zoom plugin family provides containerization and environment-variable configuration guides in [`plugins/zoom/skills/team-chat/concepts/deployment.md`](https://github.com/openai/plugins/blob/main/plugins/zoom/skills/team-chat/concepts/deployment.md).

The deployment process validates the plugin through [`quick_validate.py`](https://github.com/openai/plugins/blob/main/quick_validate.py) (referenced in the Plugin Creator skill documentation) before the marketplace entry makes it selectable for end users.

## Validation and Policy Controls

The workflow enforces consistency through automated validation and policy-driven availability controls. The **Plugin Creator** skill includes [`quick_validate.py`](https://github.com/openai/plugins/blob/main/quick_validate.py) to verify manifest integrity before deployment.

**Policy blocks** in marketplace entries determine user access:
- `AVAILABLE`: Users can manually install the plugin
- `INSTALLED_BY_DEFAULT`: Automatically enabled for eligible users
- Hidden states: Restricted access for internal testing or gradual rollouts

These controls allow OpenAI to manage plugin lifecycles from beta testing through general availability without code changes, simply by updating the marketplace.json policy field.

## Summary

- **Scaffolding automation**: The Plugin Creator skill in [`.agents/skills/plugin-creator/scripts/create_basic_plugin.py`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/scripts/create_basic_plugin.py) generates compliant directory structures and [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) manifests according to the canonical spec.
- **Centralized registry**: Plugins register in [`marketplace.json`](https://github.com/openai/plugins/blob/main/marketplace.json) files (personal or repo-wide) with structured entries controlling source paths and installation policies.
- **Secure deployment**: Vercel CLI commands (`vercel` and `vercel --prod`) deploy runtime code using OIDC tokens rather than static credentials, as documented in [`plugins/vercel/vercel.md`](https://github.com/openai/plugins/blob/main/plugins/vercel/vercel.md).
- **Policy governance**: The `policy` block in marketplace entries supports `AVAILABLE`, `INSTALLED_BY_DEFAULT`, and hidden states for granular rollout control.
- **Validation pipeline**: The [`quick_validate.py`](https://github.com/openai/plugins/blob/main/quick_validate.py) script ensures manifest integrity before the Codex UI exposes plugins to users.

## Frequently Asked Questions

### What is the Plugin Creator skill in OpenAI's repository?

The **Plugin Creator** skill is an automated scaffolding system located in `.agents/skills/plugin-creator/` that generates new plugin directory structures. It writes the required [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) manifest and optional companion directories (skills/, hooks/, assets/) while optionally registering the plugin in the appropriate [`marketplace.json`](https://github.com/openai/plugins/blob/main/marketplace.json) file.

### Where does the marketplace.json file live for personal vs. repo-wide plugins?

Personal plugins register in `~/.agents/plugins/marketplace.json` within the user's home directory, while repository-wide plugins use `<repo-root>/.agents/plugins/marketplace.json` at the repository root. Both follow the same schema defined in the marketplace specification.

### How does OpenAI handle authentication during plugin deployment?

OpenAI mandates **short-lived OIDC tokens** for authentication instead of long-lived API keys. When deploying via Vercel, the CLI automatically generates a `VERCEL_OIDC_TOKEN` that the Codex gateway reads. This approach, documented in [`plugins/vercel/vercel.md`](https://github.com/openai/plugins/blob/main/plugins/vercel/vercel.md), eliminates manual credential management and reduces security exposure.

### What deployment platforms does OpenAI support for Codex plugins?

The repository primarily documents **Vercel** deployment through [`plugins/vercel/vercel.md`](https://github.com/openai/plugins/blob/main/plugins/vercel/vercel.md), supporting serverless functions and microservices with preview and production environments. Individual plugin families like Zoom provide additional deployment guides for containerized environments and environment-variable configuration in paths like [`plugins/zoom/skills/team-chat/concepts/deployment.md`](https://github.com/openai/plugins/blob/main/plugins/zoom/skills/team-chat/concepts/deployment.md).