robotnix: building AOSP images with Nix, and what it still cannot do

The problem is the build system, not the source

Android projects often contain long and complicated build instructions requiring a variety of tools for fetching source code and executing the build, and the documentation makes the point that this applies not only to Android itself but also to the projects included in the Android build, such as the Linux kernel, the Chromium webview, MicroG and other external or prebuilt privileged apps.

robotnix orchestrates the diverse build systems across these multiple projects using Nix, inheriting its reliability and reproducibility benefits, and consequently makes the build and signing process very simple for an end user.

That is the entire thesis, and it is a narrower and more interesting claim than it first appears. Building AOSP by hand is not difficult because Android is complex, it is difficult because the build is a stack of build systems, each with its own dependencies, its own toolchain expectations and its own way of fetching things, and none of them were designed to be nested inside one another. Nix provides the nesting: each dependency is pinned, the sandbox isolates the steps, and the same inputs produce the same output.

The repository reflects that model. The top level contains components.json and components.nix for the pieces of the stack, flavors/ for the supported distributions, modules/ for the NixOS style module system, pkgs/ for the package definitions, lib/ for the shared logic, plus nixos/ and ota.nix for the OTA pieces, and a template/ directory for the project skeleton.

The primary language is Nix, the default branch is master, and the last push was on 2026-09-28.

One command produces an image you can flash

The quick start is a single nix-build invocation that fetches the project and builds an img for a Fairphone 4:

$ nix-build "https://github.com/nix-community/robotnix/archive/master.tar.gz" \
    --arg configuration '{ device = "FP4"; flavor = "lineageos"; }' \
    -A img

The configuration is passed as an argument rather than edited in a file, which is what makes the quick start quick: device picks the hardware target and flavor picks the distribution. The build runs entirely inside Nix's own dependency machinery, so the only things you need on the machine are Nix itself and the disk space and memory described later.

To flash the result, the documentation gives one more command:

fastboot update -w <img.zip>

And then there is the warning that matters most in the whole quick start. The image is signed with publicly known test-keys, so the documentation says definitely not to use it for anything intended to be secure. Those keys are the same for everyone who has ever built a debug Android image, which means the signing keys are effectively public and the image cannot be trusted for a device whose security matters.

The project does provide the alternative, in the module list: signed builds for verified boot, dm-verity and AVB, and re-locking the bootloader with a user-specified key. That path exists, but it is a module you have to opt into, and the default one-command build is the insecure one.

The flake interface mirrors NixOS system modules

For anyone who works in Nix flakes, the second interface will feel like the natural one.

Robotnix provides a flake interface that can be used via the lib.robotnixSystem attribute, similar to lib.nixosSystem. The example in the documentation configures a system with a flavour, a device codename, a flavour version and a set of module options:

{
    inputs.robotnix.url = "github:nix-community/robotnix";

    outputs = { self, robotnix }: {
        exampleSystem = robotnix.lib.robotnixSystem {
            flavor = "lineageos";
            device = "FP4";
            flavorVersion = "22.2";
            apps.fdroid.enable = true;
            microg.enable = true;
            ccache.enable = true;
        };
    };
}

The comments in that example are practical rather than decorative. The device is the codename, and the supported devices are listed on the LineageOS wiki. The flavour version is the LineageOS branch, and leaving it out chooses the official default branch for the device. The ccache option needs a note: it enables ccache for the build process, and you have to add /var/cache/ccache as an additional sandbox path to your Nix configuration.

That last point is the kind of detail that only appears in a project with real users, and it illustrates the general shape of the tool: the module system is genuinely declarative, and the cost of a module is sometimes a piece of your Nix configuration rather than a line in the module.

Once the flake is written, the build is:

$ nix build .#exampleSystem.img

The modules cover the parts you would otherwise assemble by hand

The module list is the best catalogue of what the project actually does, because each entry corresponds to a piece of the Android build you would otherwise configure by hand.

There is support for GrapheneOS and for LineageOS, and for vanilla Android 12 AOSP for Pixel devices. There are signed builds for verified boot, dm-verity and AVB, with the ability to re-lock the bootloader using a user-specified key.

There is a set of application modules: F-Droid, including the privileged extension for automatic installation and updating, Auditor, and Seedvault Backup. There is a browser and webview set covering Chromium, Bromite and Vanadium, plus OTA updates through the GrapheneOS Updater project and MicroG. You can set framework configuration settings such as those found in the Android platform config, build custom kernels, and supply a custom /etc/hosts file.

And there is the part that most people find hardest to do by hand: extracting vendor blobs from Google's images, using android-prepare-vendor and adevtool.

The module system is described as NixOS style, which is the right comparison because it explains the shape of the configuration. Enabling a feature means setting an option, and the option namespace is organised by area, so apps.fdroid.enable and microg.enable sit next to each other in the same block.

What the module system does not do is paper over the differences between flavours. Choosing GrapheneOS rather than LineageOS is not a configuration value in a vacuum; it changes which upstream is tracked, which is why the flavour version option exists at all, and why the status table below matters.

