Project configuration: atmos.yaml structure, all sections, discovery, merging, base paths, settings, imports, profiles
The atmos.yaml file is the central project configuration for Atmos. It defines how Atmos discovers stacks, where
components live, how templates are processed, and how every subsystem (auth, stores, workflows, toolchain, validation,
integrations) is configured. Every Atmos project needs at least one atmos.yaml.
Atmos searches for atmos.yaml in this order (first found wins):
--config CLI flag or ATMOS_CLI_CONFIG_PATH environment variable.--profile flag or ATMOS_PROFILE environment variable)../atmos.yaml).<repo-root>/atmos.yaml).~/.atmos/atmos.yaml)./usr/local/etc/atmos/atmos.yaml on Linux/macOS, on Windows).%LOCALAPPDATA%/atmos/atmos.yamlWhen multiple files are found, they are deep-merged with earlier sources taking precedence.
Most atmos.yaml settings can be overridden via environment variables using the ATMOS_ prefix:
ATMOS_BASE_PATH=/path/to/project
ATMOS_STACKS_BASE_PATH=stacks
ATMOS_COMPONENTS_TERRAFORM_BASE_PATH=components/terraform
ATMOS_WORKFLOWS_BASE_PATH=stacks/workflows
ATMOS_LOGS_LEVEL=Debug
The simplest atmos.yaml that works:
base_path: ""