Proposal: a plain-HTTP way to distribute plugin marketplaces (no git required)

[apiarya]

The problem

Note: this is a preliminary, v1-style proposal — intentionally the
smallest version of this idea we could write down, meant to get a
scope/direction read before investing in a fuller spec. See "This is a
starting point, not the final shape" below for where we'd expect this to
grow.

Agent Plugins 1.0 nails down what a plugin is (plugin.json,
skills/, mcp.json). It deliberately doesn't say how a client finds
a marketplace in the first place — issue #5 calls this out directly.

In practice, every harness that has marketplaces today has quietly
converged on the same answer: put a marketplace.json in a git repo,
and have the client run git clone on it. That's it — that's the whole
"protocol." It works, but it means:

• Git is a hard requirement, even though nothing about a plugin
  catalog is inherently git-shaped. A marketplace is just a list of
  plugins with versions — conceptually closer to an npm registry or an
  app store than to a source repo.
• No standard way to grant access per user or team. Git has no
  concept of per-file or per-branch authorization beyond repo-level
  access — it's all-or-nothing. There's no clean way to express "this
  catalog is public, but this one plugin is only for the security team,"
  or "revoke this user's access to just this plugin."
• A concrete bug that actually bit us: git's "dumb" HTTP transport
  (what you get from any plain static file host / S3 / CDN with no
  git-aware server behind it) cannot do a shallow clone — see
  https://git-scm.com/docs/http-protocol on the dumb-protocol vs.
  smart-protocol split. Try it yourself:

  $ git clone --depth 1 https://static.acme.com/my-marketplace.git
  fatal: dumb http transport does not support shallow capabilities
  

  So the simplest possible way to self-host a marketplace (a folder of
  static files) silently doesn't work, and you're forced into running
  git-http-backend (real git server infrastructure) just to get a
  shallow clone to succeed. We hit this first-hand prototyping a
  self-hosted enterprise marketplace.

Why this matters beyond git's transport limitations

A few real scenarios that git-as-transport makes awkward or impossible
today:

• Private, company-only marketplaces. A bank wants an internal
  catalog of plugins its engineers can install, hosted behind the
  corporate firewall/VPN, with no public GitHub repo involved at all.
  Git-over-HTTPS to a private repo technically works, but now every
  client machine needs git credentials/SSH keys provisioned just to
  read a plugin list — overkill for what is really just "fetch some
  JSON and a tarball."
• Enterprise-approved-only catalogs. A company wants engineers to
  only install plugins that security has reviewed, and wants to revoke
  a specific plugin for a specific team without taking the whole catalog
  down. How a client learns "you don't have access" is ordinary HTTP
  auth territory — not something this proposal tries to standardize —
  but it's one more reason a real access-controlled catalog can't just
  be a public git repo.
