Supported formats

Nix repository

Nix is a package manager used by NixOS. Nix packages are distributed as pre-built, content-addressed artifacts served from a binary cache.

Cloudsmith supports hosting a public or private Nix binary cache. Packages are published and consumed using the standard Nix tooling (nix copy, nix build) — there is no separate upload format or file type to prepare beforehand.

For more information, see:

• Nix: The official Nix website
• Nix Manual: The Nix command and configuration reference
• Nix HTTP Binary Cache Store: The protocol Cloudsmith implements

Early Access

The Nix format is available in Early Access. Some functionality, such as CLI-based package upload and upstream management, is not yet available. Instead, use the native nix tooling and the Cloudsmith web app as described in Upload a package and Download / install a package.

What Cloudsmith supports

Cloudsmith Nix repositories support:

• Public and private binary cache hosting — serve NAR (Nix ARchive) and narinfo files to authenticated users or publicly, using the standard Nix HTTP binary cache protocol
• ED25519 signing — every repository has a dedicated ED25519 signing key. Cloudsmith re-signs the narinfo for every package on every read, so key rotation and multiple simultaneous signatures are fully supported (see Key management)
• Upstream proxying and caching — proxy and cache packages from a NixOS release channel (see Upstream proxying / caching)

Public key required to download packages

Trust for the Nix binary cache protocol is established separately from HTTPS/transport security.

Before you can install a package from a Cloudsmith Nix repository, you must add the repository's ED25519 public key to trusted-public-keys in your Nix configuration. Without it, nix build and nix copy will refuse to substitute from the cache, even though the underlying HTTP request succeeds. For more details, see Get your repository's public key.

In the following examples:

Upload a package

Cloudsmith ingests Nix packages by using the native Nix binary cache protocol. Unlike other formats, Nix packages cannot be uploaded using the Cloudsmith CLI or the Cloudsmith web app. You can publish a package with the standard nix copy command.

Upload via nix copy

First, build your package:

nix build .#default

Then copy the resulting store path, including its full dependency closure, to your Cloudsmith repository:

STORE_PATH="$(readlink -f result)"

nix copy --to 'https://nix.cloudsmith.io/OWNER/REPOSITORY' \
  --no-check-sigs \
  "$STORE_PATH"

Why --no-check-sigs

A store path that you build locally is unsigned. Cloudsmith signs the narinfo for every package server-side, on every read, using the repository's ED25519 key, you must pass --no-check-sigs when pushing a package. Downstream consumers who trust your repository's public key will still see a validly signed narinfo when they pull the package.

Alternatively, you can sign locally before copying by using nix store sign --key-file KEY_FILE "$STORE_PATH".

Private repositories

To publish to a private repository, authenticate using your Cloudsmith entitlement token as the password in a netrc file:

machine nix.cloudsmith.io
login token
password TOKEN

Then reference the netrc file in your Nix configuration, or pass --option netrc-file /path/to/netrc on the command line:

netrc-file = /path/to/netrc

Upload via Cloudsmith CLI or web app

Uploading Nix packages via the Cloudsmith CLI or web app is not currently supported. Publish packages using nix copy, as described in Upload via nix copy.

Download / install a package

Get your repository's public key

In the Cloudsmith web app, go to your repository Settings tab, select Key management > Artifact signing, and copy the ED25519 public key. It's in the format Nix expects for trusted-public-keys:

KEY_NAME:PUBLIC_KEY

Configure Nix to use your repository

Add your repository as a substituter and trust its public key, either in nix.conf (for example, /etc/nix/nix.conf or ~/.config/nix/nix.conf) or per invocation.

In nix.conf:

extra-substituters = https://nix.cloudsmith.io/OWNER/REPOSITORY
extra-trusted-public-keys = KEY_NAME:PUBLIC_KEY

Per invocation:

nix build --option substituters 'https://nix.cloudsmith.io/OWNER/REPOSITORY' \
  --option trusted-public-keys 'KEY_NAME:PUBLIC_KEY' \
  .#default

Private repositories

Secrets management

Entitlement tokens should be treated as secrets. Ensure that you do not commit them in configuration files along with source code, or expose them in any logs.

For private repositories, configure a netrc file as described in Private repositories, or embed the token directly in the substituter URL:

extra-substituters = https://token:TOKEN@nix.cloudsmith.io/OWNER/REPOSITORY
extra-trusted-public-keys = KEY_NAME:PUBLIC_KEY

Installing a package

Nix addresses packages by store path rather than by name and version, so there's no direct equivalent of apt install PACKAGE for packages you've published yourself. Once your repository is configured as a substituter, fetch a specific store path with:

nix copy --from 'https://nix.cloudsmith.io/OWNER/REPOSITORY' STORE_PATH

Or build/run a flake output that resolves to a path already cached in your repository. Nix will transparently substitute it from Cloudsmith instead of building it locally:

nix build .#default
nix run .#default

If your repository's public key isn't configured correctly, you'll see an error similar to:

error: cannot add path '/nix/store/...' because it lacks a signature by a trusted key

Upstream proxying / caching

The Nix format supports upstream proxying and caching for NixOS release channels. When a store path is requested that Cloudsmith doesn't have locally, Cloudsmith checks the configured upstreams, fetches and caches the package, then serves it.

Supported upstream sources

One channel per upstream

Each Nix upstream must point at exactly one channel. To proxy and cache multiple NixOS releases, configure a separate upstream for each — for example, one upstream with upstream_url set to https://channels.nixos.org/nixos-26.05 and a second with https://channels.nixos.org/nixos-25.11.

Configure an upstream

When creating the upstream, set the Proxy URL to the NixOS release channel you want to proxy and cache, for example:

https://channels.nixos.org/nixos-26.05

For more information about form fields and configuration options, including a known limitation around full dependency closures on NixOS release channels, see Create a Nix upstream.

Key management

Cloudsmith signs Nix packages using an ED25519 key, per the Nix binary cache signing scheme. Unlike file-based signing on other formats, the narinfo is signed on every read rather than once at upload time. This means that key rotation takes effect immediately for all packages, and multiple keys can be active and signing simultaneously.

Updated 2 hours ago