version unknown

azldev

microsoft@microsoft⭐ 5.4k stars· last commit 2d ago· 26 open issues

Read this before running azldev or editing azldev config, and whenever working in a repo that contains an azldev.toml file; do not guess azldev's commands or config. Explains how to use the azldev CLI to build a distro from TOML config, including the core concepts (components, overlays, distros, rendered specs, locks), running azldev (repo root or -C, plus the -q and -O json flags), the common commands, and where to go for each workflow. Triggers include azldev, comp build, comp render, comp upd

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

7.1/10
Verified
Oct 11, 2026

// RATINGS

⭐GitHub Stars
⭐⭐⭐⭐⭐ 5.4k on GitHubGitHub ↗

Very popular

🟢ProSkills ScoreAI Verified
7.1/10
📍

Not yet listed on ClawHub or SkillsMP

// README

An open-source Linux distribution built and optimized for Azure, with sources derived from Fedora Linux. Azure Linux provides a secured, reliable operating system for virtual machines, containers, and bare-metal platforms.

Azure Linux is built on a robust open-source foundation from the Fedora ecosystem and enhanced with Azure-specific innovations. This provides the familiarity of the RPM package ecosystem, while adding Azure-native security, compliance, and operational capabilities.

Key features of Azure Linux include: hardened security posture, an Azure-optimized kernel, supply chain security, native Azure integration, and a predictable lifecycle.

This branch holds the in-development sources for Azure Linux 4. For Azure Linux 3, see the 3.0 branch.

Getting started

The links below will help you get started with Azure Linux:

Product documentationhttps://aka.ms/azurelinux
Release informationGitHub Releases
File a bug / feedbackGitHub Issues
Ask a question / get helpSUPPORT.md
Get started as a distro developerDEVELOPING.md
Contribution guidelinesCONTRIBUTING.md
Report a security issueSECURITY.md

Using Azure Linux

Note: Azure Linux 4 is still in development

To try Azure Linux in an Azure VM, please visit our Azure Linux 4.0 page on the Microsoft Marketplace.

To try Azure Linux base container, please use the following image reference: mcr.microsoft.com/azurelinux-beta/base/core:4.0

To try Azure Linux in a local VM, please download the ISO Installer: x86_64 / ARM64

Before using a downloaded ISO, verify the checksum and signature of the ISO.

After downloading and verifying the ISO, follow the ISO installer instructions to install and use Azure Linux in a local VM (Hyper-V on Windows or QEMU/KVM on Linux). The ISO runs the Anaconda installer.

Note: Support for the ISO is community based. Before filing a new bug or feature request, please search the list of Github Issues. If you are unable to find a matching issue, please report new bugs by clicking here. For additional information, refer to the SUPPORT.md file.

To try Azure Linux on the Windows Subsystem for Linux, install it from the WSL distribution list:

wsl --install AzureLinux-4

wsl --install downloads the package for your architecture (x86_64 or ARM64) and checks it against the SHA-256 checksum in the WSL distribution manifest before installing it. wsl --list --online shows Azure Linux 4 among the available distributions.

To list all the installed distributions:

wsl --list

To use the distro:

wsl -d AzureLinux-4

To install from a downloaded .wsl package instead, download the package for your architecture:

Before installing a downloaded package, verify the checksum and signature of the .wsl package. Then install it using wsl:

wsl --install --from-file "C:\Path\To\AzureLinux-4.0-ARCH.wsl"

See Systemd defaults in WSL images for the networking, console, and temporary-file policies.

What's in this branch?

Azure Linux 4 is an RPM-based distribution optimized for Azure and modern cloud workloads. It is defined by a set of TOML configuration files and targeted overlays applied to Fedora Linux, its upstream base.

Deviations from upstream are declaratively defined and scoped to avoid unnecessary divergence or forking. This repository contains a mechanically rendered set of RPM package spec files derived from applying this layer to Fedora's upstream packaging sources.

For the implementations selected by the VM base images, see VM base image userland implementations.

How Azure Linux is defined

The distro is described almost entirely in TOML-based configuration files. Our open-source development tool, azldev, is used to apply this configuration to upstream Fedora spec files and packaging sources.

azldev.toml        # Top-level entry point
├── distro/        # Distro-wide configs (e.g., sources, mock configs)
└── base/          # The "base" project: components, images, tests
    └── comps/     # Component definitions (one per source package)
    └── images/    # Base image definitions

Concepts/terms

  • Components (also known as source packages) are the unit of packaging. Most are imported in source form from Fedora's upstream dist-git repositories; each component produces one or more RPMs. Azure Linux builds all components from sources to produce a full set of installable RPM packages.
  • Overlays are declarative modifications to upstream specs and sources (e.g., patches, additions/removals, build parameters). They live alongside the component definition and always carry a description explaining why the change is needed. Overlays let us avoid forking upstream specs and are more flexible than plain textual patches.
  • Rendered specs are the final .spec files produced by applying overlays to upstream sources. They are mechanically generated by azldev, checked in for visibility and auditability, and live under specs/. Treat them as derived output and not sources for editing. We use them as the input to standard RPM building services/tools (mock + rpmbuild, koji).

For a deeper tour of the tooling, the overlay system, and how to get started developing within this distro, please see DEVELOPING.md.

Repository layout

