> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/harness-platform/use-harness-platform/references/harness-cloud-vm-images.md). # Harness Cloud VM Images Harness provides preconfigured virtual machine (VM) images to run your pipeline stages in Harness Cloud. These images come with common build tools and dependencies preinstalled, so you can focus on building and testing your code without worrying about setup. Every stage runs on a fresh VM, ensuring clean, isolated executions. For a full list of the tools included in each image, visit the [Harness Cloud VM image repository](https://github.com/wings-software/harness-docs/tree/main/harness-cloud). ### Cloud VM Images #### Available VM Images Image Tags Below is a list of the images used by Harness Cloud. You can either: 1. Use a **moving image tag** (for example, `ubuntu-latest`) to automatically receive updates, or 2. **Pin to a specific image version** to maximize build reproducibility. **VM Images**: | Virtual machine image | Image label | Notes | Rollout Status | | ---------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | -------------- | | [Linux AMD Ubuntu 22.04](https://github.com/wings-software/harness-docs/blob/main/harness-cloud/Linux-amd/Ubuntu2204-Readme.md) | `ubuntu-latest` or `ubuntu-22.04` | Default Linux image for Linux AMD | GA | | [Linux AMD Ubuntu 24.04](https://github.com/wings-software/harness-docs/blob/main/harness-cloud/Linux-amd/Ubuntu2404-Readme.md) | `ubuntu-24.04` | Default Linux image for Linux AMD | Beta | | [Linux ARM Ubuntu 22.04](https://github.com/wings-software/harness-docs/blob/main/harness-cloud/Linux-arm/Ubuntu2204-Readme.md) | `ubuntu-latest` or `ubuntu-22.04` | Default Linux image for Linux ARM | GA | | [Linux ARM Ubuntu 24.04](https://github.com/wings-software/harness-docs/blob/main/harness-cloud/Linux-arm/Ubuntu2404-Readme.md) | `ubuntu-24.04` | Default Linux image for Linux ARM | GA | | [macOS 14 (Sonoma)](https://github.com/wings-software/harness-docs/blob/main/harness-cloud/macos-14-sonoma-xcode-15.2-default-Readme.md) | `mac-latest`, `mac-sonoma`, or `macos_sonoma_xcode_16.3` | macOS 14 (Sonoma) with Xcode 15.2 (default), 16.3, 16.1, 15.1 | GA | | [macOS 15 (Sequoia)](https://github.com/wings-software/harness-docs/blob/main/harness-cloud/macos-15-xcode-26.4-Readme.md) | `macos_sequoia`, `macos_sequoia_xcode_16.4`, or `macos-sequoia-xcode-26.2` | macOS 15 (Sequoia) with Xcode 16.4 (default), 16.3, 26.0, 26.1, 26.2, 26.3, 26.4 | BETA | | [macOS 26 (Tahoe)](https://github.com/wings-software/harness-docs/blob/main/harness-cloud/macos-26-tahoe-27.0-Beta.5-Readme.md) | `macos-tahoe` | macOS 26 (Tahoe) with Xcode 26.4.1 (default), 26.3, 26.5, 27.0 (Beta 5) | BETA | | [Windows Server 2022](https://github.com/wings-software/harness-docs/blob/main/harness-cloud/Windows2022-Readme.md) | `windows-latest` or `windows-2022` | Latest Windows 2022 Server Image | GA | | [Windows Server 2025](https://github.com/wings-software/harness-docs/blob/main/harness-cloud/Windows2025-Readme.md) | `windows-2025` | Latest Windows 2025 Server Image | BETA | {% hint style="info" %} **Beta vs GA Images:** * **Beta images** are preview releases for testing before general availability. They are not covered by production SLA and require a feature flag to access (`CI_ENABLE_HOSTED_BETA_IMAGES` for Linux, `CI_ENABLE_MAC_HOSTED_BETA_IMAGES` for macOS). * **GA (General Availability) images** are production-ready and covered by your Harness SLA. Harness supports the latest 2 major versions of each operating system. **Feature Flag Behavior:** * When `CI_ENABLE_HOSTED_BETA_IMAGES` is enabled, `ubuntu-latest` points to the Beta version instead of the GA version. * When `CI_ENABLE_MAC_HOSTED_BETA_IMAGES` is enabled, `mac-latest` points to the Beta macOS version. **Note:** Minor OS upgrades for GA images also go through the beta image process before being promoted to GA. {% endhint %} #### Choosing an image version Harness VM images use a versioning system to help you balance between getting the latest updates and maintaining build stability. To select an the image tag to use, simply provide it in the `imageName` property of the cloud infrastructure `runtime` section. ```yaml runtime: type: Cloud spec: size: xxlarge imageName: ubuntu-latest # specify image tag ``` **Best Practice: Pin Image Versions in Production** Since using the `latest` tag may contain breaking changes or updated tool versions that could affect your build. Always test thoroughly before updating production pipelines. To ensure stable production deployments while still benefiting from the latest updates, we recommend the following approach: 1. **Test in Dev**: **Use latest in non-prod** pipelines and confirm everything works with the new image. 2. **Update Prod**: Switch production pipelines to the new image, and **pin image name to a specific version**. To simplify the rollout and management of image tag updates across environments, we recommend defining the image name as [a variable at the Account, Org, Project, or Pipeline level](/harness-platform/use-harness-platform/variables-and-expressions/add-a-variable.md) in Harness. This will ensure you can pin your pipeline to a new version globally. {% hint style="warning" %} The `latest` image may contain breaking changes or updated tool versions that could affect your build. Always test thoroughly before updating production pipelines. {% endhint %} #### Image Updates and Maintenance Harness regularly updates VM images to include: * Security patches and OS updates. * Latest versions of popular development tools. * Runtime updates (Node.js, Python, Java, etc.). * New tools and utilities based on community feedback. ### Image Lifecycle This section outlines Harness's policy for managing VM image releases, versioning, and deprecation in Harness Cloud. #### Deprecation Policy **N-1 Support Model** Harness supports the **latest 2 major versions of each operating system** at any given time. When a new GA version is released, deprecation of the oldest supported GA version begins. Harness provides Ubuntu LTS (Long Term Support) images for both AMD64 and ARM64 architectures. **Example:** When a new Ubuntu major version becomes LTS → Harness publishes a new image → Ubuntu 24.04 (N-1) remains available → Ubuntu 22.04 (the N-2 maintained LTS image) deprecation process begins. **Deprecation Process** When an image is deprecated, we follow this timeline to minimize disruption: * **Announcement** — Public notice via RSS feed with the target deprecation date. Minimum notice: 60 days for Linux, 30 days for macOS. * **Migration period** — Time to update your pipelines to use supported images. * **Removal** — Image is no longer available after the deprecation date. {% hint style="info" %} macOS has a shorter deprecation notice period (30 days) due to Apple's support policies, which require faster transitions when a macOS version reaches end-of-life. {% endhint %} #### Xcode Versions Availability Harness provides three Xcode versions pre-installed on each macOS image: 1. **Base version** - The Xcode version that ships with the macOS release (e.g., Xcode 16.0 comes with macOS 15). This only updates when we upgrade to a new major macOS version. 2. **Latest stable version** - The newest production Xcode release (e.g., Xcode 16.4). This updates regularly as Apple releases new stable versions. 3. **Latest beta version** — The current Xcode beta or preview release (e.g., Xcode 17.0 beta). If Apple promotes the beta to GA and no new beta is available, this slot contains the newly released stable version, resulting in two stable versions on the image (e.g., Xcode 16.4 and 17.0). {% hint style="info" %} We aim to make new Xcode beta versions available within approximately three business days of Apple’s release. {% endhint %} {% hint style="info" %} **SWITCHING XCODE VERSIONS** The latest stable version is the default. To list all available versions: ```bash ls /Applications | grep Xcode ``` To switch versions, run this before your build commands: ```bash sudo xcode-select -s /Applications/Xcode_.app ``` Replace `` with your desired version (e.g., `16.0`, `16.4`). {% endhint %} ### Pre-installed Software Version Management #### Using preinstalled software Harness-hosted VM images include a comprehensive set of preinstalled software packages, development tools, and runtime environments. This eliminates the need to install common dependencies during your pipeline execution, significantly reducing build times. **You can customize the Harness Cloud build environment.** In your pipelines, you can [select specific versions of pre-installed tools](#specify-versions), ensure that a step [uses a specific version every time](#lock-versions-or-install-additional-tools), or [install additional tools and versions](#lock-versions-or-install-additional-tools) that aren't preinstalled on the Harness Cloud images. You can run these steps on the host machine or as separate Docker containers. #### Specify versions If a Harness Cloud image has multiple versions of a tool pre-installed, you can specify the version that you want to use in a step's **Command**. For example, with the Harness Cloud macOS build infrastructure, you could use the following command in a [Run step](/continuous-integration/use-harness-ci/use-harness-ci/run-step-settings.md) to select an Xcode version: ``` sudo xcode-select -switch /Applications/Xcode_15.1.0.app ``` {% hint style="warning" %} Harness Cloud machine images can change. If your pipeline relies on a specific version of a software, tool, or environment, make sure you [lock versions](#lock-versions-or-install-additional-tools) to prevent your pipeline from failing when the image changes. {% endhint %} #### Lock versions or install additional tools If your build requires a specific version of a tool or you need to use a version/tool that isn't pre-installed on the [Harness Cloud image](#platforms-and-image-specifications), you must add a step (such as a [Run step](/continuous-integration/use-harness-ci/use-harness-ci/run-step-settings.md) or [Plugin step](/continuous-integration/use-harness-ci/use-harness-ci/use-drone-plugins/run-a-drone-plugin-in-ci.md)) to install the version/tool directly on the build machine or run a Docker image that has the required version/tool. When installing additional tools, run `apt-get update` before installing new software that might not be in the packages list.
Example: Use an Action step to setup Java In the following YAML example, an [Action step](/continuous-integration/use-harness-ci/use-harness-ci/use-drone-plugins/ci-github-action-step.md) runs the `actions/setup-java` GitHub Action to install a Java version, and then the **Run** step confirms the Java version. ```yaml steps: - step: identifier: install_java name: install java version 17 type: Action spec: uses: actions/setup-java@v3 with: distribution: 'temurin' java-version: '16' - step: identifier: java_ver_check name: java version check type: Run spec: shell: Bash command: | JAVA_VER=$(java -version 2>&1 | head -1 | cut -d'"' -f2 | sed '/^1\./s///' | cut -d'.' -f1) if [[ $JAVA_VER == 16 ]]; then echo successfully installed $JAVA_VER else exit 1 fi ``` {% hint style="info" %} You can also use the [Bitrise step](/continuous-integration/use-harness-ci/use-harness-ci/use-drone-plugins/ci-bitrise-plugin.md) to run Bitrise Workflow Steps in your CI pipelines. {% endhint %}
Example: Use a Docker image The following YAML example demonstrates how a **Run** step can use a Docker image to leverage tools that are available on the image without having to install them on the build machine. ```yaml - stage: name: Print welcome message identifier: welcome_message type: CI spec: cloneCodebase: true platform: ## Platform properties describe the target machine required by this stage. os: Linux arch: Amd64 runtime: type: Cloud ## This build runs on Harness-provided infrastructure. spec: {} execution: steps: - step: type: Run name: Welcome identifier: Welcome spec: connectorRef: my_docker_hub ## Specify a Docker connector to pull an image from Docker. image: alpine ## If no image is specified, the step runs on the host machine. shell: Sh command: Echo "Welcome to Harness CI" ```
{% hint style="info" %} **MISSING TOOLS AND ENVIRONMENT CONFIGURATION** Some tools referenced in Harness Cloud VM images might not be preinstalled, or they might not be on `PATH` by default. If a tool isn’t available, install it in a step or run your step inside a container image that already includes it. If a tool is present but not auto-configured, **set the required environment variables** (for example, update `PATH`, set `JAVA_HOME`, etc.). **Install on-demand (example: Node via NVM)** ```yaml - step: type: Action name: Setup Node Using NVM identifier: Setup_Node_Using_NVM spec: uses: dcodeIO/setup-node-nvm@master with: node-version: 20.12.2 ``` **Alternative: run inside a container with all required dependencies** ```yaml - step: type: Run name: Build with custom image identifier: build_with_custom_image spec: connectorRef: my_docker_hub image: YourCustomImage:tag shell: Bash command: your_build_command ``` {% endhint %} #### Verifying software versions To see the exact versions of preinstalled software on each image, check the detailed specifications in the [Harness Cloud documentation](https://github.com/wings-software/harness-docs/tree/main/harness-cloud). Each image type has its own README file with current software versions and installation details. Alternatively, if you prefer verifying software versions within your pipeline, refer to the following sample: ```yaml pipeline: name: Check Software Version Pipeline identifier: check_software_version_pipeline stages: - stage: name: Check Software Version identifier: check_software_version type: Custom spec: execution: steps: - step: identifier: run_version_check_script name: Check Software Versions type: ShellScript timeout: 10m spec: shell: Bash source: type: Inline spec: script: |- echo "===== Software Version Check =====" echo # Node.js and NPM echo "Node.js Version:" node --version || echo "Node.js not installed" echo echo "NPM Version:" npm --version || echo "NPM not installed" echo # Python echo "Python Version:" python --version || echo "Python not installed" python3 --version || echo "Python3 not installed" echo # Java echo "Java Version:" java -version || echo "Java not installed" echo # Docker echo "Docker Version:" docker --version || echo "Docker not installed" echo # Git echo "Git Version:" git --version || echo "Git not installed" echo # Maven echo "Maven Version:" mvn --version || echo "Maven not installed" echo # Gradle echo "Gradle Version:" gradle --version || echo "Gradle not installed" echo # Go echo "Go Version:" go version || echo "Go not installed" echo # Ruby echo "Ruby Version:" ruby --version || echo "Ruby not installed" echo # Operating System echo "Operating System:" uname -a || echo "uname command not available" cat /etc/os-release 2>/dev/null || echo "OS release info not available" echo echo "===== Version Check Complete =====" rollbackSteps: [] description: This pipeline shows if specific tools are installed on the VM and their images (if available). projectIdentifier: YOUR_PROJECT_IDENTIFIER orgIdentifier: YOUR_ORG_IDENTIFIER ``` ### Installing additional software While Harness VM images come with many tools preinstalled, you may need to install additional software specific to your project. #### Using package managers You can install additional packages using the system package manager during your pipeline: ```yaml steps: - step: type: Run name: Install Dependencies identifier: install_deps spec: command: | # Ubuntu/Debian sudo apt-get update sudo apt-get install -y your-package-name # CentOS/RHEL sudo yum install -y your-package-name # macOS brew install your-package-name ``` #### Installing language-specific packages Install packages using language-specific package managers: ```yaml steps: - step: type: Run name: Install Language Packages identifier: install_lang_packages spec: command: | # Node.js packages npm install -g your-package # Python packages pip3 install your-package # Ruby gems gem install your-gem # Go modules go install your-module ``` #### Performance considerations Installing software during pipeline execution increases build time. Consider these approaches for better performance: * Use preinstalled software when possible * Cache dependencies between builds when available * Consider creating custom Docker images for complex dependencies * Use specific tool versions that are already preinstalled ### Bring Your Own Image (BYOI) Harness supports **Bring Your Own Image (BYOI)**, allowing you to use Harness Cloud with your own **custom images**. Create VM images with your tools and dependencies pre-installed for faster, more consistent CI builds. #### Linux BYOI For Linux builds, you can create custom images using Packer with the BYOI builder plugin. This allows you to: * Pre-install development tools, SDKs, and dependencies * Configure environment settings and files * Build on top of Ubuntu base images or your existing BYOI images Linux BYOI images are built with the Harness BYOI builder plugin and stored in Harness-managed storage. Unlike macOS BYOI, Linux BYOI does not use an external registry pull model. Supplying a custom image connector (for example, the [Override Image Connector](/harness-platform/use-harness-platform/connectors/artifact-repositories/connect-to-harness-container-image-registry-using-docker-connector.md) stage infrastructure setting) is not supported for the Linux BYOI VM image, so you cannot host the Linux BYOI image in your own registry. Reference the image by `imageName:imageVersion`. Go to [Harness Cloud BYOI](/harness-platform/use-harness-platform/references/harness-cloud-byoi.md) to review detailed instructions for creating and using custom Linux images. #### Windows BYOI For Windows builds, you can create custom images using Packer with the BYOI builder plugin on Windows Server 2022 or 2025 (amd64 only). The same authoring and delivery model as Linux BYOI applies: * Windows BYOI images are built with the Harness BYOI builder plugin and stored in Harness-managed storage. * Windows BYOI does not use an external registry pull model. Supplying a custom image connector (for example, the [Override Image Connector](/harness-platform/use-harness-platform/connectors/artifact-repositories/connect-to-harness-container-image-registry-using-docker-connector.md) stage infrastructure setting) is not supported for the Windows BYOI VM image, so you cannot host the Windows BYOI image in your own registry. * Reference the image by `imageName:imageVersion`. {% hint style="info" %} The BYOI builder plugin accepts `windows-server/2019` as base images, but that version is not yet qualified to run as CI VMs on Harness Cloud. Use `windows-server/2022` or `windows-server/2025` for Windows BYOI images intended to run on Harness Cloud. {% endhint %} Go to [Harness Cloud BYOI](/harness-platform/use-harness-platform/references/harness-cloud-byoi.md) to review detailed instructions for creating and using custom Windows images. #### macOS BYOI macOS BYOI support is also available for custom macOS build environments. Unlike Linux and Windows BYOI, which use Packer to build custom VM images stored by Harness, macOS BYOI uses an OCI registry pull model — you push a pre-configured image layer to an OCI-compatible registry, and Harness pulls it onto the macOS VM at build time. {% hint style="info" %} * Setting an image pull policy is currently not supported. However, by default, an image is never pulled if it already exists on the VM. * BYOI support requires the `CI_ENABLE_BYOI_HOSTED` feature flag. Contact Harness support to enable this feature. {% endhint %} **Best Practice**: Always retag your custom image with a new version whenever changes are made. This ensures Harness Cloud picks up the updated image during your build. #### Staying Informed Subscribe to the **Harness CI RSS feed** to receive notifications about: * Image deprecation announcements * New image releases **RSS Feed URL**: ### Support and Feedback For questions, issues, or feature requests related to Harness VM images, contact [Harness Support](https://support.harness.io). ### Related Resources * [Use Harness Cloud Build Infrastructure](/continuous-integration/use-harness-ci/use-harness-ci/set-up-build-infrastructure/use-harness-cloud-build-infrastructure.md) * [Harness Cloud BYOI (Bring Your Own Image)](/harness-platform/use-harness-platform/references/harness-cloud-byoi.md) * [Harness Cloud VM Image Repository](https://github.com/wings-software/harness-docs)