Workspaces

Custom domains

Your company brand and trust are important to you and your customers, and with custom domains you can present your own company as the endpoint for distribution, APIs, and configuration (e.g. retrieving GPG keys).

This is a great idea if you are:

A vendor that is selling and distributing software to your customers
A security-conscious DevOps team that is looking to control the source endpoint for artifacts

Disambiguation
If you are looking for Broadcast URL customization, please refer to the Broadcasts documentation or contact us.

Custom domains are available with our Ultra and Enterprise plans. We strongly recommend - and may require - custom domains for any customer with significant Cloudsmith package delivery traffic.

Configuration options

Account-wide vs per-repository

An account-wide (also called organizational-level) custom domain works across all repositories in your Cloudsmith organization. When using an account-wide custom domain, the organization/account identifier (slug) will be removed from the URI for a repository.

A per-repository custom domain works for a single repository in your Cloudsmith organization. When using a per-repository custom domain, the organization/account identifier (slug) and the repository identifier are both removed from the URI for the repository.

Package support (download vs native API)

For API-based (Native) package formats, such as NuGet, Docker, Cargo, npm, Conan, Conda, Go and Terraform, you can have a specific custom domain, such as docker.yourdomain.com, npm.yourdomain.com or cargo.yourdomain.com.

For other package formats, and downloads in general, you can have a custom domain such as dl.yourdomain.com.

It is possible to have multiple download domains for a package type, however, all of them will be accessible through each other, for example, if we set up a general Downloads domain for raw packages and a Debian domain (which is also Download), we will be able to hit the Downloads domain to get Debian packages.

Please refer to the table below to see which package will utilize Download/API Native domains.

Package Type	Download	Native Uploads	Native Downloads
Alpine	✅	❌	❌
Cargo (Rust)	✅	❌	✅
Chocolatey	-	✅	✅
Cocoapods	✅	❌	❌
Composer	✅	❌	✅
Conan	-	✅	✅
Conda	✅	❌	✅
CRAN	✅	❌	❌
Dart	-	✅	✅
Debian	✅	❌	❌
Docker	-	✅	✅
Go	✅	❌	✅
Gradle	✅	✅	❌
Helm	✅	❌	❌
Hex	-	✅	✅
LuaRocks	✅	❌	❌
Maven	✅	✅	❌
Nix	-	✅	✅
npm	-	✅	✅
NuGet	-	✅	✅
PowerShell	-	✅	✅
Python	✅	✅	❌
Raw	✅	-	-
RPM	✅	❌	❌
Ruby	✅	✅	❌
sbt	✅	✅	❌
Swift	✅	✅	❌
Terraform	✅	❌	✅
Unity	-	✅	✅
Vagrant	✅	❌	❌

Top level redirects

You can request that the top-level of your domain (e.g. npm.example.com) redirect to a location of your choice. For example, to the Cloudsmith web app for your repositories if public, or to your own customer support page.

If you'd like to configure this, please include it in your request.

List domains with the Cloudsmith CLI

Use cloudsmith domains list to identify the built-in and custom domains that the CLI and its credential helpers can authenticate to.

List the built-in domains and any custom domains cached by an earlier command:

shell

cloudsmith domains list

Fetch the custom domains for a workspace:

shell

cloudsmith domains list --workspace WORKSPACE

Replace WORKSPACE with your workspace slug. When filtering for one repository, replace REPOSITORY with its repository slug.

You can set CLOUDSMITH_WORKSPACE or workspace in config.ini instead of passing --workspace to each command.

Only enabled and validated custom domains are returned. Custom domains appear before built-in Cloudsmith domains so that clients can select the preferred endpoint.

Use these options to narrow or refresh the result:

Option	Description
`-w, --workspace WORKSPACE`	Fetch custom domains for a workspace.
`--format FORMAT`	Return domains that can serve a package format, plus the general download and upload endpoints.
`--repo, --repository REPOSITORY`	Return domains that can serve a repository. Repository-specific domains are listed before workspace-wide domains.
`--domain-type TYPE`	Return one endpoint type: `download`, `upload`, or `native_api`.
`--refresh`	Bypass the custom-domain cache and fetch current data from the API. Set a workspace to fetch fresh data.
`-p, --page PAGE`	Return one page of results.
`-l, --page-size INTEGER OR *`	Set the number of results on each page. Use `*` to return all results.
`--page-all, --show-all`	Return all results. This is the default unless `--page` or `--page-size` is set. Do not combine this option with either pagination option.

For example, list the preferred npm domains for a repository:

shell

cloudsmith domains list \
  --workspace WORKSPACE \
  --repo REPOSITORY \
  --format npm

A shortened response has this shape:

json

{
  "version": 1,
  "domains": [
    {
      "host": "npm.example.com",
      "format": "npm",
      "type": "custom",
      "domain_type": "native_api",
      "workspace": "example-workspace",
      "repository": null,
      "primary": true,
      "created_at": "2026-01-01T00:00:00Z"
    }
  ]
}

Using --page or --page-size also adds pagination details under meta.pagination.

Setup

To configure a custom domain within Cloudsmith, we require you to provide:

A list of domains that you wish to have for each package type (refer to the table above). We recommend having only 1 domain for Download types, but this can be set up to include multiple if needed.
For each domain, do you wish to have an account-wide or per-repository domain
Finally, would you like to have a top level redirect for your domain

Example request:

Domain: `docker.mycompany.com` (Docker)  
Account wide  
No redirect

Once created within Cloudsmith, you will need to create two DNS CNAME entries for each domain you wish to configure within your DNS provider.

Step 1

The process begins when you contact us via support with a list of custom domains you would like to configure. We will review and start processing your request, ensuring your plan is eligible to make use of the custom domain feature.

Step 2

After confirming the domains you need, a member of the team will review and configure them within Cloudsmith. Once set, the DNS CNAME entries will be visible in your account (in the "Custom Domains" section of any repository)

Step 3

You then add the DNS CNAME entries to your domain DNS records with your DNS provider. The first CNAME is for authorizing the domain, and the second is to make it visible and accessible to your users.
Once you have configured the CNAME's, you will then be able to make use of your custom domains.
Please just contact us if you would like to set this up or require any further information.

Updated 1 hour ago