The hardware cost is the first thing to plan for

The requirements section is specific enough to plan a machine around, and it starts with the upstream recommendation: the AOSP project recommends at least 250GB free disk space as well as 16GB RAM, and it notes that certain device kernels which use LTO plus CFI may require even more memory.

The breakdown for a typical build is roughly 45GB of free disk to check out the Android source, about 14GB for Chromium, and then around 100GB of additional free space for intermediate build products.

That last number is where people get caught, and the documentation explains why. By default Nix uses /tmp to store these intermediate build products, so you have to ensure that /tmp is not mounted using tmpfs, since the intermediate build products are very large and will easily use all of your RAM even if you have 32GB.

That is a genuinely useful warning, because tmpfs is a common default on tmpfs-first Linux setups and the symptom it produces, a machine that appears to run out of memory during a build, looks like a hardware problem rather than a mount configuration one.

There is a second lever if memory is the binding constraint. The --cores option for nix-build sets the number of cores to use, which the documentation says is also useful to decrease parallelism in case memory usage of certain build steps is too large.

Two more requirements close the list. Robotnix requires support for user namespaces, the CONFIG_USER_NS Linux kernel option. And the signing inside Nix with a sandbox exception feature requires a Nix daemon with sandbox support enabled, which is why the documentation says that feature is currently not supported inside Docker.

For timing, the documentation offers one measured data point and one upgrade: a full Android 10 build with the Chromium webview took approximately 10 hours on a quad-core i7-3770 with 16GB of memory, with AOSP accounting for about 4 hours of that and webview for about 6, and the same build on a 3970x Threadripper with 32 cores takes about an hour.

The security caveats are in the documentation, not hidden

Two security boundaries are stated outright, and both are worth understanding before a build rather than after.

The first is the test-keys signing of the default image. The keys are publicly known, so anyone who flashed that image holds a device whose signing chain is worthless for any security purpose. The project does not hide this, and it also does not make the secure path the default, which means a reader who does not read the quick start will produce an insecure image without any warning from the build itself.

The second is the sandbox exception for signing. Signing an Android image means producing something the bootloader will trust, and doing it inside the Nix sandbox requires relaxing the sandbox, which is why the feature needs a Nix daemon with sandbox support. That capability is exactly the kind that tends to be disabled in shared or containerised build environments, and the documentation says the feature is not supported inside Docker for this reason.

A third boundary is more subtle. Robotnix builds the operating system, and the operating system decides what gets signed, what gets installed as a privileged app and what runs with which permissions. The module list shows the reach of that decision: F-Droid with its privileged extension, MicroG, custom kernels, custom /etc/hosts, framework configuration settings and the bootloader key all live in the same configuration file.

That reach is the point of the tool, and it is also why the licence of the resulting image and of the third party components you enable are questions to answer before you flash anything to a device that matters.

Three years without a maintainer, and a status table instead of a promise

The important callout at the top of the repository describes the state of the project accurately.

It is currently in the process of being picked up by a new maintainer, and many components are still in disrepair after having been unmaintained for three years. At the moment the team can keep up with the LineageOS and GrapheneOS upstreams, but that could change at any point.

The next line is the one to remember: at this point robotnix is not ready for daily use, and it should be treated as in-development alpha software.

For a project whose whole purpose is tracking upstream changes, that is a serious constraint and it is honestly stated. The status section exists precisely because of it. The table documents the current status of robotnix components, with columns for whether a component is maintained, whether it is subject to removal, and who knows it well. The rows shown in the excerpt cover Android versions, marked as maintained with two people knowledgeable, and dependencies, meaning Nixpkgs, also marked as maintained with two people knowledgeable.

The subject to removal column is the part worth pausing on. A component can be marked maintained and still be flagged as something that may be removed, which means you are not choosing between a maintained project and an abandoned one, you are choosing between components with different degrees of institutional support.

The documentation beyond the repository is thin but pointed: docs.robotnix.org is the place the project says to consult before use, and the project was presented at Nixcon 2020, with a recording of the talk and the slides linked. The community channel is #robotnix on Matrix at nixos.org.

The repository also carries NEWS.md, a LICENSES directory that holds per-file licence information, and the SPDX header names Daniel Fullmer and the robotnix contributors under MIT, even though the repository's own licence field is listed as unknown.

Editorial conclusion

robotnix suits a developer who wants a reproducible Android build, who needs to patch the kernel or the framework and rebuild, and who already lives in Nix. It is the wrong choice if you want a supported phone, if your goal is a daily driver, or if you are not prepared to read a status table before every upgrade, because the project says plainly that many components are still in disrepair. Verify three things before you plan a build: that the component you care about is marked as maintained in the status table, that you have the disk space and RAM the documentation quotes, and that you have decided how you will sign the image, since the quick start path produces a test-keys build that the documentation says must not be used for anything intended to be secure.

Frequently asked questions

Official sources

1. Issues
2. nix-community/robotnix on GitHub
3. README