# Internal Plugin Marketplaces

Centralize approved Droid plugins across your organization with internal marketplaces and managed settings.

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](/harness/plugins). Use this page when you need enterprise distribution, managed marketplace sources, and org-level rollout controls.

## Why use Internal Plugin Marketplaces?

| Challenge | Solution |
|-----------|----------|
| **Inconsistent tooling** across teams | Single source of approved plugins ensures everyone uses the same capabilities |
| **Security and compliance review** for each plugin | Vet plugins once at the org level, distribute everywhere |
| **Onboarding new developers** | New team members instantly access all approved capabilities |
| **Role-specific tooling** | Package plugins by team function (security, frontend, data, etc.) |
| **Version control** | Manage plugin versions centrally, roll out updates organization-wide |

<LabeledDivider label='Setup and rollout' />

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

```text
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:

```json
{
  "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:

```json
{
  "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
  }
}
```

| Field | Purpose |
|-------|---------|
| `extraKnownMarketplaces` | Registers the marketplace so users can browse and install plugins |
| `enabledPlugins` | Pre-installs specific plugins for all users (optional) |

### Restricting marketplaces

To prevent users from adding unapproved marketplaces, use `strictKnownMarketplaces`:

```json
{
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "your-org/droid-plugins" },
    { "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
- Existing unapproved marketplaces continue to work but cannot be updated

With this configuration:

- The marketplace appears automatically when users run `/plugins`
- Pre-enabled plugins are available immediately without manual installation
- Users can install additional plugins from the marketplace as needed

## User experience

Users manage plugins via the `/plugins` UI:

1. Run `/plugins` to open the plugin manager
2. Browse tab shows plugins from all registered marketplaces including the org marketplace
3. Org-enabled plugins are pre-installed automatically on startup

For CLI access:

```bash
droid plugin install frontend-standards@acme-corp-plugins
droid plugin update security-toolkit@acme-corp-plugins
```

Users see the marketplace alongside public marketplaces, with org plugins clearly labeled.

<LabeledDivider label='Catalog management' />

## Organizing plugins

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

{/* sweep-allow: term-bullets */}

- **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](#org-level-configuration). Pre-installed plugins:

- Are available immediately on first Droid session
- Are installed with `org` scope automatically
- Can be updated via `/plugins` UI or `droid plugin update`

## Version management

Plugins are versioned by Git commit hash. When a plugin is updated, Droid fetches the latest commit from the marketplace.

To control versions, pin the marketplace source itself with `ref` (branch or tag) or `sha` (full commit SHA):

```json
{
  "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:

- `ref: "main"`  -  production-ready for all users (default behavior)
- `ref: "staging"`  -  early-adopter channel
- `ref: "v1.2.0"`  -  pin to a release tag
- `sha: "<40-char SHA>"`  -  hard pin to a specific commit; `droid plugin marketplace update` is a no-op

See [Plugins · Add and pin marketplaces](/harness/plugins#add-and-pin-marketplaces) for the full source schema.

<Note>
Version pinning via the per-plugin `version` field is not currently supported. To pin a plugin's version, pin the marketplace it lives in via `ref` or `sha`.
</Note>

<LabeledDivider label='Sources and access' />

## Private repository access

For private Git repositories, ensure Droid can authenticate:

### GitHub Enterprise

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

### GitLab self-hosted

```bash
# 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:

```text
/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:

```bash
droid plugin marketplace add /shared/company-plugins
```

### Configuration for auto-registration

Use the `local` source type in settings:

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

<Note>
When removing a local marketplace from the marketplace list, Droid does **not** delete the source directory. Only Git-cloned marketplaces have their directories removed on deletion.
</Note>

## Marketplaces in a subdirectory (`git-subdir`)

When your marketplace manifest 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 manifest within it:

```json
{
  "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; `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):

```json
{
  "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"
      }
    }
  ]
}
```

| Field | Purpose |
|-------|---------|
| `package` | npm package name (scoped or unscoped). Required. |
| `version` | Exact version, range (`^2.0.0`), or dist-tag (`latest`). Optional. |
| `registry` | Custom https registry URL for private packages. Optional. |
| `authTokenEnvVar` | Name of the environment variable holding the registry auth token. Optional. |

npm-sourced plugins are tracked by their resolved npm version, so auto-update detects new publishes for `latest` or range specs.

<LabeledDivider label='In practice' />

## Best practices

| Practice | Checklist |
| --- | --- |
| Establish a review process | Require security review for external dependencies, platform-team code review, isolated-environment testing, and documentation before adding plugins to the marketplace. |
| Document each plugin | Include what the plugin provides, when to use it, when not to use it, prerequisites, dependencies, and example usage. |
| Version semantically | Use **major** versions for breaking command or behavior changes, **minor** versions for backward-compatible capabilities, and **patch** versions for bug fixes. |
| Monitor adoption | Track installation counts, active usage metrics, team feedback, issues, and feature requests. |
| Plan for deprecation | Announce the timeline, provide a migration path, and keep deprecated plugins available read-only during the transition. |

## 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):**

```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 ensures every developer has compliance and security tooling from day one, while specialized teams can add domain-specific capabilities.

<RelatedLinks>
  <RelatedLink href='/harness/plugins' title='Plugins'>
    Plugin basics, installation, and authoring.
  </RelatedLink>
  <RelatedLink href='/harness/subagents' title='Custom Droids'>
    Scoped subagents that plugins can bundle and distribute.
  </RelatedLink>
</RelatedLinks>