Browse and manage the module catalog

CloudSmith modules extend the platform with additional capabilities — monitoring, firmware management, update orchestration, and more. Modules are distributed as OCI artifacts on the GitHub Container Registry (ghcr.io/cloudsmith-cloud/) and are cosign-signed by the CloudSmith release pipeline.

First-party modules

Module ID Name Description
cloudsmith-module-hello Hello World Reference implementation and fork template for third-party module authors. Demonstrates the full module lifecycle, nav slot registration, health checks, and CI publishing. See the Hello World module reference.

What modules are

A module is a self-contained capability bundle that plugs into the CloudSmith platform using the ICloudSmithModule lifecycle interface. Each module:

  • Ships as an OCI artifact on ghcr.io/cloudsmith-cloud/
  • Is cosign-signed and carries a verification badge in the catalog
  • Can be installed, updated, and removed without restarting the platform
  • Runs inside the cloudsmith-api process space and has access to platform services via dependency injection

How the GHCR-based catalog works

The module catalog is a live list that CloudSmith fetches from ghcr.io/cloudsmith-cloud/ on demand. Each catalog entry includes:

Field Description
Module ID Unique stable identifier (e.g., monitoring)
Name Display name
Version Current version in the catalog
Verified Whether the image has a valid cosign signature from the CloudSmith release key
Installed Whether this module is currently installed on your platform
Update available Whether the catalog version is newer than the installed version
Description What the module does
Catalog source Full ghcr.io image reference

Modules without a valid cosign signature are shown with a warning badge. Installing an unverified module requires explicitly acknowledging the warning.

Browse the catalog in the portal

  1. Open the portal and sign in.
  2. In the left navigation, select Platform Management → Modules.
  3. The All modules tab shows the full catalog. Use the search box to filter by name or description.
  4. Select Installed to filter to modules already on your platform.
  5. Select Updates available to see modules with a newer version in the catalog.
  6. Select any module row to open the module details panel, which shows the description, version history, cosign verification status, and install/uninstall button.

Install a module from the portal

  1. Open Platform Management → Modules.
  2. Find the module you want in the All modules tab.
  3. Select the module row and click Install in the details panel.
  4. If prompted, confirm the version and select Confirm install.
  5. A progress indicator appears in the details panel. Installation is asynchronous and typically completes in 30–120 seconds.
  6. Once installed, the module row moves to the Installed tab and its status badge turns green.

Uninstall a module from the portal

  1. Open Platform Management → Modules and select the Installed tab.
  2. Select the module row and click Uninstall in the details panel.
  3. Confirm the uninstall when prompted.
  4. The module is removed and the row returns to the All modules tab with status Available.

Apply a module update from the portal

When a newer module version is available, the module row displays an Update available badge.

  1. Open Platform Management → Modules and select Updates available.
  2. Select the module row and click Update to <version>.
  3. The update pulls the new image, verifies the cosign signature, and performs a rolling swap. The module is unavailable for approximately 10–30 seconds during the swap.

CLI — module catalog commands

List modules

# List all modules in the catalog
cs module catalog list

# List only cosign-verified modules
cs module catalog list --verified

# List only installed modules
cs module catalog list --installed

# Output as JSON
cs module catalog list --format json

Example output (--format table):

ID             NAME                     VERSION  VERIFIED  INSTALLED
monitoring     CloudSmith Monitoring    1.2.0    Yes       No
firmware       CloudSmith Firmware      0.9.1    Yes       No

Get module details

cs module catalog get monitoring

Example output:

ID:           monitoring
Name:         CloudSmith Monitoring
Version:      1.2.0
Verified:     Yes
Installed:    No
Description:  Prometheus-based workload monitoring for Hyper-V clusters.
Source:       ghcr.io/cloudsmith-cloud/module-monitoring:1.2.0

Install a module

# Install the latest verified version
cs module install --from-catalog monitoring

# Install a specific version
cs module install --from-catalog monitoring --version 1.1.0

Uninstall a module

cs module uninstall monitoring

PowerShell — module catalog cmdlets

List the catalog

# All modules
Get-CSModuleCatalog

# Only installed modules
Get-CSModuleCatalog -Installed

# Only cosign-verified modules
Get-CSModuleCatalog -Verified

# Get a specific module
Get-CSModuleCatalog -Id monitoring

Install a module

# Install the latest verified version
Install-CSModule -ModuleId monitoring -FromCatalog

# Install a specific version
Install-CSModule -ModuleId monitoring -FromCatalog -Version 1.1.0

Uninstall a module

Remove-CSModule -ModuleId monitoring

Cosign verification badge

The verification badge in the catalog indicates that the module image was signed by the CloudSmith release pipeline using the project’s cosign key. Verification is performed automatically when you install from the catalog using the portal, cs module install, or Install-CSModule.

CloudSmith’s public cosign key is published at: https://github.com/cloudsmith-cloud/cloudsmith-installer/releases/latest/download/cloudsmith-cosign.pub

To manually verify a module image:

cosign verify `
    --key 'cloudsmith-cosign.pub' `
    ghcr.io/cloudsmith-cloud/module-monitoring:1.2.0

A module that cannot be verified will show a warning badge in the portal and the CLI will prompt for confirmation before installing.