Internal Plugin Marketplaces

Internal Plugin Marketplaces are private plugin catalogs where organizations maintain approved Droid plugins for company-wide distribution. Instead of individual teams discovering and vetting plugins independently, an internal marketplace provides a curated catalog of capabilities that are pre-approved, maintained, and ready to use.

For day-to-day plugin usage and authoring, see Plugins. Use this page when you need enterprise distribution, managed marketplace sources, and org-level rollout controls.

Why use Internal Plugin Marketplaces?#

Set up an internal plugin marketplace#

An internal plugin marketplace is a Git repository containing your organization's approved plugins with a marketplace manifest.

Repository structure#

your-org/droid-plugins/
├── .factory-plugin/
│   └── marketplace.json      # Marketplace manifest
├── plugins/
│   ├── security-toolkit/     # Security team plugins
│   │   ├── .factory-plugin/
│   │   │   └── plugin.json
│   │   └── skills/
│   ├── frontend-standards/   # Frontend team plugins
│   │   ├── .factory-plugin/
│   │   │   └── plugin.json
│   │   └── skills/
│   ├── data-engineering/     # Data team plugins
│   │   └── ...
│   └── platform-tools/       # Platform/DevOps plugins
│       └── ...
└── README.md

Marketplace manifest#

Create .factory-plugin/marketplace.json to register your plugins:

{
  "name": "acme-corp-plugins",
  "description": "ACME Corp approved Droid plugins",
  "owner": {
    "name": "ACME Platform Team",
    "email": "platform@acme.com"
  },
  "plugins": [
    {
      "name": "security-toolkit",
      "description": "Security review, threat modeling, and vulnerability scanning",
      "source": "./plugins/security-toolkit",
      "category": "security"
    },
    {
      "name": "frontend-standards",
      "description": "React component patterns, accessibility checks, design system integration",
      "source": "./plugins/frontend-standards",
      "category": "frontend"
    },
    {
      "name": "data-engineering",
      "description": "SQL review, pipeline validation, data quality checks",
      "source": "./plugins/data-engineering",
      "category": "data"
    },
    {
      "name": "platform-tools",
      "description": "CI/CD helpers, infrastructure review, deployment automation",
      "source": "./plugins/platform-tools",
      "category": "platform"
    }
  ]
}

Org-level configuration#

Configure the marketplace at the organization level so it's automatically available to all users. Add to your org-managed settings:

{
  "extraKnownMarketplaces": {
    "acme-corp-plugins": {
      "source": {
        "source": "github",
        "repo": "your-org/droid-plugins"
      }
    }
  },
  "enabledPlugins": {
    "security-toolkit@acme-corp-plugins": true,
    "platform-tools@acme-corp-plugins": true
  }
}

With this configuration:

• The marketplace appears automatically when users run /plugins
• Droid installs the enabled plugins automatically during startup
• Users can install additional plugins unless strictEnabledPlugins restricts the list

Restricting marketplaces#

To prevent users from adding unapproved marketplaces, use strictKnownMarketplaces:

{
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "Factory-AI/factory-plugins" }
  ]
}

When strictKnownMarketplaces is set:

• Users can only add marketplaces from the approved list
• Plugin installations from non-approved marketplaces are blocked

Marketplaces the organization declares in extraKnownMarketplaces count as approved without being repeated in the list, so strictKnownMarketplaces only has to name sources outside your own org settings. A local path in the list has to be absolute or start with ~, since a relative one points at a different directory for every user, and saving one is rejected.

Existing-plugin provenance enforcement is rolling out separately. When it is active for your organization:

• Installed plugins whose marketplace is not approved stop loading
• Installed plugins whose recorded source differs from the approved source stop loading, even when the marketplace name matches

A blocked plugin stays in the installed list and shows the reason in /plugins. Approve its marketplace, or have the user reinstall the plugin from a marketplace already on the list. When the name is approved but the source no longer matches, re-add the marketplace to repair the registration, then reinstall the plugin to record the new source.

If an org list saved by an older CLI contains only relative local paths, Droid denies new installs but keeps existing plugins active. Replace those entries with absolute paths or paths that start with ~.

Restricting enabled plugins#

By default, enabledPlugins entries from org, project, and user settings combine. Set strictEnabledPlugins to make the entries at the policy level and higher the complete list:

{
  "strictEnabledPlugins": true,
  "enabledPlugins": {
    "security-toolkit@acme-corp-plugins": true,
    "platform-tools@acme-corp-plugins": true
  }
}

At org level, project and user settings cannot enable or install other plugins. Their existing entries stay stored but inactive, and can reactivate if the strict policy is removed. Factory's default plugins are also disabled unless they appear in the org list.

See Hierarchical settings and org control for precedence and the full settings reference.

User experience#

Users manage plugins via the /plugins UI:

1. 1
   Run /plugins to open the plugin manager
2. 2
   The Available tab shows plugins from all registered marketplaces including the org marketplace, minus the ones already installed
3. 3
   Org-enabled plugins are installed automatically during startup

For CLI access:

droid plugin install frontend-standards@acme-corp-plugins
droid plugin update frontend-standards@acme-corp-plugins

Organization marketplaces are labeled in Marketplaces, and managed installs are labeled in Installed. Available identifies each plugin's source marketplace.

Organizing plugins#

Structure your marketplace around the boundaries your platform team already owns. Common patterns include:

• Team function: security, frontend, backend, data, platform, compliance.
• Capability: code review, testing, documentation, migrations, security.
• Project type: microservices, monoliths, data pipelines, ML projects.

