Supported formats

Cargo registry

Cloudsmith provides public & private registries for Cargo (Rust).

For more information on Rust, please see:

• Rust: The official website for Rust language
• Cargo: The official documentation for Cargo - the Rust package manager
• Crates Public Registry: The official Rust community's crate registry

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 workspace, repository, and RSA key pre-configured.

In the following examples:

Upload a package

Upload via Cargo publish

A name and URL for the registry must be added to your .cargo/config file as follows:

Public repositories

[registries]
REGISTRY_NAME = { index = "https://dl.cloudsmith.io/public/WORKSPACE/REPOSITORY/cargo/index.git" }

Private repositories

Private Repositories

Private Cloudsmith repositories require authentication. You can choose between two types of authentication, Entitlement Token Authentication or HTTP Basic Authentication. The setup method will differ depending on what authentication type you choose to use.

Warning

Entitlement Tokens, User Credentials and API-Keys should be treated as secrets, and you should ensure that you do not commit them in configurations files along with source code, or expose them in any logs.

Authenticate with the Cloudsmith credential helper

The Cloudsmith credential helper lets Cargo use credentials configured in the Cloudsmith CLI. It avoids cargo login and does not write a token to Cargo's credentials.toml.

This setup requires Cargo 1.74 or later, which supports credential helpers for authenticated registries.

First, configure the registry without a token:

[registries.WORKSPACE-REPOSITORY]
index = "sparse+https://cargo.cloudsmith.io/WORKSPACE/REPOSITORY/"

Then install the credential helper:

cloudsmith credential-helper install cargo

The installer creates a cargo-credential-cloudsmith launcher and registers it in $CARGO_HOME/config.toml, or ~/.cargo/config.toml when CARGO_HOME is not set. It adds the credential helper after cargo:token in the [registry] global-credential-providers list. Cargo evaluates the list in reverse order, so Cloudsmith credentials are tried first.

The credential helper resolves an API key supplied directly or loaded from credentials.ini, an SSO token from the configured keyring, or automatically discovered OIDC credentials through the same chain as the CLI. It only returns credentials for Cloudsmith Cargo registries. For other registries, including crates.io, it tells Cargo to continue to the next credential helper.

The credential helper implements Cargo's authentication protocol. Cargo configures credential helpers with the credential-provider and global-credential-providers keys; these names remain unchanged.

To discover custom Cloudsmith domains for a workspace:

cloudsmith credential-helper install cargo --workspace WORKSPACE

Useful installation options:

To inspect or remove installed credential helpers:

cloudsmith credential-helper list
cloudsmith credential-helper uninstall cargo

Uninstalling removes the Cloudsmith launcher and configuration while preserving other Cargo credential helpers. CLI versions earlier than v1.30.0 installed the launcher next to the cloudsmith executable. To remove that launcher, pass its directory with --bin-dir.

The following static authentication methods remain available if you do not install the Cloudsmith credential helper.

# Entitlement Token Auth
[registries]
REGISTRY_NAME = { index = "https://dl.cloudsmith.io/TOKEN/WORKSPACE/REPOSITORY/cargo/index.git" }

# HTTP Basic Auth
[registries]
REGISTRY_NAME = { index = "https://dl.cloudsmith.io/basic/WORKSPACE/REPOSITORY/cargo/index.git" }

If using HTTP basic authentication, you'll need to configure Git with credentials. Git's standard authentication mechanisms are used by Cargo and can be configured in the normal way. For example, you could use git's per-user credential store as follows:

# HTTP Basic Auth (User & Pass)
git config --global credential.helper store
echo "https://USERNAME:PASSWORD@dl.cloudsmith.io" > ~/.git-credentials

# HTTP Basic Auth (API-Key)
git config --global credential.helper store
echo "https://USERNAME:API-KEY@dl.cloudsmith.io" > ~/.git-credentials

# HTTP Basic Auth (Token)
git config --global credential.helper store
echo "https://token:TOKEN@dl.cloudsmith.io" > ~/.git-credentials

For further details or other configuration options, see the Official Git Documentation.

If you do not use the Cloudsmith credential helper, you can authenticate for publishing by entering your credentials with:

cargo login --registry REGISTRY_NAME

Or, add your credentials to your .cargo/credentials file:

[registries.REGISTRY_NAME]
token = API-KEY

Publish

To publish a crate, you can do so from your project directory using cargo publish as follows:

cargo publish --registry REGISTRY_NAME

If you haven't configured the Cloudsmith credential helper or specified credentials using one of the static methods above, you'll be asked to provide them using cargo login.

