Playbook Structure

Overview

AtlasOS uses the AME Wizard Playbook format to automate Windows modifications. The playbook is a structured directory containing configuration files, executables, and metadata that define how Atlas transforms Windows.

Directory Structure

The playbook is located at src/playbook/ and follows this structure:

src/playbook/
├── playbook.conf          # Main playbook configuration file
├── Configuration/         # YAML configuration files
│   ├── atlas/            # Core Atlas configuration tasks
│   ├── tweaks/           # Categorized system tweaks
│   ├── custom.yml        # Root playbook orchestration file
│   └── tweaks.yml        # Tweaks orchestration file
├── Executables/          # Scripts and tools
│   ├── AtlasDesktop/     # User-facing Atlas folder
│   ├── AtlasModules/     # Internal modules and tools
│   └── *.ps1, *.cmd      # Setup scripts
├── Images/               # Playbook images and assets
├── build-playbook.cmd    # Windows build script
└── build-playbook.sh     # Linux build script

playbook.conf File Format

The playbook.conf file is an XML configuration file that defines the playbook’s metadata, requirements, and user interface.

Basic Structure

<Playbook>
    <Name>AtlasOS</Name>
    <Username>Atlas</Username>
    <Title>Atlas v0.5.0</Title>
    <ShortDescription>AtlasOS Playbook for Windows 11</ShortDescription>
    <Description><![CDATA[...]]></Description>
    <Version>0.5.0</Version>
    ...
</Playbook>

Key Configuration Sections

Metadata Fields

<Name>AtlasOS</Name>
<Username>Atlas</Username>
<Title>Atlas v0.5.0</Title>
<ShortDescription>AtlasOS Playbook for Windows 11</ShortDescription>
<Description><![CDATA[╭───────────── ⚠️ 𝗖𝗿𝗶𝘁𝗶𝗰𝗮𝗹 ⚠️ ─────────────╮
│         Read the Atlas documentation first.       │
│                https://docs.atlasos.net/                 │
╰───────────────────────────────────────╯

Atlas makes your computer snappier and more private with lots of usability improvements.]]></Description>
<Details>An open and lightweight modification to Windows, designed to optimize performance, privacy and security.</Details>
<ProgressText><![CDATA[Atlas is currently installing software, copying its configuration folders, and tweaking Windows.]]></ProgressText>
<Version>0.5.0</Version>

Supported Windows Builds

playbook.conf:15-20

<SupportedBuilds>
    <!-- 24H2 -->
    <string>26100</string>
    <!-- 25H2 -->
    <string>26200</string>
</SupportedBuilds>

Requirements

The playbook enforces specific requirements before installation:

playbook.conf:22-29

<Requirements>
    <Requirement>DefenderToggled</Requirement>
    <Requirement>NoAntivirus</Requirement>
    <Requirement>Internet</Requirement>
    <Requirement>NoPendingUpdates</Requirement>
    <Requirement>UCPDDisabled</Requirement>
    <Requirement>PluggedIn</Requirement>
</Requirements>

Configuration Options

playbook.conf:30-40

<UniqueId>00000000-0000-4000-6174-6c6173203a33</UniqueId>
<InstallGuide>https://docs.atlasos.net/getting-started/installation</InstallGuide>
<Overhaul>true</Overhaul>
<UseKernelDriver>false</UseKernelDriver>
<AllowUnsupportedUpgrades>false</AllowUnsupportedUpgrades>
<ProductCode>64</ProductCode>
<EstimatedMinutes>15</EstimatedMinutes>
<Git>https://github.com/Atlas-OS/Atlas</Git>
<Website>https://atlasos.net</Website>
<SupportsISO>true</SupportsISO>

Feature Pages

The playbook defines interactive setup pages for user customization:

Radio Pages (Single Choice)

playbook.conf:57-70

<RadioPage IsRequired="true" DefaultOption="defender-enable" 
           Description="Disabling Defender reduces security, and is an option for advanced users only.">
    <TopLine Text="Defender can be toggled in the Atlas folder."/>
    <Options>
        <RadioOption>
            <Text>Enable Defender (recommended)</Text>
            <Name>defender-enable</Name>
        </RadioOption>
        <RadioOption>
            <Text>Disable Defender</Text>
            <Name>defender-disable</Name>
        </RadioOption>
    </Options>
    <BottomLine Text="Learn more" Link="https://docs.atlasos.net/..."/>
</RadioPage>

Checkbox Pages (Multiple Choice)

playbook.conf:99-115

<CheckboxPage IsRequired="true" 
              Description="Select the options you would like to use...">
    <Options>
        <CheckboxOption>
            <Text>Disable Hibernation</Text>
            <Name>disable-hibernation</Name>
        </CheckboxOption>
        <CheckboxOption>
            <Text>Maximum Performance (Disable Power Saving)</Text>
            <Name>disable-power-saving</Name>
        </CheckboxOption>
        <CheckboxOption>
            <Text>Disable Core Isolation</Text>
            <Name>disable-core-isolation</Name>
        </CheckboxOption>
    </Options>
    <BottomLine Text="Learn more" Link="https://docs.atlasos.net/..."/>
</CheckboxPage>

Radio Image Pages (Visual Selection)

