- CopperheadOS installation instructions
- Supported devices
- Web Installer
- Windows 10 Installation Simplified
- Linux and Mac OSX
- Enabling OEM unlocking
- Bootloader-locked devices
- Updating stock before using fastboot
- Obtaining factory images
- Flashing factory images
- Pixel 3/3a: setting custom AVB key
- Pixel 2 and 2 XL: Setting custom AVB key
- Locking the bootloader
- CopperheadOS Signing Key Verification
- Clearing custom AVB key
CopperheadOS currently has official support for the following devices:
- Pixel 3 (blueline)
- Pixel 3 XL (crosshatch)
- Pixel 3a (sargo)
- Pixel 3a XL (bonito)
- Pixel 4 (flame)
- Pixel 4xl (coral)
- Pixel 4a (sunfish)
At one point CopperheadOS was supported on the:
- HiKey (hikey)
- HiKey 960 (hikey960)
- Samsung Galaxy S4
- Nexus 5 (hammerhead)
- Nexus 5X (bullhead)
- Nexus 6P (angler)
- Pixel (sailfish)
- Pixel XL (marlin)
- Pixel 2 (walleye)
- Pixel 2 XL (taimen)
It can be ported to other Android devices with Treble support via the standard device porting process. Most devices lack support for the security requirements needed to match how it works on the officially supported devices.
The Copperhead web installer is currently available to Copperhead Partners with full flashing and locking capabilities.
Start the device you intend to flash normally, and connect it to the internet.
- Open Settings -> About phone -> Find Build Number at the bottom and tap 7 times.
- Return to the Settings menu and navigate to System -> Advanced -> Developer Options
You will now set enable OEM Unlocking. This requires an active network connection such as WiFi. If you cannot enable OEM unlocking with an active network connection, you will need to contact the vendor you bought your device from. Your device will require a restart. Please do so now, and then continue below.
With the device restarted: Return to Settings -> System -> Advanced -> Developer Options and scroll down until you find Enable USB Debugging and toggle it on. You will be presented with a confirmation screen, agree and put your device down somewhere safe for the moment.
Your machine will require at least 4GB RAM and 16GB of disk space. For best results please ensure that Windows 10 is updated to the latest version available.
Download the Android platform-tools for Windows, here. Unzip them to an easily accessible directory. You will need to ensure that these tools are up to date whenever you flash devices.
Add the platform-tools directory to your System Environment
In PowerShell, it is possible to set environment variables with a single command:
Set-Item -Path Env:Path -Value ($Env:Path + ";")
For example, if we downloaded the platform-tools and unzipped them into their own folder in our Windows user Downloads directory. Be sure to fill in the correct directory path to your platform-tools directory.
Set-Item -Path Env:Path -Value ($Env:Path + ";C:\Users\USERNAME\Downloads\platform-tools")
A guide using the Windows GUI: Add to Path in Windows
CopperheadOS currently provides factory images to the Copperhead Partner network and is not open to the public for download.
Factory image files follow the name format codename-factory-BuildID.tar, for example:
Decompress the factory.tar. If you installed WinRAR, you can right click the .tar files and choose 'Extract to sunfish-factory-2021.01.15.01\' from the context menu. This will create a directory of that name in the folder you're working from.
Open the folder we just created by decompressing the factory.tar, and then open the subfolder named codename-buildID, or
The full path would be:
Users unfamiliar with PowerShell can simply open the folder in File Explorer and click the Files menu and choose 'Open Windows PowerShell' to begin a PowerShell session in the open folder.
Flashing requires only a handful of commands. With your device connected by USB to your Windows machine begin with:
This will start the Android Device Bridge daemon the first time it is run. You will now need to authorize adb to communicate with your device. Tap Allow on the pop-up on your device. The
adb devices command may time out before you authorize it, do not worry, if this happens just re-run the command by pressing the Up Arrow on your keyboard and then enter.
For example, with our sunfish device:
PS C:\Users\USERNAME\Downloads\sunfish-2021.01.15.01\sunfish-2021.01.15.01> adb devices List of devices attached 07211JEC204827 device
Now that we know our device is prepared and connected, we can begin flashing.
First, we will put our sunfish device into
fastboot mode using adb.
adb reboot bootloader PS C:\Users\USERNAME\Downloads\sunfish-2021.01.15.01\sunfish-2021.01.15.01> adb reboot bootloader
Your device should immediately restart, and the next screen you see on your device will be the fastboot menu. The most notable features of this menu are the red Fastboot Mode text beneath a red triangle with an exclamation point inside it, and the green "locked" text.
Next we will need to unlock the bootloader.
fastboot flashing unlock PS C:\Users\USERNAME\Downloads\sunfish-2021.01.15.01\sunfish-2021.01.15.01> fastboot flash unlock OKAY [ 0.067s] Finished. Total time: 0.069s
You will need to confirm that you want to unlock the bootloader on your device itself using the Volume Keys to select 'Unlock the bootloader' in the selection text next to the Power Key, and then press the Power Key to confirm.
You will then be returned to the fastboot menu. The device state should now be red and state "unlocked". If the device state remains green "locked", you will need to re-try the
fastboot flashing unlock command.
Next we can run the flash-all.bat that comes with all CopperheadOS factory images.
Do not move your device or touch the USB cable which connects your device to your Windows machine while flash-all runs. Interfering with the USB connection may result in a bad flash or a bricked device.
For example a with our sunfish device:
PS C:\Users\USERNAME\Downloads\sunfish-2021.01.15.01\sunfish-2021.01.15.01> ./flash-all Sending 'bootloader_b' (8341 KB) OKAY [ 0.318s] Writing 'bootloader_b' ...
The device will restart several times.
With the flash-all script complete, you will be prompted to "Press any key to continue..." doing so will return you to the PowerShell prompt.
Our next step will be to lock the bootloader by running
fastboot flashing lock.
PS C:\Users\USERNAME\Downloads\sunfish-2021.01.15.01\sunfish-2021.01.15.01> fastboot flashing lock OKAY [ 0.057s] Finished. Total time: 0.058s
You will again be prompted by your device to confirm. Use the Volume Keys to select 'Lock the bootloader' from the selection text next to the Power Key and use the Power Key to confirm. Your device will restart.
With the bootloader locked, you will now need to Start the device by pressing the Power Key. If Start is not selected on the Fastboot Mode menu, use the Volume Keys to select Start and then press the Power Key to confirm.
If your flash was successful, you will next see a yellow triangle and the texts "Your device is loading a different operating system..."
It is strongly recommended that you disable OEM Unlocking now that CopperheadOS is installed. To do so, follow the instructions below:
Once CopperheadOS starts, you will need to re-enable the Developer Options by going to Settings -> About phone -> Scroll down until you find Build Number and tap Build Number 7 times.
Return to the Settings menu and navigate to System -> Advanced -> Developer Options and then disable OEM Unlocking. Your device will restart.
You should have at least 4GB of memory on your computer to avoid problems.
You can obtain the adb and fastboot tools from the Android SDK. Either install Android Studio or use the standalone SDK. Do not use distribution packages for adb and fastboot. Distribution packages are out-of-date and not compatible with the latest version of Android. An obsolete fastboot will result in corrupted installations and potentially bricked devices. Do not make the common mistake of assuming that everything will be fine and ignoring these instructions. Double check that the first fastboot in your PATH is indeed from an up-to-date SDK installation:
Download the latest SDK platform-tools directly from Google here
To make your life easier, add the directories to your PATH in your shell profile configuration. This will make it so you do not have to be inside a specific directory to get access to fastboot.
Check your $PATH by typing
fastboot -h and see if the output matches ..
usage: fastboot [OPTION...] COMMAND...
With your $PATH correct and installation complete, you can now flash factory images regardless of the directory.
To set up a minimal SDK installation without Android Studio on Linux:
mkdir ~/sdk cd ~/sdk wget https://dl.google.com/android/repository/commandlinetools-linux-6200805_latest.zip unzip commandlinetools-linux-6200805_latest.zip
Run an initial update, which will also install platform-tools and patcher;v4:
For running the Compatibility Test Suite you'll also need the build-tools for aapt:
To make your life easier, add the directories to your PATH in your shell profile configuration:
export PATH="$HOME/sdk/tools:$HOME/sdk/tools/bin:$HOME/sdk/platform-tools:$HOME/sdk/build-tools/25.0.3:$PATH" export ANDROID_HOME="$HOME/sdk"
This is not mandatory, since you can run them from ~/sdk/platform-tools directly.
You should update the sdk before use from this point onwards:
This information covers the Pixel 2, 3 and 3a series of secure phone.
OEM unlocking needs to be enabled from within the operating system.
Enable the developer settings menu by going to Settings -> About device and pressing on the build number menu entry until developer mode is enabled.
Next, go to Settings -> Developer settings and toggle on the 'Enable OEM unlocking' setting. Certain device models may require connecting to WiFi with a delay before the OEM unlocking setting is toggle-able.
If this setting is grayed out even after connecting to WiFi and selecting/de-selecting Developer Options numerous times, you may have a Bootloader-locked device.
Not all devices are created equally and not all devices are unlockable. There is a distinct difference between unlocked devices and bootloader unlockable devices. Often vendors will not know what a bootloader unlockable device is and confuse it with carrier-locked devices. Google has provided refurbished units in the past that are not unlockable even though they may have been unlockable before the refurbished status. To this date no bootloader unlocking exploit has worked or is recommended for installing CopperheadOS. If you encounter a bootloader locked device then you need to return it to the vendor.
To test bootloader-unlockable compatibility, use
getprop in adb shell
adb shell getprop ro.boot.cid
At the time of this writing the only bootloader unlockable device code is
The following is a non-exhaustive list of locked device codes Copperhead has encountered:
- VZW_001 : Verizon locked device
- 00000001 : Google refurbished
It's important to have the latest bootloader firmware before installing CopperheadOS, due to bug fixes for the fastboot mode used to flash CopperheadOS. There are known issues with older versions of the bootloader that are likely to cause problems.
If you're only behind one release, updating within the stock OS makes sense to get an incremental update. If you're behind multiple releases, updating within the OS will usually require installing multiple updates to catch up to the current state of things. The quickest way to deal with that if you have plenty of bandwidth is sideloading the latest full over-the-air update from Google.
The initial install should be performed by flashing the factory images. This will replace the existing OS installation and wipe all the existing data.
CopperheadOS currently provides factory images to the Copperhead Partner network and is not open to the public for download.
At one point Copperhead supported public downloading of official Nexus factory images on a releases page. Public factory had to be unfortunately images removed because of mass violation of Copperhead's non-Commercial licensing.
First, boot into the bootloader interface. You can do this by turning off the device and then turning it on by holding both the Volume Down and Power buttons. Alternatively, you can use
adb reboot bootloader from Android.
The bootloader now needs to be unlocked to allow flashing new images:
fastboot flashing unlock
On some older models of Pixel 2 XL it's necessary to unlock the critical partitions.
fastboot flashing unlock_critical
The command needs to be confirmed on the device.
Next, extract the factory images and run the script to flash them. Extracting the factory images depends on the OS you're using and the applications available.
$DEVICE will either be crosshatch, taimen, walleye, sargo, bonito or blueline. The $DATE of the factory image will correspond to our releases.
Note that the
fastboot command run by the flashing script requires a fair bit of free space in a temporary directory, which defaults to
tar xvf $DEVICE-factory-$DATE.tar.gz cd $DEVICE-factory-$DATE ./flash-all.sh
Use a different temporary directory if your
/tmp doesn't have 2GiB available:
mkdir tmp TMPDIR=$PWD/tmp ./flash-all.sh
You should now proceed to locking the bootloader before using the device as locking wipes the data again.
The custom AVB key for Pixel 3 and 3a series should automatically be set upon flashing.
On the Pixel 2 and Pixel 2 XL, the public key needs to be set for Android Verified Boot 2.0 before locking the bootloader again
fastboot flash avb_custom_key $DEVICE-avb_pkmd.bin
To confirm that the key is set, verify that
fastboot getvar avb_user_settable_key_set
Locking the bootloader is important as it enables full verified boot. It also prevents using fastboot to flash, format or erase partitions. Verified boot will detect modifications to any of the OS partitions (boot, recovery, system, vendor) and it will prevent reading any modified / corrupted data. If changes are detected, error correction data is used to attempt to obtain the original data at which point it's verified again which makes verified boot robust to non-malicious corruption.
Reboot into the bootloader menu and set it to locked:
fastboot flashing lock
The command needs to be confirmed on the device since it needs to perform a factory reset.
If your Pixel 2 XL is the same older model that requires unlocking of the critical_partition, lock the critical_partitions again:
fastboot flashing lock_critical
OEM unlocking should be disabled again in the developer settings menu within the operating system. This prevents unlocking the bootloader without access to the owner account. CopperheadOS prevents bypassing the OEM unlocking toggle by wiping the data partition from the hidden recovery menu, unlike stock Android. You can still trigger factory resets from within the OS. Note that this means that recovering a device with a forgotten password is not possible without Copperhead doing it, which is the main purpose of this feature (anti-theft). Stock Android can be more forgiving because it's tied to a Google account.
Note: Unlocking the bootloader again will perform a factory reset. Do not plan to do so unless otherwise requried.
You should now disable OEM unlocking and factory reset the CopperheadOS device for optimal hardware security.
On device boot the device screen will show an OS fingerprint which is used by Android Verified Boot to match the signing keys of the Operating System installed. Comparing the fingerprint on boot to the keys below is a foolproof way to determine if the device has a verified CopperheadOS install. If the fingerprints below do not match the device boot screen there is a possibility it is a non-CopperheadOS install. If that is the case proceed with caution if the device was not purchased from an authorized CopperheadOS partner.
Updates can also be downloaded from Copperhead and installed via recovery with adb sideloading. The zip files are signed and will be verified by the CopperheadOS recovery image. Sideloading should only be done if OTA updates are not working and there is a critical issue with Updater.
First, boot into recovery. You can do this either by using
adb reboot recovery from the operating system or selecting the Recovery option in the bootloader menu.
You should see an Android lying on their back being repaired, with the text "No command" meaning that no command has been passed to recovery.
Next, access the recovery menu by holding down the power button and pressing the volume up button a single time. This key combination toggles between the GUI and text-based mode with the menu and log output.
Finally, select the "Apply update from ADB" option in the recovery menu and sideload the update with adb:
adb sideload $DEVICE-ota_update-$DATE.zip
On the Pixel 2 and Pixel 2 XL, reverting back to stock requires clearing the configured public key after unlocking the bootloader and before locking it again with the stock factory images:
fastboot erase avb_custom_key
To confirm that the key is unset, verify that
fastboot getvar avb_user_settable_key_set