The Astrality configuration directory

The configuration directory for astrality is determined in the following way:

  • If $ASTRALITY_CONFIG_HOME is set, use that path as the configuration directory, else…
  • If $XDG_CONFIG_HOME is set, use $XDG_CONFIG_HOME/astrality, otherwise…
  • Use ~/.config/astrality.

The resulting directory path can be displayed by running:

$ astrality --help
usage: Astrality ...
The location of Astralitys configuration directory is:

This directory path will be referred to as $ASTRALITY_CONFIG_HOME in the rest of the documentation.

The Astrality configuration files

There are three configuration files of importance in $ASTRALITY_CONFIG_HOME:

Global configuration options for Astrality.
Here you define modules you want to use.
Context values used for placeholder substitution in compiled templates.

If $ASTRALITY_CONFIG_HOME/astrality.yml does not exist, an example configuration directory will be used instead.

You can also copy over this example configuration directory as a starting point for your configuration by running:

$ astrality --create-example-config
Copying over example config directory to "/home/example_username/.config/astrality".

You should now edit astrality.yml, modules.yml, and context.yml to fit your needs.

The configuration file syntax

Astrality’s configuration files uses the YAML format. The syntax should be relatively self-explanatory when looking at the example configuration. If you still want a basic overview, take a look at the Ansible YAML syntax documentation for a quick primer.

Command substitution in configuration files

Astrality’s configuration files are themselves templates that are compiled and interpreted at startup. Using templating features in astrality configuration files is usually unnecessary.

But sometimes it is useful to insert the result of a shell command within a configuration file, such as “context.yml”. You can use command substitutions in order to achieve this:

  • Command substitution:

    {{ 'some_shell_command' | shell }} is replaced with the standard output resulting from running some_shell_command in a bash shell.

    You can set a timeout and/or fallback value for command substitutions. See the documentation for the shell filter.


Shell commands are always executed from the same directory as the file which contains the command substitution.

If you need to refer to paths outside this directory, you can use absolute paths, e.g. {{ 'cat ~/.home_directory_file' | shell }}.

Astrality configuration options

Global Astrality configuration options are specified in astrality.yml within a dictionary named astrality, i.e.:

# Source file: $ASTRALITY_CONFIG_HOME/astrality.yml
    hot_reload_config: true
    startup_delay: 10

Avalable configuration options:


Default: false

If enabled, Astrality will watch for modifications to astrality.yml, modules.yml, and context.yml.

When one of these are modified, Astrality will perform all exit actions in the old configuration, and then all startup actions from the new configuration.

Ironically requires restart if enabled.

Useful for quick feedback when editing your configuration.


Default: 0

Delay Astrality on startup, given in seconds.

Useful when you depend on other startup scripts before Astrality startup, such as reordering displays.

Where to go from here

What you should read of the documentation from here on depends on what you intend to solve by using Astrality. The most central concepts are:

  • Templating explains how to write configuration file templates.
  • Modules specify which templates to compile, when to compile them, and which commands to run after they have been compiled.
  • Event listeners define types of events which modules can listen to and change their behaviour accordingly.

These concepts are relatively interdependent, and each documentation section assumes knowledge of concepts explained in earlier sections. If this is the first time you are reading this documentation, you should probably just continue reading the documentation in chronological order.