Install CloudSmith — Appliance mode

Appliance mode imports a pre-built, cosign-signed VHDX that ships with Ubuntu 24.04, Docker CE, and all CloudSmith container images already loaded. The portal is reachable approximately 3 minutes after import completes. Use this mode for fully air-gapped sites or any environment where you want the fastest path to a running installation.

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 ~3–4 GB VHDX
• Port 443 inbound from operator workstations (import script creates the firewall rule)
• cosign available on the machine performing verification (optional but recommended — the import script performs this automatically if cosign is on PATH)

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

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

Step 1 — Download the appliance artifacts

Run the following on a machine with internet access:

$base = 'https://github.com/cloudsmith-cloud/cloudsmith-installer/releases/latest/download'
Invoke-WebRequest -Uri "$base/cloudsmith-appliance.vhdx"         -OutFile 'cloudsmith-appliance.vhdx'
Invoke-WebRequest -Uri "$base/cloudsmith-appliance.sha256"       -OutFile 'cloudsmith-appliance.sha256'
Invoke-WebRequest -Uri "$base/cloudsmith-appliance.sha256.sig"   -OutFile 'cloudsmith-appliance.sha256.sig'
Invoke-WebRequest -Uri "$base/Import-CloudSmithAppliance.ps1"    -OutFile 'Import-CloudSmithAppliance.ps1'
Invoke-WebRequest -Uri "$base/cloudsmith-cosign.pub"             -OutFile 'cloudsmith-cosign.pub'

Step 2 — Verify integrity and authenticity

Before transferring, verify the VHDX has not been tampered with or corrupted.

# Step 2a — Integrity: SHA-256 hash check
$manifest = Get-Content 'cloudsmith-appliance.sha256'
$expected = ($manifest -split '\s+')[0]
$actual   = (Get-FileHash -Path 'cloudsmith-appliance.vhdx' -Algorithm SHA256).Hash
if ($actual -ne $expected) { throw "VHDX hash mismatch — do not import" }
Write-Host "Integrity verified: $actual"

# Step 2b — Authenticity: cosign signature verification of the manifest
cosign verify-blob `
    --key 'cloudsmith-cosign.pub' `
    --signature 'cloudsmith-appliance.sha256.sig' `
    'cloudsmith-appliance.sha256'

Warning: Do not import the VHDX before completing both verification steps. A signature failure means the manifest may have been replaced. Treat any verification failure as a security incident.

Step 3 — Transfer to the management host

Transfer all five files to the management host:

• cloudsmith-appliance.vhdx (~3–4 GB)
• cloudsmith-appliance.sha256
• cloudsmith-appliance.sha256.sig
• Import-CloudSmithAppliance.ps1
• cloudsmith-cosign.pub

Step 4 — Import and start

On the management host in an elevated PowerShell 7 session:

# Default import: VHDX placed at C:\ProgramData\CloudSmith\, VM IP 192.168.100.10
& '.\Import-CloudSmithAppliance.ps1'

# Custom paths and IP
& '.\Import-CloudSmithAppliance.ps1' `
    -VhdxSourcePath 'D:\Transfer\cloudsmith-appliance.vhdx' `
    -VhdxDestPath   'D:\Hyper-V\cloudsmith-docker.vhdx' `
    -VmIp           '10.10.50.20'

Import-CloudSmithAppliance.ps1 performs the following automatically:

1. Re-verifies the SHA-256 hash of the VHDX.
2. Verifies the cosign signature if cosign is on PATH (skips with a warning if not found).
3. Copies the VHDX to the destination path.
4. Creates a Hyper-V Generation 2 VM named cloudsmith-docker with the VHDX attached.
5. Configures the VM: 4 GB RAM (dynamic, max 8 GB), 2 vCPU, static IP, auto-start on host boot.
6. Creates the Hyper-V internal switch cloudsmith-internal.
7. Creates a Windows Firewall inbound rule forwarding port 443 to the VM’s static IP.
8. Starts the VM.

No internet access is required.

Step 5 — Wait for first boot

The appliance VM boots and the CloudSmith Docker Compose stack starts automatically. Portal reachability takes approximately 2–4 minutes.

$ip = '192.168.100.10'   # or your -VmIp value
do {
    Start-Sleep -Seconds 10
    $result = Test-NetConnection -ComputerName $ip -Port 443 -InformationLevel Quiet -WarningAction SilentlyContinue
    Write-Host "Waiting for portal... $(Get-Date -Format 'HH:mm:ss')"
} until ($result)
Write-Host "Portal is up. Navigate to https://$ip"

Step 6 — Open the portal

Navigate to https://<management-host-fqdn> (or the static IP, 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.

Import script parameters

Troubleshooting

“VHDX hash mismatch” during import. The VHDX was corrupted or partially transferred. Re-download the file from the GitHub release page and verify the hash before transferring again.

Cosign verification fails. Do not proceed. The manifest signature is invalid. Re-download all appliance artifacts from the official release page. If the problem persists, contact support.

Portal is not reachable after 5 minutes. SSH into the VM (ssh cloudsmith@<vm-ip>) and check container status:

docker compose -f /opt/cloudsmith/docker-compose.yml ps

All six containers should show status Up. If any container is restarting, check its logs: docker compose -f /opt/cloudsmith/docker-compose.yml logs <container-name>.

The VM powers on but no network connection from the host. Confirm the Hyper-V internal switch cloudsmith-internal exists: Get-VMSwitch -Name 'cloudsmith-internal'. If absent, create it manually:

New-VMSwitch -Name 'cloudsmith-internal' -SwitchType Internal
New-NetIPAddress -InterfaceAlias 'vEthernet (cloudsmith-internal)' -IPAddress '192.168.100.1' -PrefixLength 24