Installation

Installation

Prerequisites

Before installing az prototype, ensure the following tools are available:

Tool	Minimum Version	Required For	Install
Python	3.9+ (3.10-3.12 tested in CI)	Extension runtime	python.org
Azure CLI	2.50.0+	All commands	Install Azure CLI
GitHub CLI (gh)	2.30.0+	Copilot/GitHub Models auth, backlog push	cli.github.com
Terraform	1.14.0+	IaC generation and deployment (if --iac-tool terraform)	Terraform Install
Bicep	(bundled with Azure CLI)	IaC generation and deployment (if --iac-tool bicep)	Included with Azure CLI

The governor agent uses pre-computed neural embeddings for built-in policy retrieval. These are generated at build time and shipped with the wheel -- no extra install needed, works on all platforms including Windows 32-bit.

For custom policies (added to .prototype/policies/), TF-IDF is used by default. Non-Windows users who want neural-quality embeddings for custom policies can optionally install:

pip install sentence-transformers

Note: sentence-transformers requires torch, which has no 32-bit Windows wheels. This optional install is only for macOS/Linux or 64-bit Windows Python environments.

You also need access to at least one AI provider. See the AI Provider Setup section below.

Install from Wheel

Download the latest .whl file from the Releases page, then install it as an Azure CLI extension:

az extension add --source azext_prototype-0.2.1b6-py3-none-any.whl

If you have a previous version installed, remove it first (see Upgrade).

Verify Installation

az prototype --help

You should see the available subcommands: init, design, build, deploy, status, and backlog.

AI Provider Setup

The extension supports three AI providers. Configure one during az prototype init with --ai-provider.

Copilot (default)

Requires an active GitHub Copilot subscription (Individual, Business, or Enterprise). The extension authenticates through the GitHub CLI and validates your Copilot license during init. Default model: claude-sonnet-4.5.

See AI Providers for detailed setup.

GitHub Models

Requires a GitHub Personal Access Token with the models scope. Set up via gh auth login or by providing the token in your project secrets. Default model: gpt-4o.

See AI Providers for detailed setup.

Azure OpenAI

Requires an Azure OpenAI resource with a deployed model, plus the endpoint URL and API key. Configure the endpoint and deployment name during init or in prototype.yaml. Default model: gpt-4o.

# prototype.yaml
ai:
  provider: azure-openai
  azure_openai:
    endpoint: https://your-resource.openai.azure.com/
    deployment: gpt-4o

API keys are stored in prototype.secrets.yaml (git-ignored).

See AI Providers for detailed setup.

Upgrade

Remove the existing extension and install the new version:

az extension remove --name prototype
az extension add --source azext_prototype-<new-version>-py3-none-any.whl

Your project files (prototype.yaml, generated code) are not affected by extension upgrades.

Uninstall

az extension remove --name prototype

This removes the CLI extension only. Project directories and configuration files created by az prototype init remain on disk.