Supported Formats

Generic Repository

Cloudsmith provides public & private repositories for Generic files.

Cloudsmith supports Generic files, a flexible format for managing any file or binary that relies on specific file paths rather than semantic versioning.

HTML-based upstreams

Generic upstreams work with simple HTML-based sources. The upstream must consist of simple, unstyled HTML pages with no JavaScript. Each page should contain only links to package files or subdirectories. Examples include Gradle distributions, Apache releases, and Node distributions.

Contextual Documentation

The examples in this document are generic. Cloudsmith provides contextual setup instructions within each repository, complete with copy and paste snippets (with your namespace/repo pre-configured).

In the following examples:

Substitute placeholder values

Where you see uppercase values such as OWNER, REPOSITORY, TOKEN, API-KEY, or UPSTREAM_PREFIX, substitute these with your own Cloudsmith namespace, repository, token, API key, and upstream prefix as appropriate.

Why Generic Format?

The Generic format is designed for artifacts that rely on specific file paths rather than semantic versions. Key benefits include:

• Path-Based Identification: Uses the filepath as the unique identifier, enabling exact replication of upstream directory structures
• Upstream Proxying and Caching: Proxy and cache files from simple HTML-based upstream sources
• Supply Chain Management: Bring custom scripts, installers, and binaries into your managed supply chain
• Consistent URLs: Internal URLs remain consistent with upstream sources

Generic vs Raw Format

The Generic format is optimized for path-based file distribution and upstream proxying. It relies strictly on the filepath as the unique identifier and does not support:

• Package naming (separate from filepath)
• Package versioning (semantic versions)
• End User License Agreements (EULA)

If you need package naming, semantic versioning, or EULA support, use the Raw format instead. The Raw format provides traditional package management features including distinct package names, version tracking, and license acceptance workflows.

File-Based Storage

Generic packages are treated as files and binaries. Unlike native package formats (Python, npm, Maven), Generic packages do not have metadata, version information, or vulnerability scanning capabilities. They are stored and served as-is without package-specific processing.

Upload a File

Upload via the Cloudsmith CLI

For full details of how to install and setup the Cloudsmith CLI, see Command Line Interface

The command to upload via the Cloudsmith CLI is:

cloudsmith push generic OWNER/REPOSITORY ~/downloads/file.tar.gz --filepath path/to/file.tar.gz

Example:

cloudsmith push generic OWNER/REPOSITORY ~/downloads/file.tar.gz --filepath distributions/latest/file.tar.gz

Filepath parameter

The --filepath parameter specifies where the file will be stored in the repository structure. This path becomes the unique identifier for the package and determines its download URL.

Upload via Cloudsmith web app

Please see upload a package for details of how to upload via the Cloudsmith web app.

Download a Package

Download via Cloudsmith web app

Public Repositories

When logged into Cloudsmith via a Web Browser, use the Download button located on the package details page to download a generic package.

Private Repositories

To download from a private repository via the Cloudsmith web app, use the Use Package button to download a generic package using the default Entitlement Token for the repository. Use the dropdown arrow within the pop-up window to select a different authentication method.

Download via Command Line

To download a Generic package, fetch uploaded files using a well-crafted URL. The package URL format is based on the filepath used when uploading.

Public Repositories

Example curl commands to download a generic package from a public repository:

curl -sLf -O "https://generic.cloudsmith.io/OWNER/REPOSITORY/UPSTREAM_PREFIX/path/to/file.tar.gz"

Private Repositories

Private Repositories

Private repositories require authentication. Use either an Entitlement Token or API Key via HTTP Basic Authentication mechanisms to access files. The authentication method will depends on how you download packages.

The following authentication methods do not work for browsing the HTML index in a web browser. For browser access, use HTTP Basic Authentication when prompted—enter token as the username and your entitlement token as the password.

HTTP Basic Authentication (generic.cloudsmith.io):

Use an entitlement token or API key to authenticate and download files directly:

curl -sLf -u "token:TOKEN" -O "https://generic.cloudsmith.io/OWNER/REPOSITORY/UPSTREAM_PREFIX/path/to/file.tar.gz"

curl -sLf -u "token:API-KEY" -O "https://generic.cloudsmith.io/OWNER/REPOSITORY/UPSTREAM_PREFIX/path/to/file.tar.gz"

Alternatively, embed HTTP Basic Auth credentials in the URL to download files:

curl -sLf -O "https://token:TOKEN@generic.cloudsmith.io/OWNER/REPOSITORY/UPSTREAM_PREFIX/path/to/file.tar.gz"

