System requirements

This page covers requirements for both deployment models. Read the section that matches your target environment.

Model A — On-premises standalone

Windows Server management host

The management host is the Windows Server 2025 machine that runs the CloudSmith control plane. It is not a node in the managed cluster — it is a dedicated or shared management machine that has network access to the clusters you want to manage.

Operating system:

• Windows Server 2025 (Standard or Datacenter edition)
• Hyper-V role installed and running (Install-WindowsFeature -Name Hyper-V -IncludeManagementTools)
• PowerShell 7.4 or later

Hardware minimums:

The 10 GB RAM minimum accounts for 8 GB allocated to CloudSmith services inside the Linux VM plus approximately 2 GB of Linux guest OS overhead. The installer enforces this minimum and will not proceed if less than 10 GB is available.

Nested virtualization (VM-hosted management servers):

If the management host is itself a Hyper-V VM — for example, a management VM running on the same cluster you are about to manage — nested virtualization must be enabled on the parent host before running the installer:

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

The installer detects the absence of nested virtualization and stops with an error. Do not bypass this check in production.

Linux guest VM (provisioned by the installer)

The installer creates a Hyper-V Generation 2 VM named cloudsmith-docker running Ubuntu 24.04 LTS. You do not provision this VM manually — these specs are provided for capacity planning.

If C:\ProgramData is on a small OS disk, pass --vhdx-path to specify an alternate location.

Network and firewall

Inbound (to management host):

Only port 443 needs an inbound firewall rule. The installer creates this rule automatically. All other communication is outbound from the runner or internal to the Docker Compose network.

Outbound (from management host / runner):

Outbound (from Linux VM — Online mode only):

Bundled and Appliance modes do not require outbound internet access for the initial install. Post-install update checks require ghcr.io access unless you mirror images internally.

Model B — Azure PaaS

Azure subscription

No Entra ID / Azure AD roles are required for the initial deployment. Entra ID SSO is optional and configured post-install. See Prerequisites for the full RBAC breakdown.

Local tooling

Install the following on the workstation from which you run azd up. Windows, macOS, and Linux are all supported.

# Verify versions before proceeding
az version
azd version
$PSVersionTable.PSVersion

Azure service availability

The Phase IV Bicep pack provisions the following Azure resources. Confirm each is available in your chosen region before running azd up:

Note: Azure SignalR Service, Azure Service Bus, Azure Front Door, VNet integration, and private endpoints are not provisioned by the current Bicep pack — they are part of the production-hardening roadmap.

Heads-up: The resource set above is the current MVP. SKU defaults and the exact parameter surface may evolve; pin to a specific cloudsmith-installer release tag when automating.

Entra ID SSO (optional — post-install)

Entra ID app registrations are not required to deploy CloudSmith. The platform starts with a first-run setup wizard that creates a local administrator account. You can add Entra ID (or another identity provider) after the platform is running, under Platform Management → Identity Providers.

If you plan to configure Entra SSO post-install, the person creating the app registration needs Application Administrator or Cloud Application Administrator in Entra ID. See Identity configuration for setup steps.