Runner prerequisites and Azure requirements

A CloudRadial AutomationAI runner is an execution agent you deploy into your own Azure subscription. Before you install one, you need the right Azure access, the right tooling on the machine, and the registration values the installer asks for. You can install the tooling automatically with the script for your platform, or follow the manual steps below. This article is written so you can go from a fresh machine to fully ready even if you have never used PowerShell or Azure before. It is intended for the technician performing the install.

In this article:

• Installing the Prerequisites Automatically
• Step 1: Confirming Your Azure Subscription and Role
• Step 2: Installing PowerShell 7
• Step 3: Installing the Az PowerShell Module
• Step 4: Installing the Azure CLI
• Step 5: Installing the Bicep CLI
• Step 6: Signing In With Connect-AzAccount
• Step 7: Gathering Your Runner Secret
• Verifying Your Machine Is Ready

Installing the Prerequisites Automatically

If you would rather not work through Steps 2 to 5 by hand, download the script for your platform. Each one installs PowerShell 7, the Azure CLI, the Bicep CLI, and the Az PowerShell modules the runner scripts use, skipping anything already present. They are safe to run more than once, and each ends with a table showing what is installed.

The scripts install local tooling only. They do not sign you in to Azure, do not create anything in your subscription, and do not deploy a runner.

The same three scripts also ship inside the runner setup package you download from the Runners page, in a prereqs folder beside the installer. You do not have to fetch them separately: when Deploy-Runner.ps1 runs its preflight and finds a missing tool, it names the script for your platform and, in an interactive session, offers to run it and then re-checks. Nothing is installed without your confirmation.

Important -> The Bicep CLI must be a standalone bicep on your PATH. The copy bundled with the Azure CLI (az bicep) is kept in a private folder that Az PowerShell cannot use, so a machine that has only that copy passes an older preflight and then fails part way into the deployment. The scripts above install the standalone binary.

Important -> The scripts cover the tooling only. Step 1 (your Azure subscription and role) and Step 7 (your runner secret) are still yours to do, and you still sign in with Connect-AzAccount as described in Step 6.

Windows

Save the script, then open PowerShell as Administrator, change to the folder you saved it in, and run:

powershell -ExecutionPolicy Bypass -File .\Install-RunnerPrereqs.ps1

Administrator rights are needed because PowerShell 7 and the Azure CLI install machine-wide. The script runs under the Windows PowerShell 5.1 that ships with Windows, so you do not need PowerShell 7 first. That is the point of it.

Note: Windows marks files downloaded from the internet as blocked. The -ExecutionPolicy Bypass above handles that for this one run. To clear the mark permanently instead, run Unblock-File .\Install-RunnerPrereqs.ps1 first.

Note: The script needs winget, the Windows Package Manager, which is included with current versions of Windows 10 and 11. If it is missing, the script tells you to install App Installer from the Microsoft Store and stops.

macOS

Save the script, then in Terminal change to the folder you saved it in and run:

chmod +x ./install-runner-prereqs-macos.sh
./install-runner-prereqs-macos.sh

The script uses Homebrew. If Homebrew is not installed it offers to install it for you. Installing the Bicep CLI uses sudo, so you are prompted for your password.

Linux

Save the script, then in your terminal change to the folder you saved it in and run:

chmod +x ./install-runner-prereqs-linux.sh
./install-runner-prereqs-linux.sh

Debian and Ubuntu (apt) and RHEL, CentOS Stream, and Fedora (dnf) are supported. Most steps use sudo, so you are prompted for your password.

Note: On an arm64 (aarch64) machine the script installs PowerShell 7 from Microsoft's official binary archive rather than the package repository, which publishes PowerShell for x86_64 only. There is nothing extra for you to do; the Azure CLI and the Bicep CLI both ship arm64 builds.

Note: Add --skip-az-modules on macOS or Linux, or -SkipAzModules on Windows, to install the command-line tools and leave the Az PowerShell modules out. The runner installer installs the Az submodules it needs on its first run anyway.

If a script cannot run in your environment, or you prefer to install each tool yourself, work through the steps below instead.

Step 1: Confirming Your Azure Subscription and Role

Why are we doing this? The runner deploys into an Azure subscription you own, and the installer both creates resources and grants the runner's managed identity its least-privilege roles. The account you run it as needs permission to create resources and role assignments.

Use one of the following on the subscription:

• Owner, or
• Contributor plus User Access Administrator

The installer also registers any resource providers the deployment needs (Microsoft.App, Microsoft.Web, Microsoft.Network, Microsoft.Storage, Microsoft.KeyVault, Microsoft.CognitiveServices, Microsoft.Insights, and Microsoft.OperationalInsights), which requires a subscription-scoped role.

Important -> A resource-group-scoped role is not enough. If your account cannot register a provider, the installer stops early and prints the exact one-time command for a subscription admin to run.

Not sure what role you have? In the Azure portal, go to Subscriptions, select your subscription, open Access control (IAM), and choose View my access. Your assigned roles are listed there.

