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:
| Mode | When it runs |
|---|---|
| Fresh | Atlas isn’t installed yet. |
| Upgrade | The installed Atlas version is listed in updatableFrom. |
| Reapply | The installed version is the same as the package’s. |
| Rebase | Windows 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,requirementsand 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.toolsandtests: 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.
Running the front door directly
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.