Instead of using the previous authentication methods, you can also set the following environment variables to define your index and token:

• CARGO_REGISTRIES_<REGISTRY_NAME>_INDEX
• CARGO_REGISTRIES_<REGISTRY_NAME>_TOKEN

Remember to rename the variable with your registry name.

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 a cargo crate via the Cloudsmith CLI is:

cloudsmith push cargo WORKSPACE/REPOSITORY PACKAGE_NAME.crate

Example:

cloudsmith push cargo org/repo your-package.crate

Upload via Cloudsmith web app

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

Download a package

Configure a new upstream

Cloudsmith supports https://index.crates.io as an upstream. This allows you to proxy and cache external Rust crates that are not part of your repository.

To enable the upstream, browse to your repository overview page and click in the Upstreams tab. Then, click on + Add Upstream Proxy and then choose the Cargo Upstream.

In the Upstream creation menu, define a name your Upstream and in the Proxy URL field insert https://index.crates.io/. Click on + Create Upstream Proxy and the upstream should become immediately available.

Registry setup

It is easy to add a Cloudsmith-based Cargo registry.

For private registries, the recommended setup is the Cloudsmith credential helper. It uses existing CLI credentials without storing a token in Cargo configuration and leaves authentication for crates.io unchanged.

Cargo Sparse Registry

Cargo Sparse Registries are a new addition to Cargo as of v1.68.0, and are the recommended way to interact with your Cloudsmith Repositories - they offer significant performance advantages over the old Git-based registries, such as reducing the bandwidth used and improving dependency resolution times.

First, the name and config for the registry must be added to your .cargo/config.toml or .cargo/config file as follows:

Cargo >= v1.74 (HTTP sparse registry)

[registries.WORKSPACE-REPOSITORY]
index = "sparse+https://cargo.cloudsmith.io/WORKSPACE/REPOSITORY/"
token = "Token API-KEY"
credential-provider = "cargo:token"

[registries.WORKSPACE-REPOSITORY]
index = "sparse+https://cargo.cloudsmith.io/WORKSPACE/REPOSITORY/"
token = "Token TOKEN"
credential-provider = "cargo:token"

config.toml

Once you’ve configured your credentials in the config.toml file, there’s no need to run cargo login. Cargo will automatically authenticate using the token from the configuration.

Cargo < v1.74 (HTTP sparse registry)

If you are using Cargo version < 1.74, the only way to authenticate with a private sparse registry is using Cloudsmith's URL-based authentication.

[registries.WORKSPACE-REPOSITORY]
index = "sparse+https://dl.cloudsmith.io/TOKEN/WORKSPACE/REPOSITORY/cargo/"

Cargo < v1.68 (legacy Git registry)

[registries]
WORKSPACE-REPOSITORY = { index = "https://dl.cloudsmith.io/basic/WORKSPACE/REPOSITORY/cargo/index.git" }

[registries]
WORKSPACE-REPOSITORY = { index = "https://dl.cloudsmith.io/TOKEN/WORKSPACE/REPOSITORY/cargo/index.git" }

Registry authentication

You must configure Git with the proper credentials to clone the registry when using HTTP basic authentication. Git's standard authentication mechanisms are used by Cargo and can be configured normally. For example, you could use git's per-user credential store like so:

git config --global credential.helper store
echo "https://USERNAME:API-KEY@dl.cloudsmith.io" > ~/.git-credentials

When using URL-based authentication, no further configuration is required, you're all set up and ready to go.

Install a package

Once you have configured a registry using one of the methods described above, a crate can then depend on a crate from your registry by specifying the registry key and a value of the registry's name in that dependency's entry in Cargo.toml:

[package]
name = "PROJECT_NAME"
version = "0.1.0"
[dependencies]
PACKAGE_NAME = { version = "PACKAGE_VERSION", registry = "REGISTRY_NAME" }

You can also install a crate directly by specifying the registry on the command line:

cargo install PACKAGE_NAME --registry REGISTRY_NAME`

Vulnerability detection

Please see our vulnerability detection documentation for further information.

Key signing support

Known limitations

The cargo search command is not supported.

Troubleshooting

Q. It's not working...
Cargo's cache can become corrupted. If this happens, you can often fix the issue by manually deleting the cache directories. The folders to remove are:

• ~/.cargo/registry
• ~/.cargo/git

If you previously set an override for $CARGO_HOME, the cache may be in a non-standard location.

Still need help?

Contact us here. We're always happy to help.

Updated yesterday