Step 2: Installing PowerShell 7

Why are we doing this? The installer and the Az module both require PowerShell 7 or later. On Windows, the version that ships with the operating system is Windows PowerShell 5.1, so unless someone installed PowerShell 7 separately, you probably do not have it yet. macOS and most Linux distributions do not ship with PowerShell at all.

First, check what you have. Open a terminal and run:

$PSVersionTable.PSVersion

If the Major number is 7 or higher, you already have PowerShell 7. Skip to Step 3. If it shows 5.1, or the command is not recognized, install it using one of the options below.

Option A, Windows (winget). Recommended on Windows 10 and 11:

winget install --exact --id Microsoft.PowerShell

Option B, macOS (Homebrew). Microsoft supports PowerShell on macOS 14 and later:

brew install powershell

PowerShell is a regular Homebrew formula, so do not add --cask. If Homebrew reports that PowerShell is installed but not linked, run brew link powershell. The formula is maintained by the Homebrew community rather than by Microsoft. If you would rather use a Microsoft-built package, download the .pkg from the PowerShell releases page instead.

Option C, Linux (Debian and Ubuntu). Microsoft publishes a separate repository per distribution, so the path below picks the right one from /etc/os-release rather than assuming Ubuntu:

sudo apt-get update
sudo apt-get install -y wget apt-transport-https software-properties-common
source /etc/os-release
wget -q https://packages.microsoft.com/config/$ID/$VERSION_ID/packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb
rm packages-microsoft-prod.deb
sudo apt-get update
sudo apt-get install -y powershell

$ID resolves to debian on Debian and ubuntu on Ubuntu. If wget returns a 404, Microsoft does not publish a repository for that exact release — check the published list and use the nearest supported version, or use the automatic installer above, which handles this for you.

Option D, Linux (RHEL and Fedora). Adjust the repository URL to match your major version:

sudo rpm --import https://packages.microsoft.com/keys/microsoft.asc
sudo dnf install -y https://packages.microsoft.com/config/rhel/9.0/packages-microsoft-prod.rpm
sudo dnf install -y powershell

Note: The Microsoft package repository publishes the powershell package for x86_64 only. On an arm64 (aarch64) machine, Options C and D fail during dependency resolution; install PowerShell from the binary archive for Linux instead, or run the Linux script above, which does that for you.

After it installs, close and reopen your terminal, then launch PowerShell 7 by running:

pwsh

Confirm the version:

$PSVersionTable.PSVersion

Important -> On Windows, PowerShell 7 installs alongside Windows PowerShell 5.1 rather than replacing it. Run every remaining step, including the Az module install and the runner install, from the PowerShell 7 window you launched with pwsh.

Step 3: Installing the Az PowerShell Module

Why are we doing this? The installer is a PowerShell script that drives Az PowerShell cmdlets, so the modules have to be present before it can deploy.

The runner install and upgrade scripts check for the submodules they use and install any that are missing to your user profile on first run, without admin rights. So this step is optional. Do it now if you would rather get the download out of the way before the install, or if the machine has no access to the PowerShell Gallery at install time.

In your PowerShell 7 window, first check whether the modules are already there:

Get-Module Az -ListAvailable

If nothing is returned, install once for your user:

Install-Module Az -Scope CurrentUser

The install and upgrade scripts use these submodules:

• Az.Accounts
• Az.Resources
• Az.KeyVault
• Az.Websites
• Az.CognitiveServices

The full Az module is large. To install only what the runner scripts need, install those five by name instead:

Install-Module Az.Accounts, Az.Resources, Az.KeyVault, Az.Websites, Az.CognitiveServices -Scope CurrentUser

Note: If you are prompted to trust the PSGallery repository, answer Yes. The install can take several minutes.

Step 4: Installing the Azure CLI

Why are we doing this? The installer preflights the Azure CLI in addition to the Az PowerShell module, signs it in for you, and prints follow-up az commands for tasks such as checking AI model quota and re-locking the runner Key Vault. It has to be callable as az from your terminal. The Azure CLI and the Az PowerShell module are two separate tools from two separate installs, and having one does not give you the other. Step 3 passes cleanly on a machine that does not have the Azure CLI.

First, check whether it is already present. Run this from the PowerShell 7 window you opened in Step 2:

az version

Use Azure CLI 2.20.0 or later, the first version with built-in Bicep support. If you get a version number at or above that, skip to Step 5. If az is not recognized as a command, install it using the option for your platform below.

Option A, Windows (winget):

winget install --exact --id Microsoft.AzureCLI

Option B, macOS (Homebrew). Requires macOS 13 or higher:

brew update && brew install azure-cli

Option C, Linux (Debian and Ubuntu):

curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash

Option D, Linux (RHEL, CentOS Stream, and Fedora). Adjust the repository URL to match your major version:

