Agent Packages Repositories

Agent Packages repositories in JFrog Artifactory provide a governed, private registry for agent configuration, including skills, plugins, prompts, hooks, Model Context Protocol (MCP) servers, instructions, and agents. Agent Packages repositories work with the Agent Package Manager (APM) CLI. When you integrate APM with JFrog Artifactory, your organization gets a secure place to publish, discover, and install agent packages across tools such as Claude, Cursor, Codex, and more.

Artifactory fully supports Agent Packages repositories, including the following capabilities:

• APM Support: Managing packages in Artifactory repositories using Agent Package Manager apm version 0.23.0 and later.
• Robust Metadata Support: Artifactory calculates metadata for packages stored in Artifactory local repositories from apm.yml or apm.lock.yaml manifests inside each package.
• Secure Local Storage: Storing your internal and private agent packages securely in local repositories.
• API Support: APM v1 REST API endpoints for list, publish, download, and search operations on local repositories.

Get Started with Agent Packages

To get started working with Agent Packages, complete the following main steps:

1. Create an Agent Packages Repository
2. Connect APM to Artifactory
3. Publish Agent Packages to Artifactory
4. Install Agent Packages

Create an Agent Packages Repository

Create a local Agent Packages repository in JFrog Artifactory before you publish or install APM packages. Local Agent Packages repositories store and share first- and second-party packages with your organization.

For more information on JFrog repositories, see Repository Management.

Prerequisite: You need Admin or Project Admin permissions in Artifactory to create a repository. If you don't have Admin permissions, you won't see the option.

To create an Agent Packages repository:

1. In the Administration tab, click Repositories > Create a Repository.

   

2. From the repository type menu, select Local.

3. Select the Agent Packages package type.

4. In the Repository Key field, enter a meaningful name for the repository. For example, agent-packages-local. For more information on local repositories and their settings, see Local Repositories.

5. Click Create Repository. The repository is created and the Repositories page is displayed.

Connect APM to Artifactory

You can use the APM CLI as a client to install and publish Agent Packages. Connect APM to Artifactory by enabling registry support, configuring your Artifactory registry URL, and setting your bearer token. APM writes these settings to .apm/config.json in your project.

Prerequisites:

• You must have an existing local Agent Packages repository in Artifactory. For more information, see Create an Agent Packages Repository.
• Artifactory is compatible with apm version 0.23.0 and later.

To connect APM to Artifactory:

• From the directory that contains your apm.yml file, run the following commands to enable registry support and configure Artifactory as the default registry:

  Shell

  apm experimental enable registries
  apm config set registry.<REPO_NAME>.url https://<JFROG_HOSTNAME>/artifactory/api/agentpackages/<REPO_NAME>
  apm config set registry.<REPO_NAME>.token <TOKEN>
  apm config set registry.<REPO_NAME>.default true

  Where:

  • <REPO_NAME>: The name of your local Agent Packages repository in Artifactory
  • <JFROG_HOSTNAME>: The hostname of your JFrog Platform
  • <TOKEN>: Your Artifactory identity token

  For example:

  Shell

  apm experimental enable registries
  apm config set registry.agent-packages-local.url https://company.jfrog.io/artifactory/api/agentpackages/agent-packages-local
  apm config set registry.agent-packages-local.token <TOKEN>
  apm config set registry.agent-packages-local.default true

Marking the registry as the default lets you reference packages without specifying the registry. Without a default, you must include the full registry name for all dependency references.

You can also use JFrog CLI to configure the registry. For more information about setup, installation, publishing, passthrough, and optional build information, see Use APM with JFrog CLI.

Enforcing APM Download from Artifactory

To enforce centralized and secure Agent Package distribution, it's best practice to configure Artifactory as your organization-wide default registry for the APM client. You can set organizational defaults in your .github/apm-policy.yml file, in the following format:

name: "JFrog APM Registry Policy"
version: "1.0.0"
enforcement: block						# block | warn | off
fetch_failure: block 					# fail closed-off if policy can't be fetched

registry_source:
	require:	
		- agent-resources-local		# must match registry name in config.json
	allow_non_registry: false		# blocks any dependency not routed through this registry	

Once you push the policy to your GitHub repository, it automatically governs all repositories in the organization on the next apm install.

For more information, see Get Started with apm-policy.yml in the Agent Package Manager documentation.

Publish Agent Packages to Artifactory

You can use the APM client to publish packages to Artifactory. Artifactory stores each published package as a .zip archive using the layout <OWNER>/<PACKAGE_NAME>/<PACKAGE_NAME>-<VERSION>.zip. For more information, see Package Layout and Artifacts.

Prerequisite: Configure at least one Artifactory registry in your .apm/config.json file. For more information, see Connect APM to Artifactory.

To publish an Agent Package:

• From the directory that contains your apm.yml file, run one of the following commands:

  • To publish to the default registry, run the following command:

    Shell

    apm publish --package <OWNER>/<PACKAGE_NAME>

    Where:

    • <OWNER>: The package owner or organization namespace
    • <PACKAGE_NAME>: The name of the package

    For example:

    Shell

    apm publish --package frog/my-package

  • To publish to a specific registry, run the following command:

    Shell

    apm publish --package <OWNER>/<PACKAGE_NAME> --registry <REPO_NAME>

    Where:

    • <OWNER>: The package owner or organization namespace
    • <PACKAGE_NAME>: The name of the package
    • <REPO_NAME>: The name of the Agent Packages repository to publish to

    For example:

    Shell

    apm publish --package frog/my-package --registry agent-packages-local

    📘

    Note

    Use this command when you didn't set a default registry, or when .apm/config.json contains multiple registries.