• Static hosting / CDN distribution. Plain-HTTP distribution (think
  https://plugins.acme.com/marketplace.json) means a marketplace
  can be served from literally anything that can serve a file —
  S3 + CloudFront, GitHub Pages, an nginx box — no git server required.
• Multiple marketplaces per organization. e.g. acme-platform,
  acme-security, acme-data-eng as independently-versioned catalogs —
  https://plugins.acme.com/platform/marketplace.json,
  https://plugins.acme.com/security/marketplace.json,
  https://plugins.acme.com/data-eng/marketplace.json. Easy with
  per-catalog JSON endpoints; awkward with one-repo-per-catalog git
  conventions once you have dozens of teams.

What we're proposing (kept intentionally small)

A plain-HTTP, git-free distribution protocol as a companion to Agent
Plugins 1.0 — in the same spirit as how the
OCI Distribution Spec
lets any client docker pull from any conformant registry without
caring how that registry runs internally, or how
PEP 503 does the same for pip install against any index.

1. Discovery — one GET, plain HTTPS, no git:

   GET https://plugins.acme.com/marketplace.json
   

   returns a small JSON index: plugin names, descriptions, tags, and
   each plugin's latest version. No clone, no .git directory, no
   repository semantics at all.

2. Per-plugin detail, fetched lazily, only when needed:

   GET https://plugins.acme.com/plugins/pdf-tools.json
   

   returns that one plugin's version history and per-version artifact
   info. This keeps the top-level index small even if a catalog has
   thousands of plugins and hundreds of versions each — the index
   doesn't grow with version history, only with plugin count.

3. Fetching the actual plugin — a checksummed tarball, nothing exotic:

   GET https://plugins.acme.com/artifacts/pdf-tools-1.4.0.tar.gz
   sha256: 9f86d0818...   (from the per-plugin detail doc)
   

   Same directory layout a client gets from git clone today — just not
   wrapped in a git repo. Client verifies the SHA-256 before extracting.

Auth, if a marketplace needs it at all, is just normal HTTP auth —
token-based headers, mTLS, signed URLs, whatever the server wants. We're
not proposing anything new here, and deliberately leaving 401/403
handling and access-request signaling out of this discussion — that's
ordinary server/operator policy, not something we're asking the TSC to
standardize right now.

Explicitly out of scope here

Review/approval workflows, who-can-install-what administration,
authentication/entitlement signaling (401/403 handling, access-request
hints), telemetry, and webhook notifications are all server-internal
concerns — no other vendor's client ever calls those endpoints, so
there's no interop cost if every implementation does them differently.
We are not asking the TSC to standardize any of that, only the
three client-facing points above.

Why we're raising this with the TSC specifically

A spec only matters if clients actually implement it. For this to be
useful, it needs buy-in from the harnesses that currently each implement
their own marketplace convention (Copilot CLI, Claude Code, and others as
they add marketplace support) — otherwise we end up with yet another
format nobody adopts. We'd rather get early signal here than build this
out unilaterally and ask for adoption after the fact.

Following this repo's contribution guidance

Per CONTRIBUTING.md, spelling out the four things a proposal should
cover before this goes further:

• The concrete problem: described above — git-as-transport has no
  shallow-clone support over dumb HTTP, which blocks plain-static-file/
  CDN-hosted marketplaces entirely.
• Who encounters it: every client that implements a plugin marketplace
  today re-invents this convention independently, and it's already more
  than two clients: Copilot CLI and Claude Code support git-based
  marketplaces today; Gemini CLI installs extensions the same way
  (gemini extensions install <github-url>); and Codex CLI has a
  /plugins browser that installs "from a configured marketplace." Cursor's
  Team Marketplaces also point at a GitHub/GitLab repo — and Cursor's own
  team has publicly said they're hearing the same ask we're making here:
  "we've heard similar feedback from other teams that want to use their
  own artifact registries rather than relying on Git-based
  distribution".
  Per MAINTAINERS.md, this TSC represents Amazon, Cursor, Microsoft,
  OpenAI, and Vercel — four of those five already ship something that hits
  this exact gap.
• Why this belongs in the portable spec, not client policy: discovery,
  manifest shape, and artifact verification are exactly the parts that
  must match byte-for-byte for a single marketplace to serve multiple
  clients — the same reasoning Agent Plugins 1.0 already applies to
  plugin.json. Governance/policy (who approves what) is correctly left
  client/operator-specific, which is why it's explicitly out of scope here.
• Implementer readiness, honestly: we've built and validated a working
  reference implementation ourselves (linked repo, plus a private PoC
  exercising it against a real copilot CLI install flow) — so we can
  commit to implementing and maintaining the client+server reference. We
  do not yet have a second harness maintainer committed to adopting
  this on the client side. That's genuinely the open question this
  discussion is meant to resolve, not something we're asserting is already
  solved (see Question 4 below).

This is a starting point, not the final shape

What's described above is deliberately the smallest useful version —
enough to replace git clone with plain HTTP and nothing more. We're
not claiming this is everything a marketplace protocol will ever need.
Once there's a basic version in place, a few directions we'd expect this
to grow into later (not part of this proposal, just so the shape of
where this could go is visible up front):

• Search/browse at the protocol level — today, "find me a PDF
  plugin" means downloading the whole index and filtering client-side.
  A catalog with thousands of plugins may eventually want a real
  ?q=pdf query endpoint.
• Signed manifests — today integrity is per-artifact (SHA-256 on
  the tarball). A later version could sign the manifest itself (think
  sigstore/cosign-style) so a client can verify the whole catalog
  hasn't been tampered with, not just one download.
• Mirroring/caching semantics — standard cache headers / mirror
  endpoints so large orgs can run a local pull-through cache in front of
  an upstream marketplace, similar to how container registries support
  pull-through mirrors.
• Access-denied signaling — if/when there's appetite to standardize
  any part of the auth surface, a small optional reason code
  (not_entitled, plugin_yanked, region_blocked, etc.) so clients
  can show a specific message instead of a bare 403 — not part of this
  first ask.
• Deprecation/yank signaling — a standard way for a manifest to mark
  a version as yanked/deprecated so clients can warn before install,
  not just 404 after the fact.

None of this needs to be decided now — flagging it so the TSC can weigh
in on whether v1 leaves room for these (e.g. versioning the manifest
format itself) rather than discovering a wall later.

Full draft spec (manifest schema, client algorithm, compatibility path,
open questions): https://github.com/apiarya/agent-marketplace-spec

Questions for the TSC:

1. Is a separate companion "distribution" spec the right shape, or
   should this become new sections within Agent Plugins 1.0 itself?
2. Any objection to the two-tier manifest design (lightweight index +
   lazy per-plugin detail doc), given catalogs may grow into the
   thousands of plugins?
3. Realistically, what would it take to get harness maintainers (beyond
   whoever's in this discussion) to commit to implementing this, versus
   it staying a paper spec?