Contributing to the Atlas package

On this page

This guide is for contributors who change what Atlas does to Windows. Read the contribution guide first.

The Atlas repository holds the Atlas package, Atlas Manager, and their build and test tools.

How the Atlas package works

The Atlas package is an .atlaspkg file, a ZIP archive that opens with the public password atlasos. It holds the PowerShell scripts, data definitions and supporting files that apply Atlas to Windows. Its manifest, atlas.json, declares the version, the supported Windows builds, the versions it can update, the requirements and the installation choices. The repository’s package format defines the archive and the manifest.

Atlas Manager prepares the PC, collects the user’s choices and then runs the package’s front door, Executables\AtlasModules\Scripts\Entry\Install-Atlas.ps1. The front door checks that the PC is ready, copies the package to a protected staging folder and runs the install plan as TrustedInstaller.

The front door picks one of four install modes:

ModeWhen it runs
FreshAtlas isn’t installed yet.
UpgradeThe installed Atlas version is listed in updatableFrom.
ReapplyThe installed version is the same as the package’s.
RebaseWindows rebuilt itself while Atlas Manager moved it to a newer release.

On an update or reinstall, Atlas Manager asks whether to Keep my choices or Choose again. The repository’s upgrading guide explains what each mode and each answer applies.

After installation, the launchers in the Atlas folder run toggles from the same modules. The architecture guide covers the install plan, identities, install state, retries and recorded choices.

Find the relevant source

  • package/atlas.json: the manifest, with the release version, supportedBuilds, updatableFrom, requirements and the installation choices.
  • package/Executables/AtlasModules: the install framework, phases, tweaks and toggle definitions.
  • package/Executables/AtlasDesktop: the Atlas folder’s launchers and shortcuts.
  • app: Atlas Manager, a Rust app. See its README.
  • tools and tests: build tools, developer tools and automated checks.
  • docs/catalog: generated references for every toggle and install tweak.

The contributor quick start explains how to add or change a tweak or toggle, and how to regenerate the launchers and catalog afterwards.

Build a test package

Install PowerShell 7 and 7-Zip or NanaZip, then open the repository root.

On Windows:

.\build.cmd

On a Unix shell:

./build.sh

Both write package/Atlas Test.atlaspkg with the local test profile. That profile leaves out supportedBuilds, so it suits quick structure checks. Atlas Manager and the front door refuse to install it.

To build a package you can install, run a full build from PowerShell 7:

pwsh tools/build/Build-Package.ps1 -FileName 'Atlas Lab' -ReplaceExisting -NoExplorer

This writes package/Atlas Lab.atlaspkg with every check in place. Never distribute a package you built yourself as a release.

The build tools use PowerShell 7. The scripts in the package run on Windows PowerShell 5.1, which every supported Windows includes, so avoid syntax that only PowerShell 7 supports. The build guide lists the build options and how to verify a built package.

Test a built package

Use a disposable virtual machine for each supported Windows release. The supported releases table lists them. Take a checkpoint before each test, and keep separate checkpoints for a fresh Windows installation and for each Atlas release that can update directly.

To test your full build, open your .atlaspkg file with the release version of Atlas Manager.

When testing, you can run Install-Atlas.ps1 from an elevated Windows PowerShell prompt in the extracted package’s Executables folder. The front door reference lists its parameters and exit codes. Atlas Manager remains the only way to install Atlas for users.

Check these for every change:

  • The changed behaviour, its failures and a retry after a failure.
  • Restarts during the Get ready page and after installation.
  • Updates with Keep my choices and with Choose again, and a reinstall of the same version.
  • The recorded choices, and 9. Troubleshooting → Check Atlas Health.cmd after the restart.
  • The installing account, another existing account and a new account.

For ISO changes, boot the created media and finish setup on the destination PC. A successful ISO build alone doesn’t prove the media works.

Follow the testing guide and the repository’s testing reference, which covers the automated checks and lab VM runs. Test on real hardware as well as VMs before treating a change as verified, and report issues with diagnostics and exact versions.

Search documentation

Search the docs

Pages, guides, and reference