Building CopperheadOS


1. Ubuntu 16.04
2. At least 100Gb free space
3. Network connection
4. Install the following packages:

sudo apt-get update                                                                                      
sudo apt-get --assume-yes install openjdk-8-jdk git-core gnupg flex bison \                              
     build-essential zip curl zlib1g-dev gcc-multilib g++-multilib \                                     
     libc6-dev-i386 lib32ncurses5-dev x11proto-core-dev libx11-dev lib32z-dev \                          
     ccache libgl1-mesa-dev libxml2-utils xsltproc unzip python-networkx \                               
     liblz4-tool fuse fuseext2 haveged libhavege1 brotli python-brotli \                                 
     libfile-slurp-perl repo                                                                                  
sudo apt-get --assume-yes build-dep "linux-image-$(uname --kernel-release)"                              
sudo apt-get --assume-yes install gperf jq

Stable release

Finding a tag can be easy - select it on Github such as this one.

Make sure to use the correct tag for a device. For devices without official support, use the latest tag for the Pixel 2 XL.
mkdir copperheados-TAG_NAME
cd copperheados-TAG_NAME
repo init -u git:// -b refs/tags/TAG_NAME

Complete the source tree download:
repo sync -j32

Note that the repo command itself takes care of updating itself and uses gpg to verify by default.

Chromium and WebView

Before building CopperheadOS, you need to include Chromium for the WebView and optionally the standalone browser app. CopperheadOS uses a hardened fork of Chromium for these. It needs to be rebuilt when Chromium is updated or the CopperheadOS chromium_patches repository changes.

Chromium and the WebView are independent applications built from the Chromium source tree. The CopperheadOS Chromium build is located at external/chromium and includes the WebView.

See Chromium’s Android build instructions for details on obtaining the prerequisites.

Downloadable Binary
Chromium is available as a ready-made binary. The latest version is 70.0.358.77

You can download the APK here
MonochromePublic.apk 142 MB Download

Building Chromium (optional if not using prebuilt APK)
mkdir chromium
cd chromium
fetch --nohooks android --target_os_only=true

Sync to the latest stable release for Android:
(version 66.0.3359.158 is only used as an example below)
gclient sync --with_branch_heads -r 66.0.3359.158 --jobs 32