PathWhat's there
azldev.tomlTop-level config — includes distro/ and base/.
distro/Distro definitions (Azure Linux + upstream Fedora), shared mock configs.
base/The base project: components, images, tests.
base/comps/Component definitions — the heart of the distro.
base/images/Image definitions (VM, container, etc.) built from the component set using KIWI NG.
specs/Rendered specs — generated .spec files after overlays are applied. Checked in for visibility; do not hand-edit.
locks/Per-component lock files pinning upstream commits + input fingerprints; do not hand-edit.
external/schemas/Cached copy of the JSON Schema for TOML config files; mirrored from azldev.
.github/CI workflows, plus Copilot prompts, skills, and agent instructions used by AI-assisted development.

Getting started as a distro developer

If you want to build or develop within the distro, start with DEVELOPING.md. Don't worry about this if you're pri

// HOW IT'S BUILT

// FILES

2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • .agents/skills/azldev/SKILL.md4.3 KB261c9814f1c9upstream ↗
    ---
    name: azldev
    description: "Read this before running azldev or editing azldev config, and whenever working in a repo that contains an azldev.toml file; do not guess azldev's commands or config. Explains how to use the azldev CLI to build a distro from TOML config, including the core concepts (components, overlays, distros, rendered specs, locks), running azldev (repo root or -C, plus the -q and -O json flags), the common commands, and where to go for each workflow. Triggers include azldev, comp build, comp render, comp update, build a component, add a component, distro config."
    ---
    
    # Using azldev
    
    azldev builds a Linux distribution from TOML configuration. It imports RPM specs
    from an upstream distro and customizes them with an overlay system — no spec
    forking. Components render to specs and sidecar build inputs, then build into RPMs;
    images assemble RPMs into bootable artifacts.
    
    ## Orient yourself
    
    - Run azldev from the repo root (where `azldev.toml` lives), or pass `-C <dir>`.
    - Global, agent-friendly flags: **`-q`** (quiet) and **`-O json`** (machine-readable
      output). They work on every command.
    - Config is a stitched TOML hierarchy: `azldev.toml` includes the distro and project
      config, which include the component files (`**/*.comp.toml`) into one namespace.
    
    ## Core concepts
    
    - **Component** — a unit of packaging that renders to a spec and sidecar build inputs,
      then builds into one or more RPMs. Its spec source is upstream (default), a pinned
      upstream distro/version, or a local spec.
    - **Overlay** — a semantic patch applied to a spec or source file at render time, so
      you customize upstream without forking it.
    - **Distro** — a named build target (`*.distro.toml`) with upstream URIs, release
      versions, and build inputs.
    - **Rendered spec** — the generated `.spec` after overlays; a build input, never
      hand-edited.
    - **Lock** — a per-component file pinning the resolved upstream commit and an input
      fingerprint.
    
    ## Common commands
    
    Top-level commands in this build:
    
    - `azldev completion` — Generate the autocompletion script for the specified shell
    - `azldev component` — Manage components
    - `azldev config` — Manage tool configuration
    - `azldev docs` — Documentation commands
    - `azldev image` — Manage Azure Linux images
    - `azldev package` — Manage binary package configuration
    - `azldev project` — Manage Azure Linux projects
    - `azldev repo` — Inspect and manage RPM repositories
    - `azldev version` — Print the CLI version
    
    Everyday tasks (add `-q -O json` when scripting):
    
    | Task | Command |
    | --- | --- |
    | List components | `azldev comp list -a` |
    | Inspect one component | `azldev comp list -p <name>` |
    | Add a component | `azldev comp add` |
    | Build a component | `azldev comp build -p <name>` |
    | Render specs | `azldev comp render -p <name>` (or `-a`) |
    | Refresh a lock | `azldev comp update -p <name>` |
    | List / build images | `azldev image list` / `azldev image build` |
    
    `comp` is an alias for `component`. Always confirm current syntax with
    `azldev <command> --help`.
    
    The hidden `advanced` group (`adv`) contains specialist integrations such as MCP and
    mock helpers; it is intentionally omitted from normal help.
    
    ## Where to go next
    
    - Add a new component — read the `azldev-add-component` skill.
    - Edit or review a component's TOML — read the `azldev-comp-toml` skill.
    - Add or change overlays — read the `azldev-overlays` skill.
    - Annotate an overlay's intent (category, upstream status, provenance) — read the `azldev-overlay-metadata` skill.
    - Build, iterate, and debug a component — read the `azldev-build-component` skill.
    - Build, boot, and register images — read the `azldev-image` skill.
    - Refresh a lock and finalize for a PR — read the `azldev-update-component` skill.
    - Remove a component — read the `azldev-remove-component` skill.
    - Test built RPMs in a chroot — read the `azldev-mock` skill.
    
    ## Golden rules
    
    - **Never edit generated output** — rendered specs and the output/work/log dirs are
      produced by azldev. Change the source config and re-render.
    - **Re-run `azldev comp update` before opening a PR** — the lock fingerprint covers
      the whole component config, and lock / rendered-spec CI checks run on committed state.
    - **Every overlay needs a `description`** explaining why the change is needed.
    
    Generated by `azldev docs agent`; do not hand-edit.
    
  • README.mdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/microsoft-azurelinux-agents-skills-azldev.md

// REPO STATS

5.4k stars
26 open issues
Last commit: 2d ago