The typical way to install Endless OS is to download an ISO or disk image built by Endless, which includes a generic set of applications and content. In some circumstances a custom image might be preferred. A typical use case would be adding or removing applications.
The Endless OS image builder is the tool used by Endless to create images for installation and evaluation. The tool has a rich set of customization methods to alter the content of the images and produce the expected assets. Some basic instructions and examples are given below, but please consult the image builder README for full details on how the configuration and hooks layers can be used to customize the build.
The Endless OS image builder is intended for use by advanced users, technicians and developers. Producing custom Endless OS images with this tool requires a degree of technical prowess and attention to detail, particularly when more advanced customisations are required.
The Endless OS image builder was only recently released for public use, it is a work in progress and we intend to make it more usable and accessible in future. Please be aware of the following restrictions and caveats:
mmdebstrapinstalled, such as the not-yet-released Endless OS 4. It cannot yet be run on a released version of Endless OS.
eos-image-builderrepo and enter it:
git clone https://github.com/endlessm/eos-image-builder.git cd eos-image-builder
config/local.inifile as needed. Some typical customizations can be seen in
Currently the builder needs to run privileged to create the build root and loop devices. The easiest way to do that is to run as
root, as instructed above.
When completed, the built images can be found in
/var/cache/eos-image-builder/tmp/out. The entire
/var/cache/eos-image-builder directory can be deleted when no longer needed, but it will cache some resources for reuse on subsequent builds if you plan to create more images.
Images built with this tool include Endless OS (more precisely: the Endless OS ostree filesystem tree), a copyrighted collective work of the Endless OS Foundation, and hence any redistribution of such images is subject to the Endless OS Redistribution Policy.
This eos-image-builder tool in itself is Open Source software licensed under the GNU GPL v2.
Below are some typical customizations available.
By default the image builder creates images based on the unreleased
master branch of the OS. This can be changed by passing a different branch on the command line. Note that the image builder is branched at the same time as the OS so that changes to the image builder can be managed independently for each OS branch.
For that reason it's required to checkout the image builder branch matching the OS branch to build from. For example, to build
git checkout eos4.0 sudo ./eos-image-builder eos4.0
This will build an image against the unreleased version of the OS. If you want to build an image that uses the released version of the OS, pass the
--use-production-ostree to the image builder.
The image builder chooses from a set of configurations in the
config directory based on the command line options. The typical configuration option to change for customization is referred to as the personality and is set by the
--personality option. By default this is
base, which is a minimal installation without applications. Other personalities include
en, which includes a standard set of configuration, apps and content targeted at English language speakers. Specifying
--personality en will choose this personality. You can also define your own personality by creating a new file in
The set of applications to install can be changed with local configuration settings in
config/local.ini. For example:
[flatpak-remote-flathub] apps_add = com.valvesoftware.Steam org.ardour.Ardour apps_del = edu.mit.Scratch
This would add Steam and Ardour from Flathub while removing Scratch. Another method is to completely override the set of applications for a given remote:
[flatpak-remote-flathub] apps = org.mozilla.firefox
It can be worthwhile to include Kolibri content in an image. To specify Kolibri channels for a personality, add a
[kolibri] section in the personality configuration:
[kolibri] install_channels = # How to get started with Kolibri on Endless OS  e8a879742b2249a0a4b890f9903916f7
You can include specific content from the included channels, as well, by adding a section for each channel:
[kolibri-e8a879742b2249a0a4b890f9903916f7] include_node_ids = # How to get started with Kolibri on Endless OS [topic - 62] e8a879742b2249a0a4b890f9903916f7
For more complex needs, try
eos-kolibri-listcontent to generate Kolibri content configuration:
It is often convenient to use an ISO image to test & install Endless OS. You can configure the image builder to generate an ISO image as follows:
[image] iso = true
(This is disabled by default since it makes the image builder take longer to run and roughly doubles the disk space required for the final artefacts.)
Images downloaded from Endless are signed with GPG to provide verification to users. A custom GPG key can be provided to generate signatures for each assets.
First, specify the GPG key ID in
[image] signing_keyid = 0123456789ABCDEF
Next, create the image builder's GPG home directory and import the private key.
sudo mkdir -p /etc/eos-image-builder/gnupg sudo chmod 700 /etc/eos-image-builder/gnupg sudo gpg --homedir /etc/eos-image-builder/gnupg import /path/to/private/key