Apply the CopperheadOS patches on top of the tagged release:
git clone git://
cd src
git am ../chromium_patches/*.patch

Note that we don’t have our own public repository at the moment because Chromium is too large to host it on GitHub or Bitbucket where we are hosting the other repositories.

Then, configure the build in the src directory:
gn args out/Default

CopperheadOS configuration:
(again, the version numbers used below are only examples)
target_os = "android"
target_cpu = "arm64"
is_debug = false

is_official_build = true
is_component_build = false
symbol_level = 0

ffmpeg_branding = "Chrome"
proprietary_codecs = true

android_channel = "stable"
android_default_version_name = "66.0.3359.158"
android_default_version_code = "335915852"

To build Monochrome, which provides both Chromium and the WebView:
ninja -C out/Default/ monochrome_public_apk

The apk needs to be copied from out/Default/apks/MonochromePublic.apk into the Android source tree at external/chromium/prebuilt/arm64/MonochromePublic.apk

Standalone builds of Chromium and the WebView can be done via the chrome_modern_public_apk and system_webview_apk targets but those aren’t used by CopperheadOS. The build system isn’t set up for including them and the standalone WebView isn’t whitelisted inframeworks/base/core/res/res/xml/config_webview_packages.


If you wish to setup custom branding for your build of Copperhead, you can add custom assets in the branding/ directory in your Copperhead sync root. In there, you can add custom bootanimation ZIP files or even override default strings or drawables. Examples have been provided in the branding/ directory.

Setting up the build environment

The build has to be done from bash as is not compatible with other shells like zsh.

Set up the build environment:
source script/

Select the desired build target (aosp_marlin is the Pixel XL):
choosecombo release aosp_marlin user

For a development build, you may want to replace user with userdebug in order to have better debugging support. Production builds should be userbuilds as they are significantly more secure and don’t make additional performance sacrifices to improve debugging.

Reproducible builds

To reproduce a past build, you need to export BUILD_DATETIME and BUILD_NUMBER to the values set for the past build. These can be obtained from out/build_date.txt and out/build_number.txt in a build output directory and the and properties which are also included in the over-the-air zip metadata rather than just the OS itself.

The signing process for release builds is done after completing builds and replaces the dm-verity trees, apk signatures, etc. and can only be reproduced with access to the same private keys. If you want to compare to production builds signed with different keys you need to stick to comparing everything other than the signatures.

Extracting vendor files for Nexus and Pixel devices

This section does not apply to HiKey or HiKey 960 as no extra vendor files are required.

Extract the vendor files corresponding to the matching release:
./script/prepare-vendor-device DEVICE BUILD_ID 

Note that prepare-vendor is non-deterministic for apk and jar files where Google doesn’t provide them unoptimized / unstripped. This was unintentionally improved by Google for the Pixels since Google stopped including odex files in the main system image and they are now provided as unstripped apk files.

The development branch currently requires modifying build/core/ to the correct build id for the vendor files, since it may be newer than the last version for the vendor files and the generated vendor files have a very useful BUILD_ID version check to catch mistakes.

Generating release signing keys

Keys need to be generated for resigning completed builds from the publicly available test keys. The keys must then be reused for subsequent builds and cannot be changed without flashing the generated factory images again which will perform a factory reset. Note that the keys are used for a lot more than simply verifying updates and verified boot. Keys must be generated before building for the Pixel and Pixel XL due to needing to provide the keys to the kernel build system, but this step can be done after building for Nexus devices.

The keys should not be given passwords due to limitations in the upstream scripts. If you want to secure them at rest, you should take a different approach where they can still be available to the signing scripts as a directory of unencrypted keys. The sample certificate subject can be replaced with your own information or simply left as-is.

The Nexus 5X, Nexus 6P, Pixel and Pixel XL use Android Verified Boot 1.0. The Pixel 2 and Pixel 2 XL use Android Verified Boot 2.0 (AVB). Follow the appropriate instructions below.

Android Verified Boot 1.0

To generate keys for marlin (you should use unique keys per device variant):
mkdir -p keys/marlin
cd keys/marlin
../../development/tools/make_key releasekey '/C=CA/ST=Ontario/L=Toronto/O=CopperheadOS/OU=CopperheadOS/CN=CopperheadOS/'
../../development/tools/make_key platform '/C=CA/ST=Ontario/L=Toronto/O=CopperheadOS/OU=CopperheadOS/CN=CopperheadOS/'
../../development/tools/make_key shared '/C=CA/ST=Ontario/L=Toronto/O=CopperheadOS/OU=CopperheadOS/CN=CopperheadOS/'
../../development/tools/make_key media '/C=CA/ST=Ontario/L=Toronto/O=CopperheadOS/OU=CopperheadOS/CN=CopperheadOS/'
../../development/tools/make_key verity '/C=CA/ST=Ontario/L=Toronto/O=CopperheadOS/OU=CopperheadOS/CN=CopperheadOS/'
cd ../..

Generate the verity public key:
make -j20 generate_verity_key
out/host/linux-x86/bin/generate_verity_key -convert keys/marlin/verity.x509.pem keys/marlin/verity_key

Generate verity keys in the format used by the kernel for the Pixel and Pixel XL:
openssl x509 -outform der -in keys/marlin/verity.x509.pem -out kernel/google/marlin/verity_user.der.x509

The same kernel and device repository is used for the Pixel and Pixel XL. There’s no separate sailfish kernel.

Android Verified Boot 2.0 (AVB)

To generate keys for taimen (you should use unique keys per device variant):
mkdir -p keys/taimen
cd keys/taimen
../../development/tools/make_key releasekey '/C=CA/ST=Ontario/L=Toronto/O=CopperheadOS/OU=CopperheadOS/CN=CopperheadOS/'
../../development/tools/make_key platform '/C=CA/ST=Ontario/L=Toronto/O=CopperheadOS/OU=CopperheadOS/CN=CopperheadOS/'
../../development/tools/make_key shared '/C=CA/ST=Ontario/L=Toronto/O=CopperheadOS/OU=CopperheadOS/CN=CopperheadOS/'
../../development/tools/make_key media '/C=CA/ST=Ontario/L=Toronto/O=CopperheadOS/OU=CopperheadOS/CN=CopperheadOS/'
openssl genrsa -out avb.pem 2048
../../external/avb/avbtool extract_public_key --key avb.pem --output avb_pkmd.bin
cd ../..

The avb_pkmd.bin file isn’t needed for generating a signed release but rather to set the public key used by the device to enforce verified boot.


Incremental builds (i.e. starting from the old build) usually work for development and are the normal way to develop changes. However, there are cases where changes are not properly picked up by the build system. For production builds, you should remove the remnants of any past builds before starting, particularly if there were non-trivial changes:
rm -r out

Start the build process, with -j# used to set the number of parallel jobs to the number of CPU threads. You also need 2-4GiB of memory per job, so reduce it based on available memory if necessary:
make -j target-files-package

Faster builds for development use only

The normal production build process involves building a target files package to be resigned with secure release keys and then converted into factory images and/or an update zip via the sections below. If you have a dedicated development device with no security requirements, you can save time by using the default make target, leaving the bootloader unlocked and flashing the raw images that are signed with the default public test keys:
make -j

Technically, you could generate test key signed update packages. However, there’s no point of sideloading update packages when the bootloader is unlocked and there’s no value in a locked bootloader without signing the build using release keys, since verified boot will be meaningless and the keys used to verify sideloaded updates are also public. The only reason to use update packages or a locked bootloader without signing the build with release keys would be testing that functionality and it makes a lot more sense to test it with proper signing keys rather than the default public test keys.

Generating signed factory images and full update packages

For the Pixels and other A/B update devices, build the tool needed to generate A/B updates:
make -j brillo_update_payload

For HiKey and HiKey 960, build dumpkey:
make -j dumpkey

Generate a signed release build with the script:
script/ marlin

The factory images and update package will be in out/release-marlin-$BUILD_NUMBER. The update zip performs a full OS installation so it can be used to update from any previous version. More efficient incremental updates are used for official over-the-air CopperheadOS updates and can be generated by keeping around past signed target_files zips and generating incremental updates from those to the most recent signed