Skip to content
Agent Package Manager

Installing from marketplaces

A marketplace publisher (see Publish to a marketplace) ships one marketplace.json that every major agent runtime can read. This page covers the install side: which command each runtime exposes, what authentication it needs, and where files land on disk.

The recommended path is apm install. It is the only path that gives you a committed apm.lock.yaml, content-hash pinning, transitive resolution, the pre-install security scan, and apm audit --ci drift detection. Use a native command when you cannot install APM, or when the runtime owns the install surface (VS Code Copilot Chat).

Install patterns

Section titled “Install patterns”
RuntimeInstall commandAuthCache layout
APM (recommended)apm marketplace add <owner>/<repo> then apm install <pkg>@<marketplace>Host token (GITHUB_APM_PAT, etc.) via git credential helper.apm_modules/ in the project; ~/.apm/cache/ for fetched refs.
VS Code (GitHub Copilot Chat)Plugin marketplace UI; or code --install-extension for the marketplace itself.VS Code GitHub sign-in.Per-user extension store managed by VS Code. APM artifacts stream from the marketplace at activation.
CursorSettings -> Plugins -> add marketplace URL.Cursor account.~/.cursor/extensions/ per-user.
GitHub Copilot CLIgh copilot marketplace add <owner>/<repo> then gh copilot plugin install <pkg>.gh auth login.~/.config/gh/copilot/ per-user.
Claude Code/plugin marketplace add <owner>/<repo> then /plugin install <pkg>.Anthropic sign-in.~/.claude/plugins/ per-user; .claude/ in-project when wired.
OpenAI Codex CLIcodex plugin add <owner>/<repo> then codex plugin install <pkg>.OpenAI sign-in.~/.codex/plugins/ per-user; .codex/ in-project when wired.

Native commands above read whichever artifact the runtime expects. Most read .claude-plugin/marketplace.json (Anthropic-compatible schema); Codex reads .agents/plugins/marketplace.json. Producers who enable both outputs reach every runtime from one repo.

What you give up with native installs

Section titled “What you give up with native installs”

Native runtime commands install the plugin and stop there. They do not produce a project-scoped lockfile, do not run the APM security scan, and do not participate in apm audit --ci drift detection. If your team or org has adopted APM, prefer apm install even when a native command exists — the lockfile is what makes installs reproducible across machines and CI.

Capabilityapm installNative runtime install
Project-scoped apm.lock.yamlyesno
Content-hash pinningyesno
Transitive dependency resolutionyesno
Pre-install security scanyesno
apm audit --ci drift gateyesno
Cross-harness deploy from one refyesno (per-runtime install)

Picking the install path

Section titled “Picking the install path”
  • You are the only user on a workstation and the plugin is simple. A native install is fine. Treat it as a personal tool, not project infrastructure.
  • The plugin will be used by a team or in CI. Use apm install. Commit apm.yml and apm.lock.yaml. Every contributor gets the same bytes.
  • Your org has an apm-policy.yml. apm install is the only path that enforces it. See Governance on the consumer ramp.

Local and self-hosted marketplaces

Section titled “Local and self-hosted marketplaces”

apm marketplace add accepts more than GitHub-hosted repos. The same register / browse / install / update workflow works against:

  • Local filesystem paths — apm marketplace add /srv/marketplaces/agent-forge (or a relative path, or ~/code/marketplace). Useful for privacy-sensitive packages, offline workflows, and air-gapped environments. Local marketplaces with relative plugin sources install by copying from disk via LocalDependencySource.
  • file:// URIs — apm marketplace add file:///srv/marketplaces/agent-forge.git. Behaves the same as a local path.
  • Generic git URLs — any host APM does not classify as GitHub or GitLab family flows through subprocess git and GitCache. Includes Azure DevOps (auth via ADO_APM_PAT), Gitea, Bitbucket Server, and self-hosted git servers.
  • SSH URLs — git@gitea.example.com:org/repo.git. The host is extracted, classified, and routed through the matching fetcher.

For generic-git marketplaces, marketplace.json is fetched via a sparse-cone clone (only the manifest path is downloaded); APM does not forward GITHUB_APM_PAT or GITLAB_APM_TOKEN to non-GitHub / non-GitLab hosts. Authentication falls through to the host’s *_APM_PAT (e.g. ADO_APM_PAT) or your local git credential-manager. See Authentication.

Lockfile note. Installs from a local marketplace record a local-path source in apm.lock.yaml. Lockfiles produced this way are machine-specific — do not commit them into a shared repo. See lockfile reference.

Where next

Section titled “Where next”