sudo rpm --import https://packages.microsoft.com/keys/microsoft.asc
sudo dnf install -y https://packages.microsoft.com/config/rhel/9.0/packages-microsoft-prod.rpm
sudo dnf install azure-cli

After it installs, close and reopen your terminal, then confirm:

az version

Note: If az version returns something older than 2.20.0, upgrade it in place with az upgrade rather than reinstalling.

Important -> Installing the Azure CLI does not sign you in to anything, and it does not affect the Az PowerShell sign-in you will do in Step 6.

Step 5: Installing the Bicep CLI

Why are we doing this? The runner is deployed from a Bicep template rather than a plain ARM template. Az PowerShell compiles that template on your machine, so the Bicep CLI has to be installed and callable as bicep from your terminal.

First, check whether it is already present. Run this from the same PowerShell 7 window:

bicep --version

If you get a version number, skip to Step 6. If bicep is not recognized as a command, install it using the option for your platform below.

Option A, Windows (winget):

winget install --exact --id Microsoft.Bicep

Option B, macOS. Download Microsoft's published binary. Use bicep-osx-arm64 on Apple silicon, or bicep-osx-x64 on an Intel Mac:

curl -Lo bicep https://github.com/Azure/bicep/releases/latest/download/bicep-osx-arm64
chmod +x ./bicep
sudo mv ./bicep /usr/local/bin/bicep

Homebrew can also install Bicep from the azure/bicep tap, but current Homebrew versions refuse to load formulas from third-party taps until you run brew trust azure/bicep first. The download above avoids that extra step.

Option C, Linux:

curl -Lo bicep https://github.com/Azure/bicep/releases/latest/download/bicep-linux-x64
chmod +x ./bicep
sudo mv ./bicep /usr/local/bin/bicep

On Arm64 machines use bicep-linux-arm64, and on Alpine and other musl-based distributions use bicep-linux-musl-x64, in place of bicep-linux-x64.

After it installs, close and reopen your terminal, then confirm:

bicep --version

Important -> The Azure CLI's own copy of Bicep is not a substitute for the install above. The Azure CLI installs a private copy that it deliberately keeps out of your PATH and only reaches through az bicep commands. The runner deploys through Az PowerShell, which looks only for a standalone bicep on your PATH and cannot use the Azure CLI's copy. The installer's startup check accepts either one, so a machine that has only az bicep passes that check and then fails later, part way through the deployment. Confirm with bicep --version, not az bicep version.

Note: If you already ran az bicep install at some point, you may have both copies on the machine. That is fine and they do not conflict.

Step 6: Signing In With Connect-AzAccount

Why are we doing this? Az PowerShell keeps its own sign-in state, separate from the Azure CLI, so the installer can only see the session Az PowerShell itself is signed into.

Running az login does not authenticate Az PowerShell. Sign in with:

Connect-AzAccount

If your subscription lives in a specific Entra tenant, sign in to that tenant:

Connect-AzAccount -TenantId <tenant-guid>

A browser window opens for you to sign in. After you complete sign-in and any multi-factor authentication prompt, return to the terminal.

The installer validates this on startup. In an interactive session it launches Connect-AzAccount for you; otherwise it prints exact remediation and stops.

Note: You do not have to choose a subscription in advance. The -SubscriptionId parameter is optional, and when you omit it the installer lists the subscriptions your login can access and lets you pick one. Pass it explicitly for unattended runs; a non-interactive session with no -SubscriptionId stops rather than guessing.

Note: If the command is not recognized, on Windows you are almost certainly in a Windows PowerShell 5.1 window. Close it, launch PowerShell 7 with pwsh, and try again.

Important -> A successful sign-in does not mean the machine is ready. Connect-AzAccount authenticates the Az PowerShell module and nothing else. It succeeds even when the Azure CLI and Bicep CLI from Steps 4 and 5 are missing entirely, and the install will then fail later in the process. Before you move on, confirm that az version and bicep --version both return a version number.

Step 7: Gathering Your Runner Secret

Why are we doing this? A runner is registered in AutomationAI before you install it in Azure, and registration mints the one value you have to capture yourself.

Registration produces one value you need to record:

• A runner secret (RUNNER_SECRET), a one-time secret the runner uses to sign its check-ins

REQUIRED: The runner secret is shown only once, at registration. Copy it into your password manager before you leave the registration dialog. The installer prompts you to paste the secret when you run it, so it is never written to disk.

The setup package you download embeds the runner identity for you. For how a runner is registered in the app, see Registering and managing runners.

Verifying Your Machine Is Ready

Before you move on, confirm all seven from the PowerShell 7 window you will run the installer in. Each check is independent, and passing one does not confirm the others. If you used the automatic installer, it prints the same checks for Steps 2 to 5 when it finishes.

Once all seven are confirmed, the machine is ready and you can register the runner and run the installer. Next: Installing a runner in your Azure subscription.

If you are still having trouble, we're here to help! Submit a ticket here for assistance, and don't forget to check our status page to ensure there are no outages in your area.