The package is published to the specified Artifactory repository.

Install Agent Packages

Artifactory supports installing Agent Packages using the APM client. Every Artifactory registry install must include a version. You can install packages in the following ways:

• Install Agent Packages as Dependencies
• Install Agent Packages Explicitly

Install Agent Packages as Dependencies

You can declare Agent Packages in apm.yml and install them from Artifactory with a single apm install command.

To install packages as dependencies:

1. Open your apm.yml file in a text editor.

2. Under the dependencies.apm key, specify the packages as dependencies in the following format:

   YAML

   dependencies:
     apm:
       - <OWNER>/<PACKAGE_NAME>#<VERSION>

   Where:

   • <OWNER>: The package owner or organization namespace.
   • <PACKAGE_NAME>: The name of the Agent Package to install.
   • <VERSION>: A required SemVer version expression. Exact versions such as 1.0.0 and ranges such as ^1.2.3 are both supported.

   For example:

   YAML

   dependencies:
     apm:
       - frog/my-agent-pkg#1.0.0

3. Save the changes to the file.

4. Run the following command to resolve and install all declared dependencies at once:

   Shell

   apm install

Install Agent Packages Explicitly

Regardless of dependencies, you can install an Agent Package by specifying the package details in the command.

To install packages explicitly:

• From your APM project directory, run the following command to install the specified package:

  Shell

  apm install <OWNER>/<PACKAGE_NAME>#<VERSION>

  Where:

  • <OWNER>: The package owner or organization namespace
  • <PACKAGE_NAME>: The name of the Agent Package to install
  • <VERSION>: A required SemVer version expression

  For example:

  Shell

  apm install acme/my-agent-pkg#1.0.0

  The package is installed in your project.

Additional Agent Packages Information

The following additional information is available for Agent Packages repositories:

• Primitives in Agent Packages
• Package Layout and Artifacts
• APM v1 REST API

Primitives in Agent Packages

APM packages are versioned .zip archives that follow the APM protocol. Each package is a portable bundle of agent configuration that you install with apm install and project onto a supported runtime with apm compile.

Inside a package, configuration is organized as primitives under a .apm/ directory at the project root. Primitives are authored once in APM format and compiled into the layout each agent tool expects on disk. A single published package can include any combination of skills, prompts, instructions, agents, hooks, commands, and MCP servers.

Each primitive is usually a Markdown file, or a folder whose entry point is Markdown, with frontmatter that names the resource and describes when it applies. Package-level metadata lives in apm.yml and apm.lock.yaml at the project root. Artifactory indexes packages from apm.yml when present, or from apm.lock.yaml otherwise, after you publish.

For more information, see Author primitives in the upstream APM producer documentation before you publish.

Package Layout and Artifacts

Artifactory stores Agent Packages as .zip archives using the following layout:

<OWNER>/<PACKAGE_NAME>/<PACKAGE_NAME>-<VERSION>.zip

For example, acme/my-pkg/my-pkg-1.2.3.zip maps to owner acme, package name my-pkg, and version 1.2.3. The <VERSION> value comes from the version field in your apm.yml file. Subfolders are not supported.

Each package may include:

• apm.yml: The APM client reads this package descriptor after extraction, and Artifactory prefers it for metadata indexing.
• apm.lock.yaml: Artifactory uses this lock file for indexing and metadata when apm.yml isn't present.

Uploads of .zip artifacts that do not follow this layout are rejected on local and Federated repositories. Other file formats, including .tar.gz, are not supported as Agent Packages.

APM v1 REST API

On local Agent Packages repositories, Artifactory exposes an APM v1-compatible REST API at the following base URL:

https://<JFROG_HOSTNAME>/artifactory/api/agentpackages/<REPO_NAME>/

The following table describes the supported methods and paths.

Agent Packages Limitations in Artifactory

The following are the limitations of Agent Packages in Artifactory:

• Local and federated repositories only: You can use apm install, apm publish, and the APM v1 REST API on local and federated Agent Packages repositories. Artifactory doesn't support remote repositories, virtual repositories, smart repositories, or replication for Agent Packages.
• Zip archives only: Package artifacts must be .zip archives. Artifactory doesn't support other formats, including .tar.gz.
• Strict package layout: You must publish artifacts that conform to <OWNER>/<PACKAGE_NAME>/<PACKAGE_NAME>-<VERSION>.zip. Artifactory rejects invalid .zip paths on upload and doesn't support subfolders.
• Artifactory as APM default: You can set Artifactory as the default APM source only at the organizational level by configuring the .github/apm-policy.yml file.

Frequently Asked Questions

This section provides answers to frequently asked questions about Agent Packages repositories.

Related Topics

• Repository Management
• Skills Repositories
• Agent Plugins Repositories
• AI Editor Extension Repositories
• Use APM with JFrog CLI