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

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. When developers invoke the creation script, it generates a minimal directory layout and writes the canonical plugin.json manifest.

Run the scaffolding command from the repository root:

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

This command creates the following structure:

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 conforms to the JSON schema specified in .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:

{
  "name": "my-plugin",
  "version": "0.1.0",
  "description": "Brief plugin description",
  "author": {
    "name": "Author Name",
    "email": "[email protected]",
    "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:

{
  "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 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 that illustrates the standard rollout process using preview and production environments.

Deploy using the Vercel CLI workflow:

# 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.

The deployment process validates the plugin through 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 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 generates compliant directory structures and plugin.json manifests according to the canonical spec.
• Centralized registry: Plugins register in 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.
• 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 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 manifest and optional companion directories (skills/, hooks/, assets/) while optionally registering the plugin in the appropriate 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, 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, 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.

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