Release channels

Run Mondoo release candidates on machines you choose, so you can test a major version against your own environment before it ships

Mondoo publishes every cnspec and mql release to a channel. The stable channel carries released versions and is what you get unless you ask for something else. The preview channel carries release candidates for the next version, so you can run one against your own assets before it ships.

That is what preview is for: a major version reaches your policies, your custom queries, and your scan times on a machine you picked, at a time you picked, while there is still room to act on what you find.

How channels work

A release's channel comes from its version number. Nothing declares it separately:

Version	Channel	Why
`13.38.1`	stable	A released version
`14.0.0-rc.7`	preview	A pre-release
`12.5.0+41`	stable	Build metadata is not a pre-release

Preview always points at the highest version available, which includes released ones. A client following preview is never moved backward when a release lands on top of the release candidate it was running.

Stable is the default. When update_channel is unset or holds a name cnspec doesn't recognize, cnspec follows the channel of the build it's running: a released version follows stable, and a release candidate follows preview. A released version never moves to preview unless you ask for it.

See what each channel points at

This installs nothing and changes nothing on your machine:

curl -s  https://install.mondoo.com/package/cnspec/latest.json                  | jq -r .version
curl -s "https://install.mondoo.com/package/cnspec/latest.json?channel=preview" | jq -r .version

Substitute mql for cnspec to ask about the mql binary instead. The two products are versioned independently, so their release candidates do not always match.

To confirm which channel answered, read the channel field:

curl -s "https://install.mondoo.com/package/cnspec/latest.json?channel=preview" | jq -r .channel

How preview is distributed

Preview is published as versioned artifacts, and an install method can offer it when it resolves a specific version to fetch:

Install method	Preview available
Portable archive (`.tar.gz`, `.zip`)	Yes
Direct binary download script	Yes
macOS `.pkg`	Yes
Windows MSI and zip	Yes
apt, yum, dnf, zypper, Homebrew, Chocolatey	No, these serve the stable channel

Package managers install whatever their repository serves, and the Mondoo package repositories carry stable releases. If you ask the agent installer for preview on a machine where it would use a package manager, it says so and installs the stable release rather than quietly giving you one thing when you asked for another.

Run a preview build without installing it

Download into a temporary directory and run it there, leaving any existing install untouched:

cd "$(mktemp -d)" && \
  curl -sSL "https://install.mondoo.com/package/cnspec/linux/amd64/tar.gz/latest/download?channel=preview" \
  -o cnspec.tar.gz && tar xzf cnspec.tar.gz && ./cnspec version

Substitute your platform: linux/amd64, linux/arm64, darwin/amd64, or darwin/arm64.

Dropping ?channel=preview from any of these gives you the stable build instead.

Install a preview build

The binary download script honors MONDOO_CHANNEL and works on every Linux distribution and on macOS:

MONDOO_PRODUCT=cnspec MONDOO_CHANNEL=preview \
  bash -c "$(curl -sSL https://install.mondoo.com/download/sh)"

On macOS, the agent installer can lay down a preview build through the .pkg installer. Select it explicitly, because the installer prefers Homebrew when Homebrew is present:

curl -sSL https://install.mondoo.com/sh | bash -s -- -i pkg -c preview

Move an existing install to preview

To follow preview from now on, set the channel in mondoo.yml:

update_channel: preview

To set it for one shell session:

export MONDOO_UPDATE_CHANNEL=preview

To cross over for a single command, without changing any configuration, pass --channel. It accepts stable or preview, and any other value is an error:

cnspec update --channel preview
cnspec providers install notion --channel preview

Providers resolve through the channel too, so a preview client installs preview providers. This matters for a provider that has only ever been published as a pre-release: on stable it is correctly reported as unavailable rather than quietly resolving to a release candidate.

Check which channel you're on

cnspec status always names the update channel:

cnspec status

cnspec update names it as well, so "already the latest version" tells you the latest version on your channel rather than leaving you to wonder whether the setting took effect.

Where each setting applies

Several places take a channel, because several different things resolve one:

Setting	Applies to
`update_channel` in `mondoo.yml`	Every self-update and provider install on that machine
`MONDOO_UPDATE_CHANNEL`	The same, for one shell session
`--channel` on `cnspec update` and `cnspec providers install`	A single command
`-c` on the agent install script, `-Channel` in PowerShell, `MONDOO_CHANNEL` for the binary download script	The version a fresh install lays down
`?channel=` on an `install.mondoo.com` package URL	One download

Return to stable

Self-update only ever moves forward, so a client on preview stays there until the stable channel catches up. When a version is released, a client running one of its release candidates, such as 14.0.0-rc.7, updates to the release normally. Running cnspec update --channel stable on a release candidate reports that there's nothing newer rather than rolling back.

To move a machine back to an earlier major version, set the channel back to stable and reinstall.

Preview tracks the newest pre-release across all major versions, not within one. When release candidates for the next major begin, a client following preview starts following those. Pin a version if you need to stay on a particular major.