Infrastructure management research project

e107fe9 README: add link to CI builds

a day ago

b88e453 Remove package list from repo, upload it instead

a day ago


Anemos is an open source infrastructure management research project.

Its goals are:

  • To promote (but not enforce) a declarative approach to deployments, ideally culminating in immutable deployments
  • To facilitate bare-metal-level infrastructure-as-code in small environments, where e.g. a full-blown PXE-boot infrastructure is not viable or overkill
  • Provide extensibility into a full-blown asset management platform

In its current state, Anemos is a set of tools that allow you to deploy a system image described in code (e.g. a script that runs setup-alpine) to a host (bare-metal or virtual) without the need for external infrastructure (like PXE boot) or physical access (like booting a live system from USB).

One absolutely welcome side-effect of how Anemos works is that it makes it "easy" (some caveats apply, of course) to deploy a custom distribution to a VPS where the provider only offers a limited choice of distributions. See the demo below.

🔴🔴🔴 NOTE: Anemos is very young and work in progress. It performs actions that can potentially leave your server in a broken or unexpected state. When using it for the first time on a server, make sure you:

  1. Understand the actions it will perform, and
  2. have the means to recover (physical access, serial console access, remote re-imaging, etc)

#How it works

A deployment with Anemos makes use of the following components:

  • A user-supplied payload: this is the codified description of what to deploy
  • An initramfs, which performs the deployment
  • A CLI tool, which - on the host to be deployed - generates the initramfs and boots it, thereby triggering the deployment

The components are described in more detail below. The deployment process works as follows:

  • The user creates a payload describing the desired deployment
  • The host to be deployed to must have:
    • The Anemos CLI
    • Access to the kernel, base initramfs, and payload - either locally or via network
    • A proper Anemos configuration file (see comments in the example)
  • The Anemos CLI is used on the host to:
    • Generate the final initramfs to be used
    • Boot the generated initramfs
  • The initramfs, once booted, will automatically perform the deployment as specified in the payload



The final initramfs is generated on the host to include the deployment payload, network configuration, and firmware. But the deployment mechanics are implemented in the base initramfs.

#CLI tool

The CLI tool is a simple shell script with a single configuration file. There are no packages yet, so it needs to be installed manually for now.


The payload is a gzipped tarball of one of two things:

  • An IMGBUILD - like e.g. the demo payload
  • A custom executable file called deploy, along with whatever other files are needed

A simple example of a custom payload could be a script that simply runs setup-alpine with some predefined answers.

#How to use it

The project is still very young. There are no packages, no versioning, no proper distribution of artifacts. That said, I uploaded everything you need to get started:

NOTE: Doing this will overwrite the host's disk! Do it in a throw-away VM, or something you can easily reset to a state of your liking.

# Prerquisites: make sure you have zstd and cpio installed
wget https://anemos.io/demo/anemos      # The CLI tool
wget https://anemos.io/demo/anemos.conf # An example config file
chmod +x anemos
# Study the config file and edit to your liking
./anemos -c anemos.conf


If you'd rather see it in action on someone else's machine, here is a screencast where you can observe the following:

  • I use the serial console of a LeaseWeb VPS running a freshly provisioned Debian
  • After installing zstd I perform the steps outlined above
  • The machine reboots, initially seemingly back into Debian
  • After loading the initramfs, an Alpine system boots
  • Once OpenRC is done, the deploy starts (pacstrap via makeimg)
  • The machine reboots again
  • A fully functional Arch Linux comes up (LeaseWeb does not offer Arch Linux images for their VPS)