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. You can upload packages and manage Nix channel upstreams with the Cloudsmith web app, API, and CLI, or publish and consume packages with native Nix tooling.

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. You can upload a NAR file and its narinfo metadata with the Cloudsmith CLI, or publish a store path with the standard nix copy command.

Upload via the Cloudsmith CLI

To upload a NAR file, optionally with its matching narinfo sidecar:

cloudsmith push nix WORKSPACE/REPOSITORY STORE_HASH.nar \
  --narinfo-file STORE_HASH.narinfo

The NAR file is required. The --narinfo-file option is optional, but including the matching STORE_HASH.narinfo file completes the package in the same command. You can also add standard push options such as --tags, --republish, and --no-wait-for-sync.

For information about installing and authenticating the CLI, see Command-line interface.

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/WORKSPACE/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, so 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 the web app

Uploading Nix packages via the Cloudsmith web app is not currently supported. Use the Cloudsmith CLI or 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/WORKSPACE/REPOSITORY
extra-trusted-public-keys = KEY_NAME:PUBLIC_KEY

Per invocation:

nix build --option substituters 'https://nix.cloudsmith.io/WORKSPACE/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/WORKSPACE/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/WORKSPACE/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

You can also create the upstream with the Cloudsmith CLI. Save the configuration as nix-upstream.json:

{
  "name": "NixOS 26.05",
  "upstream_url": "https://channels.nixos.org/nixos-26.05",
  "mode": "Cache and Proxy",
  "auth_mode": "None",
  "priority": 1
}

Then create the upstream:

cloudsmith upstream nix create WORKSPACE/REPOSITORY nix-upstream.json

Use the remaining subcommands to list, update, or delete Nix upstreams:

cloudsmith upstream nix list WORKSPACE/REPOSITORY
cloudsmith upstream nix update WORKSPACE/REPOSITORY/SLUG_PERM nix-upstream.json
cloudsmith upstream nix delete WORKSPACE/REPOSITORY/SLUG_PERM

The list output includes the permanent upstream slug required by update and delete. Deleting an upstream asks for confirmation; pass --yes in unattended scripts.

For more information about form fields and configuration options, 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 last week