Path-based authentication (dl.cloudsmith.io):

To use path-based authentication, include the token in the URL path and use the dl.cloudsmith.io domain. This method is not supported on generic.cloudsmith.io.

Add generic/download/ to the URL path before the upstream prefix to ensure the request is routed correctly.

curl -sLf -O "https://dl.cloudsmith.io/TOKEN/OWNER/REPOSITORY/generic/download/UPSTREAM_PREFIX/path/to/file.tar.gz"

HTTP libraries that don't follow redirects

Some HTTP libraries do not automatically follow redirects. The generic.cloudsmith.io domain redirects to the download domain. If your HTTP library does not follow redirects, use the dl.cloudsmith.io domain with path-based authentication instead.

Download via the HTML Index

Cloudsmith supports serving Apache-style HTML formatted indexes of generic package files in the repository.

Disabled by Default

HTML index generation is disabled by default. Enable it in Repository Settings under the Generic section.

When the HTML index is disabled (by default), the repository only supports direct file downloads. Requests for specific files can be configured to proxy (if the file exists on the upstream) or served from the repository cache.

When the HTML index is enabled, requests to directory paths (without specifying a file) will return an HTML view showing the index of available files and subdirectories.

When enabled, the HTML index is available at: https://generic.cloudsmith.io/OWNER/REPOSITORY/

Public Repositories

Browse the HTML index to view and download packages directly in your browser.

Private Repositories

When accessing the HTML index in a browser for private repositories, you will be prompted for authentication. Enter token as the username and your entitlement token or API key as the password to view the index.

After entering valid credentials, you should then be able to view the HTML index.

Upstream Proxying / Caching

The Generic format supports upstream proxying and caching for simple HTML-based sources and select non-HTML sources. When a file is requested, Cloudsmith checks for a local copy. If missing, it fetches the file from the upstream, caches it as a first-class local package, and serves it.

Supported Upstream Sources

The Generic format accepts any files or binaries, not just traditional software packages. The following upstream sources are explicitly supported and work out of the box:

• Gradle - Gradle distributions
• Node - Node.js distributions
• Hashicorp - Hashicorp releases
• Fluentbit - Fluentbit distributions
• GitHub - GitHub Releases
• HTML-based sources - Simple, unstyled HTML pages with no JavaScript, where each page contains only links to files or subdirectories (e.g., Apache releases)

Enterprise Repository Support

Enterprise repository managers like Artifactory and Sonatype Nexus require additional configuration and will not work out of the box. These sources also have practical size limits—repositories with millions of packages may not be processable. Contact support to discuss setup for these upstream sources.

Configure an Upstream

To configure an upstream for your Generic repository, browse to your repository overview page and click the Upstreams tab. Then, click + Add Upstream Proxy and choose the Generic format upstream.

In the upstream creation menu, define a name for your upstream and enter the upstream URL. You must specify an Upstream Prefix to prevent file collisions when using multiple upstreams. The prefix becomes part of the file's permanent path in the repository, ensuring files from different upstreams never collide, even with identical filenames.

Please see our Upstream Proxying documentation for further instructions on configuring upstreams.

Example: Node.js Distributions

This example demonstrates how upstream URLs, prefixes, and file paths work together.

Upstream configuration:

• Upstream URL: https://nodejs.org/dist/
• Upstream Prefix: node_distributions

How paths are resolved:

The upstream URL includes the base path (/dist/), so file paths are relative to that location. To download https://nodejs.org/dist/latest/node-v25.6.1.tar.gz, request the path latest/node-v25.6.1.tar.gz from Cloudsmith:

Download command:

curl -sLf -O 'https://generic.cloudsmith.io/OWNER/REPOSITORY/node_distributions/latest/node-v25.6.1.tar.gz'

The upstream prefix (node_distributions) ensures files from Node.js don't collide with files from other upstreams, even if they share identical file paths.

Upstream Priority

Upstream priority behaves differently for Generic repositories due to the nature of upstream prefixes. All upstreams within a prefix are given a priority of 1. Changing the priority setting does not impact package blending, as each upstream is uniquely namespaced within its own prefix.

Local packages (directly uploaded to the repository) always take precedence over upstream packages. When viewing the HTML index, cached packages display with a different icon than packages that will be proxied on demand.

Key Signing Support

Generic files are stored and served as-is without package signing. If you need signed packages, consider using the Raw format, which supports GPG signatures.

Troubleshooting

Please see the Troubleshooting page for further help and information.

Updated last week