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 an Entitlement Token or API Key depending on the authentication method. The following authentication methods do not work when 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 with HTTP Basic Auth to download files:

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

Alternatively, embed HTTP Basic Auth credentials in the URL as user information:

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

API Key Authentication (generic.cloudsmith.io):

Use an API Key with the X-Api-Key header to download files. An Entitlement Token cannot be used with this method.

curl -sLf -H "X-Api-Key: API-KEY" -O "https://generic.cloudsmith.io/OWNER/REPOSITORY/UPSTREAM_PREFIX/path/to/file.tar.gz"

Authentication when using the Download domain (dl.cloudsmith.io):

The dl.cloudsmith.io domain most commonly uses path-based authentication with entitlement tokens embedded in the URL path. There are some exceptions:

HTTP Basic Auth with credentials in the userinfo portion of the URL (e.g., token:TOKEN@dl.cloudsmith.io) is only supported for the /basic/... download route on this domain and is not supported for the default /TOKEN/... path-based URLs.

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

Include generic/download/ in the URL path before the upstream prefix to ensure requests are routed correctly.

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

Supported Authentication by Domain:

A URL follows the structure: scheme://userinfo@host/path

• Userinfo (token:TOKEN@): Credentials placed before the host.
• Path (/TOKEN/...): Token embedded after the domain in the URL path. This only works on dl.cloudsmith.io.

Note: Not all forms of Basic Auth are supported on this domain. See the documented example, HTTP Basic Auth with credentials in the userinfo portion of the URL.

When to use the download domain

Use dl.cloudsmith.io instead of generic.cloudsmith.io when:

• Your HTTP library doesn't follow redirects: The generic.cloudsmith.io domain redirects to dl.cloudsmith.io. Some libraries require manual redirect handling.
• Your tooling doesn't support credentials in the URL (userinfo): Some tools cannot pass credentials in the userinfo portion of URLs (token:TOKEN@host), but can construct URLs with tokens in the path.
• You want consistency with other formats: Other Cloudsmith package formats use dl.cloudsmith.io with path-based authentication. Using the same pattern simplifies configuration across formats.
• You need direct download URLs: Path-based URLs on dl.cloudsmith.io can be shared or embedded without requiring separate authentication configuration.

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 3 days ago