Choose one primary taxonomy so /plugins stays predictable for new users.

Pre-installing plugins#

For critical capabilities that everyone needs, set enabledPlugins in org-managed settings, alongside extraKnownMarketplaces as shown in Org-level configuration. These plugins:

• Are installed automatically with org scope during startup
• Can finish installing after the session becomes usable when a source is slow
• Follow the org settings for their version, so /plugins offers an org-scoped plugin no update or uninstall action, only its details

Move a relative-path org plugin by changing the marketplace pin in org-managed settings. For external Git or npm plugins, update the source entry in the marketplace manifest, then advance the marketplace pin so clients receive that change.

Version management#

Relative-path plugins in a Git marketplace use the marketplace checkout commit as their installed version. External Git and npm sources are fetched separately when their plugin is installed or refreshed.

Pin a marketplace source with ref (branch or tag) or sha (full commit SHA) to control its manifest and relative-path plugins:

{
  "extraKnownMarketplaces": {
    "acme-corp-plugins": {
      "source": {
        "source": "github",
        "repo": "your-org/droid-plugins",
        "ref": "v2.4.0"
      }
    },
    "acme-corp-plugins-frozen": {
      "source": {
        "source": "github",
        "repo": "your-org/droid-plugins",
        "sha": "1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b"
      }
    }
  }
}

Common patterns:

• Omit ref and sha - follow the repository's default branch
• ref: "main" - explicitly follow the main branch
• ref: "staging" - early-adopter channel
• ref: "v1.2.0" - pin to a release tag
• sha: "<40-char SHA>" - hard pin to a specific commit; marketplace update validates the checkout but does not fetch or move it

See Plugins · Add and pin marketplaces for the full source schema.

Private repository access#

For private Git repositories, ensure Droid can authenticate:

GitHub Enterprise#

# Users authenticate via gh CLI
gh auth login --hostname github.your-company.com

GitLab self-hosted#

# Configure git credentials
git config --global credential.helper store

SSH-based access#

Ensure SSH keys are configured for the repository host.

Local marketplaces#

For air-gapped environments or when Git access is restricted, you can use local directory marketplaces. This is useful for:

• Environments without internet access
• Testing plugins before publishing
• Internal distribution via shared network drives

Setting up a local marketplace#

Create a directory with the standard marketplace structure:

/shared/company-plugins/
├── .factory-plugin/
│   └── marketplace.json
└── plugins/
    ├── security-toolkit/
    │   └── .factory-plugin/
    │       └── plugin.json
    └── code-standards/
        └── .factory-plugin/
            └── plugin.json

Adding a local marketplace#

Via UI: /plugins → Marketplaces tab → "Add new marketplace" → enter absolute path

Via CLI:

droid plugin marketplace add /shared/company-plugins

Configuration for auto-registration#

Use the local source type in settings:

{
  "extraKnownMarketplaces": {
    "company-local-plugins": {
      "source": {
        "source": "local",
        "path": "/shared/company-plugins"
      }
    }
  }
}

Marketplaces in a subdirectory (git-subdir)#

When your marketplace lives in a subdirectory of a larger repository (rather than at the repo root), use the git-subdir source type. It works with any Git host via a repository URL and the path to the marketplace root within it:

{
  "extraKnownMarketplaces": {
    "acme-corp-plugins": {
      "source": {
        "source": "git-subdir",
        "url": "https://gitlab.com/acme/monorepo.git",
        "path": "tools/droid-plugins",
        "ref": "main"
      }
    }
  }
}

url and path are required. The selected directory must contain .factory-plugin/marketplace.json or .claude-plugin/marketplace.json. ref (branch or tag) and sha (full 40-character commit SHA) are optional and pin the marketplace the same way they do for other Git sources.

npm-sourced plugins#

Individual plugins in a marketplace manifest can be sourced from an npm registry instead of a Git path. Use the npm source type in a plugin's source field (it is a per-plugin source only, not a marketplace source):

{
  "name": "acme-corp-plugins",
  "plugins": [
    {
      "name": "security-toolkit",
      "description": "Security review and vulnerability scanning",
      "source": {
        "source": "npm",
        "package": "@acme/droid-security-toolkit",
        "version": "^2.0.0",
        "registry": "https://npm.internal.acme.com",
        "authTokenEnvVar": "ACME_NPM_TOKEN"
      }
    }
  ]
}

npm-sourced installs record the resolved package version, URL, and integrity when available. A plugin refresh resolves its exact version, range, or dist-tag again. Automatic refresh follows the containing marketplace's update schedule rather than continuously polling the registry.

Best practices#

Example: financial services org#

A financial services company sets up its marketplace:

Mandatory plugins (pre-installed for everyone):

• compliance-checks - PCI-DSS and SOX compliance validation
• security-scanner - OWASP vulnerability detection
• audit-logging - Enhanced audit trail for all Droid actions

Team-specific plugins (available for install):

• trading-systems - For quantitative and trading teams
• risk-models - For risk management teams
• regulatory-reporting - For compliance teams

Configuration (org-managed-settings.json):

{
  "extraKnownMarketplaces": {
    "acme-financial-plugins": {
      "source": {
        "source": "github",
        "repo": "acme-financial/droid-plugins"
      }
    }
  },
  "enabledPlugins": {
    "compliance-checks@acme-financial-plugins": true,
    "security-scanner@acme-financial-plugins": true,
    "audit-logging@acme-financial-plugins": true
  }
}

This configures the compliance and security plugins for automatic org-scope installation, while specialized teams can add domain-specific capabilities.