# How Marketplace Plugins Reference External Plugin Sources in OpenAI Plugins

> Learn how OpenAI marketplace plugins reference external plugin sources using the repository or url field in plugin.json. Discover how local directories act as wrappers for upstream Git repositories.

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

---

**Marketplace plugins in the openai/plugins repository reference external sources by defining a `repository` or `url` field in their [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) manifest, enabling the marketplace to treat the local directory as a thin wrapper that pulls code from upstream Git repositories at runtime.**

The openai/plugins repository powers the Codex plugin marketplace, where plugin metadata resides under the `plugins/` directory. While many plugins bundle all assets locally, marketplace plugins can reference external plugin sources using specific JSON manifest fields that point to upstream repositories, creating a wrapper pattern that separates localized metadata from distributed source code.

## Understanding the Plugin Manifest Structure

Every marketplace-ready plugin includes a [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) manifest that describes its identity, capabilities, and—crucially—its source location.

### The [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) File

Located at `plugins/<plugin-name>/.codex-plugin/plugin.json`, this manifest contains the metadata required by the marketplace UI and installer. When referencing external sources, the manifest uses these specific fields:

- **`repository`**: The definitive Git URL where the upstream plugin source code lives (e.g., `https://github.com/vercel/vercel-plugin`). The marketplace installer clones this URL to fetch the latest code.
- **`url`**: A direct URL to the upstream source repository, typically used by the marketplace UI to display "View source" links.
- **`source`**: Often included within `longDescription` or as a standalone field, indicating the human-readable upstream repo name (e.g., `vercel/vercel-plugin`).

## How External Source Detection Works

The marketplace distinguishes between fully local plugins and external-source wrappers through a specific detection process implemented in the source code.

### The Wrapper Pattern

When a manifest contains a `repository` field pointing outside the current repository, the local `plugins/<name>/` directory acts as a **thin wrapper**. This wrapper contains only metadata—such as icons, descriptions, and the manifest file—while the actual skill modules, agents, and commands reside in the external repository.

### Detection Logic

As implemented in openai/plugins, the marketplace code reads each plugin's manifest and checks the `repository` field. If the value starts with `https://` and does not resolve to a path inside the current repository, the system flags the plugin as having an external source.

```python
import json
import pathlib

def load_plugin_manifest(name: str) -> dict:
    """Load manifest and detect external source references."""
    manifest_path = pathlib.Path("plugins") / name / ".codex-plugin" / "plugin.json"
    
    with manifest_path.open() as f:
        data = json.load(f)
    
    # Detect external source

    if data.get("repository", "").startswith("https://"):
        data["is_external"] = True
    else:
        data["is_external"] = False
    
    return data

```

## Installation and Runtime Behavior

Referencing external sources changes how the marketplace handles plugin installation and updates.

### Four-Stage External Source Workflow

1. **Discovery**: The marketplace enumerates all directories under `plugins/` and reads each manifest at `plugins/<name>/.codex-plugin/plugin.json`.
2. **External Source Detection**: If the manifest includes a `repository` URL that does not resolve to the local repository, the marketplace records it as an external source.
3. **Installation**: When a user installs the plugin, the marketplace clones the external repository (using the `repository` URL) into a temporary sandbox, then loads assets from that location.
4. **Updates**: Because the source is external, updates pull automatically from the upstream repo on subsequent launches, ensuring the wrapper always reflects the latest upstream code.

This workflow enables a **single source-of-truth** model where developers maintain code in dedicated repositories while the openai/plugins repo hosts only the metadata wrapper.

## Real-World Implementation Examples

### Example 1: Vercel Plugin Wrapper

The Vercel plugin in [`plugins/vercel/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/vercel/.codex-plugin/plugin.json) demonstrates a minimal wrapper pointing to an external repository:

```json
{
  "name": "vercel",
  "displayName": "Vercel",
  "description": "Bring Vercel ecosystem guidance into Codex.",
  "url": "https://github.com/vercel",
  "repository": "https://github.com/vercel/vercel-plugin",
  "icon": "assets/icon.png",
  "longDescription": "Packages the upstream vercel/vercel-plugin skills, agents, and commands under the local `vercel` plugin identity for the Codex plugin marketplace."
}

```

### Example 2: Shopify Plugin Wrapper

Similarly, the Shopify wrapper in [`plugins/shopify/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/shopify/.codex-plugin/plugin.json) references a third-party repository:

```json
{
  "name": "shopify",
  "displayName": "Shopify",
  "description": "Shopify AI Toolkit integration.",
  "url": "https://github.com/Shopify",
  "repository": "https://github.com/Shopify/Shopify-AI-Toolkit",
  "icon": "assets/logo.png",
  "longDescription": "Provides Shopify store management capabilities by delegating to the upstream Shopify-AI-Toolkit repository."
}

```

### Key Files in the Repository

- **[`plugins/vercel/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/vercel/.codex-plugin/plugin.json)**: Demonstrates a wrapper that points to `https://github.com/vercel/vercel-plugin`.
- **[`plugins/shopify/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/shopify/.codex-plugin/plugin.json)**: Shows external source referencing for third-party integrations.
- **[`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json)**: The registry listing all marketplace plugins, including those with external source entries.
- **`plugins/<plugin>/README.md`**: Per-plugin documentation that typically references the upstream repository for implementation details.

## Summary

- Marketplace plugins reference external sources using the `repository` and `url` fields in [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json).
- The local directory acts as a thin wrapper containing only metadata, while actual code lives in the external repository.
- External plugins are detected when the `repository` field contains an `https://` URL outside the current repo.
- During installation, the marketplace clones the external repository into a sandbox and loads assets from there.
- This pattern maintains a single source of truth for plugin code while allowing centralized marketplace discovery.

## Frequently Asked Questions

### How does the marketplace know if a plugin uses an external source?

The marketplace checks the `repository` field in `plugins/<name>/.codex-plugin/plugin.json`. If this field contains an HTTPS URL that does not resolve to a path inside the openai/plugins repository, the system flags it as an external source and sets `is_external` to true during manifest loading.

### What is the difference between the `url` and `repository` fields in plugin.json?

The `repository` field provides the definitive Git URL used by the marketplace installer to clone the actual plugin code, while the `url` field typically points to the organization's homepage or repository root for UI display purposes. The installer relies on `repository` for code retrieval, whereas `url` drives "View source" links in the marketplace interface.

### Can a marketplace plugin reference any public Git repository?

Yes, as long as the `repository` field contains a valid HTTPS Git URL and the repository structure matches the expected Codex plugin format. The marketplace clones this repository during installation, so the external source must be publicly accessible or use authentication methods supported by the marketplace installer.

### Where does the marketplace store the external plugin code after installation?

The marketplace clones the external repository into a temporary sandbox environment during installation. The wrapper's local `plugins/<name>/` directory only contains the manifest and metadata, while the actual skills, agents, and commands are loaded from the cloned external source at runtime.