Skip to main content

​
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

  1. AME Wizard reads playbook.conf and validates requirements
  2. User Configuration - Users make selections through Feature Pages
  3. File Copying - Executables folder is copied to C:\Windows\AtlasDesktop and C:\Windows\AtlasModules
  4. 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

build-playbook.cmd
Creates the .apbx playbook package file.
The .apbx file is a compressed archive containing all playbook files that AME Wizard can execute.

​
Best Practices

  • 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
  • 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
  • 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

Build docs developers (and LLMs) love

Get started for freeTalk to us