playbook.conf:141-174

<RadioImagePage CheckDefaultBrowser="true" 
                DependsOn="install-another-browser" 
                DefaultOption="browser-brave" 
                Description="Select your preferred browser to install.">
    <TopLine Text="We do not recommend Chrome for privacy reasons."/>
    <Options>
        <RadioImageOption>
            <Text>Brave</Text>
            <Name>browser-brave</Name>
            <FileName>brave</FileName>
            <GradientTopColor>#131524</GradientTopColor>
            <GradientBottomColor>#3b3e4f</GradientBottomColor>
        </RadioImageOption>
        <!-- More browser options... -->
    </Options>
    <BottomLine Text="Which is best for me?" Link="https://docs.atlasos.net/..."/>
</RadioImagePage>

OOBE Configuration

Controls the Out-Of-Box Experience:

playbook.conf:41-51

<OOBE>
    <BulletPoints>
        <BulletPoint Icon="Rocket" Title="Performance"
        Description="By removing unnecessary background processes, telemetry..."/>
        <BulletPoint Icon="Lock" Title="Usability"
        Description="By removing Windows' advertising..."/>
        <BulletPoint Icon="Privacy" Title="Privacy"
        Description="By eliminating most of Microsoft's notorious tracking..."/>
    </BulletPoints>
    <Internet>Force</Internet>
</OOBE>

ISO Configuration

playbook.conf:52-55

<ISO>
    <DisableBitLocker>true</DisableBitLocker>
    <DisableHardwareRequirements>true</DisableHardwareRequirements>
</ISO>

How Playbooks Work

Execution Flow

AME Wizard reads playbook.conf and validates requirements
User Configuration - Users make selections through Feature Pages
File Copying - Executables folder is copied to C:\Windows\AtlasDesktop and C:\Windows\AtlasModules
Task Execution - Configuration/custom.yml orchestrates all tasks:
- Loads default user registry hive
- Copies files to Windows directory
- Executes core configuration tasks from atlas/ folder
- Applies tweaks from tweaks/ folder
- Runs cleanup and optimization scripts
- Unloads registry hive

Task Orchestration

The root configuration file (custom.yml) coordinates all tasks:

actions:
  # Load default user registry hive
  - !powerShell:
    command: 'reg load HKU\AME_UserHive_Default C:\Users\Default\NTUSER.DAT'
    oobe: false
    wait: true
  
  # Copy Atlas folders to Windows directory
  - !writeStatus: { status: "Copying files" }
  - !powerShell:
    command: |
      $windir = [Environment]::GetFolderPath('Windows')
      @(
          'AtlasModules',
          'AtlasDesktop'
      ) | ForEach-Object {
          if (!(Test-Path $_)) { exit 1 }
          Copy-Item -Path $_ -Destination $windir -Force -Recurse
          if (!$?) { exit 2 }
      }
    weight: 10
    wait: true
    exeDir: true

Action Types

Playbooks support various action types:

!powerShell - Execute PowerShell scripts
!cmd - Execute Command Prompt commands
!task - Reference another YAML configuration file
!writeStatus - Update installation progress text
!taskKill - Terminate processes
!run - Launch executables
!registryValue - Modify registry values
!scheduledTask - Configure scheduled tasks
!service - Configure Windows services

Building the Playbook

Windows
Linux

build-playbook.cmd

Creates the .apbx playbook package file.

./build-playbook.sh

Creates the .apbx playbook package file.

The .apbx file is a compressed archive containing all playbook files that AME Wizard can execute.

Best Practices

Configuration Organization

Keep core system changes in Configuration/atlas/
Categorize tweaks by purpose (debloat, performance, privacy, qol, security)
Use descriptive file names that explain what the tweak does

Task Dependencies

Set wait: true for tasks that must complete before others
Use onUpgrade: false for tasks that should only run on fresh installs
Use oobe: false for tasks that should only run during actual installation

Error Handling

Use ignoreErrors: true for optional tasks
Use handleExitCodes: { "!0": halt } to stop on critical failures
Include fallback options for system-specific variations

Configuration Files

Learn about YAML configuration file structure

Executables

Explore scripts and tools in the Executables folder

​Overview

​Directory Structure

​playbook.conf File Format

​Basic Structure

​Key Configuration Sections

​Metadata Fields

​Supported Windows Builds

​Requirements

​Configuration Options

​Feature Pages

​Radio Pages (Single Choice)

​Checkbox Pages (Multiple Choice)

​Radio Image Pages (Visual Selection)

​OOBE Configuration

​ISO Configuration

​How Playbooks Work

​Execution Flow

​Task Orchestration

​Action Types

​Building the Playbook

​Best Practices

​Related Resources

Configuration Files

Executables

Overview

Directory Structure

playbook.conf File Format

Basic Structure

Key Configuration Sections

Metadata Fields

Supported Windows Builds

Requirements

Configuration Options

Feature Pages

Radio Pages (Single Choice)

Checkbox Pages (Multiple Choice)

Radio Image Pages (Visual Selection)

OOBE Configuration

ISO Configuration

How Playbooks Work

Execution Flow

Task Orchestration

Action Types

Building the Playbook

Best Practices

Related Resources