Install CloudSmith — Bundled mode

Bundled mode packages the Ubuntu 24.04 cloud image and all CloudSmith container images inside the installer zip. No internet access is required on the management host after the bundle is transferred. Use this mode when the management host cannot reach ghcr.io or cloud-images.ubuntu.com at install time.

Prerequisites

Windows Server 2022 or 2025 (Standard or Datacenter) with Hyper-V role installed
PowerShell 7.4 or later on the management host (pwsh --version to confirm)
10 GB RAM available on the management host
80 GB free disk space on the target VHDX drive
A separate connected machine to download the ~1.2 GB bundle
Port 443 inbound from operator workstations (installer creates the firewall rule)

If the management host is itself a Hyper-V VM, enable nested virtualization on the parent host before running the installer:

# Run on the parent Hyper-V host
Set-VMProcessor -VMName '<management-vm-name>' -ExposeVirtualizationExtensions $true

Step 1 — Download the bundle (on a connected machine)

Run the following on a machine with internet access:

$bundleUrl = 'https://github.com/cloudsmith-cloud/cloudsmith-installer/releases/latest/download/Install-CloudSmith-Bundled.zip'
Invoke-WebRequest -Uri $bundleUrl -OutFile 'Install-CloudSmith-Bundled.zip'

Step 2 — Verify the bundle

$manifestUrl = 'https://github.com/cloudsmith-cloud/cloudsmith-installer/releases/latest/download/cloudsmith-bundle.sha256'
$manifest    = Invoke-WebRequest -Uri $manifestUrl -UseBasicParsing | Select-Object -ExpandProperty Content
$expected    = ($manifest -split '\s+')[0]
$actual      = (Get-FileHash -Path 'Install-CloudSmith-Bundled.zip' -Algorithm SHA256).Hash
if ($actual -ne $expected) { throw "Hash mismatch — do not proceed" }
Write-Host "Hash verified: $actual"

Step 3 — Transfer to the management host

Transfer Install-CloudSmith-Bundled.zip and cloudsmith-bundle.sha256 to the management host using your standard secure file-transfer method (USB, SMB, SCP, etc.).

The bundle is approximately 1.2 GB. Allow time for the transfer before proceeding.

Step 4 — Extract and run the installer

On the management host in an elevated PowerShell 7 session:

Expand-Archive -Path 'Install-CloudSmith-Bundled.zip' -DestinationPath 'C:\CloudSmithInstall'

# Default install: VM static IP 192.168.100.10, VHDX at C:\ProgramData\CloudSmith\
& 'C:\CloudSmithInstall\Install-CloudSmith.ps1' -Mode Bundled

# Custom static IP and VHDX path
& 'C:\CloudSmithInstall\Install-CloudSmith.ps1' -Mode Bundled `
    -VmIp '10.10.50.20' `
    -VhdxPath 'D:\Hyper-V\cloudsmith-docker.vhdx'

The install steps are identical to Online mode. No internet access is required after extraction. The installer loads images from the bundle rather than pulling from GHCR.

Installation takes 5–10 minutes. A progress bar tracks each phase.

Step 5 — Verify the install

# Confirm the VM is running
Get-VM -Name 'cloudsmith-docker' | Select-Object Name, State, Status

# Run the CloudSmith diagnostic helper
Invoke-CloudSmithDiag

Expected output: all six containers showing status Up — cloudsmith-api, cloudsmith-portal, cloudsmith-postgres, cloudsmith-prometheus, cloudsmith-loki, cloudsmith-otel.

Step 6 — Open the portal

Navigate to https://<management-host-fqdn> (or the static IP you configured, default https://192.168.100.10). On first access, CloudSmith redirects you to the first-run setup wizard.

See Getting started — first-run walkthrough for the complete post-install sequence including wizard completion, cluster registration, and Relay deployment.

Installer parameters

Parameter	Default	Description
`-Mode`	`Online`	Must be `Bundled` for this mode
`-VmIp`	`192.168.100.10`	Static IP address for the CloudSmith VM
`-VhdxPath`	`C:\ProgramData\CloudSmith\cloudsmith-docker.vhdx`	Destination path for the VHDX file
`-VmName`	`cloudsmith-docker`	Name of the Hyper-V VM
`-VmMemoryGB`	`4`	Startup RAM for the VM (dynamic memory; max 8 GB)
`-VmCpuCount`	`2`	vCPU count for the VM
`-SwitchName`	`cloudsmith-internal`	Name of the Hyper-V internal switch

Updating CloudSmith in an air-gapped environment

After the initial install, updates require downloading a new bundle on a connected machine, transferring it, and running the installer again with -Mode Bundled. The installer performs an in-place update of container images without reprovisioning the VM.

# Download the new bundle on a connected machine
Invoke-WebRequest -Uri 'https://github.com/cloudsmith-cloud/cloudsmith-installer/releases/download/v0.2.0/Install-CloudSmith-Bundled.zip' `
    -OutFile 'Install-CloudSmith-Bundled-v0.2.0.zip'

# After transfer, extract and run with -Update flag
Expand-Archive -Path 'Install-CloudSmith-Bundled-v0.2.0.zip' -DestinationPath 'C:\CloudSmithUpdate'
& 'C:\CloudSmithUpdate\Install-CloudSmith.ps1' -Mode Bundled -Update

Troubleshooting

Installer exits with “Bundle integrity check failed”. Re-download the bundle and verify the SHA-256 hash before transferring again. A partial transfer is the most common cause.

The VM is running but the portal is not reachable. Confirm the Windows Firewall rule exists: Get-NetFirewallRule -DisplayName 'CloudSmith Portal'. If absent, run Invoke-CloudSmithDiag -Fix to recreate it.

“Hyper-V is not available” error. Confirm the Hyper-V role is installed and, if the management host is a VM, that nested virtualization is enabled on the parent Hyper-V host.