Flashing GrapheneOS

GRAPHENEOS INSTALLATION & SETUP MANUAL

Classification: Technical End-User Documentation

Target Hardware: Google Pixel Series (Carrier-Unlocked)

1. System Overview & Safety Warnings

This document provides definitive instructions for performing a bare-metal installation of GrapheneOS onto a supported target hardware device using the WebUSB Web Installer interface.

CRITICAL DATA LOSS WARNING: Unlocking the device bootloader triggers an immediate hardware-level cryptographic key wipe of the storage controller (/data partition). All saved files, accounts, certificates, photos, and installed applications will be permanently unrecoverable. Ensure all critical assets are backed up to an off-device medium before initiating this process.

HARDWARE INTEGRITY NOTICE: Interrupting the system write process during bootloader, baseband, or low-level partition flashing can result in an unrecoverable device state ("bricking"). Observe all connection requirements below. Do not disconnect physical cabling, refresh browser sessions, or power down host/target systems until explicitly instructed by the software interface.

2. Technical Prerequisites & Compatibility Matrix

Before initiating the setup process, ensure both host and target environments satisfy all baseline technical parameters.

Target Hardware Constraints

• Device Lineup: Carrier-unlocked Google Pixel series hardware (Pixel 6 generation through current models).

  
  

• Carrier State: The target unit must be factory carrier-agnostic. Devices bound to specific mobile network operators (e.g., Verizon-locked variants) feature hard-locked bootloaders that explicitly restrict OEM unlocking capabilities.

  
  

• Firmware Baseline: Ensure the device has been booted into stock Android and updated to the latest available vendor patch release prior to installation.

  
  

Host Machine Hardware & Environment

• Supported Host Operating Systems: Windows (10/11 x64), macOS (Sonoma/Sequoia), Linux (Debian 12+, Ubuntu 22.04+, Arch), ChromeOS, or secondary Android devices running Android 14+.

  
  

• System Memory: Minimum 2 GB available RAM.

  
  

• Storage Footprint: Minimum 32 GB free space on the host OS primary storage drive (required for temporary payload decompression).

  
  

• Environment Restriction: Do not use Virtual Machines (VMs). Virtualized pass-through architectures introduce latency and USB descriptor resets that break WebUSB operation.

  
  

Browser & Interconnect Requirements

• Browser Engines: Chromium-based browsers only (Google Chrome, Microsoft Edge, Brave with Shields explicitly disabled, or Vanadium).

  
  

  • Incompatible Browsers: Mozilla Firefox and Apple Safari (lack WebUSB protocol support).

    
    

  • Incompatible Packages: Snap or Flatpak packaged browsers (sandbox restrictions block raw USB access). Incognito/Private modes are unsupported due to restricted quota storage APIs.

    
    

• Physical Cabling: Use a direct USB-C to USB-C connection using a high-quality, data-compliant cable. Avoid USB hubs, external docking stations, front-panel PC chassis headers, and passive extension lines.

  
  

3. Pre-Installation Configuration

Perform these preliminary configuration steps on the target phone prior to physical connection.

1.Enable Developer Options:Unlocks low-level system configuration menus.

1. Turn on the target phone and boot into the stock Android operating system.

   
   

2. Open the Settings application.

   
   

3. Scroll down and tap About phone.

   
   

4. Scroll to the bottom to locate Build number.

   
   

5. Tap Build number rapidly 7 consecutive times.

   
   

6. Enter your current device PIN or passcode when prompted. The interface will display a message: "You are now a developer!"

   
   

2.Enable OEM Unlocking:Requires active internet connection.

1. Connect the phone to a Wi-Fi network or active cellular data link (required to validate bootloader status with Google servers).

   
   

2. Navigate to Settings > System > Developer options.

   
   

3. Locate the toggle switch labeled OEM unlocking.

   
   

4. Toggle the switch to the ON position.

   
   

5. Enter your device lock PIN/password and confirm the popup warning.

   
   

Troubleshooting Note: If "OEM unlocking" is grayed out, restart the device, re-establish internet connectivity, open the Chrome browser, navigate to a web page, and re-check the Developer options menu.

3.Boot into Fastboot Mode:Initializes hardware bootloader interface.

1. Power down the device completely.

   
   

2. Press and hold the Volume Down button and the Power button simultaneously.

   
   

3. Release both buttons when the screen powers on, displaying an open Android mascot with hardware text diagnostic overlay (Fastboot Mode screen).

   
   

4. Host System Setup & Connection Verification

1. Windows Host Preparation (Windows Only):

   Windows requires standard WinUSB drivers for the Fastboot interface. Connect the phone in Fastboot Mode to the PC. Open Device Manager. If an item named Android appears under Other devices with a yellow exclamation mark:

   
   

   • Right-click Android and select Update driver.

     
     

   • Choose Search automatically for drivers or install the official Google USB Driver via Windows Update (Optional Updates).

     
     

2. Linux Host Preparation (Linux Only):

   Ensure your local user account has permission to access USB devices without root execution.

   On Debian/Ubuntu-based systems, install the udev rules by running:

   
   

   Bash

   sudo apt update && sudo apt install android-sdk-platform-tools-common

5. System Installation Procedure

Ensure the target phone is connected directly to the host computer using your USB-C cable and remains on the Fastboot Mode screen.

Step 1: Establish Link & Unlock Bootloader

1. Open your Chromium-based browser on the host machine and navigate to:

   [https://grapheneos.org/install/web](https://grapheneos.org/install/web)

   
   

2. Scroll to the Unlocking the bootloader section and click the Unlock bootloader button.

   
   

3. A browser permissions pop-up will appear. Select the device entry labeled Android Bootloader Interface (or your device model codename) and click Connect.

   
   

4. Observe the target phone's physical screen. The display will change from the standard Fastboot screen to a red/yellow warning confirmation screen.

   
   

5. Use the physical Volume Up or Volume Down buttons on the side of the phone to toggle the selection to Unlock the bootloader.

   
   

6. Press the physical Power button once to execute the selection.

   
   

7. The device will perform an automated key purge and reboot back into Fastboot Mode.

   
   

Step 2: Download System Firmware Payload

1. On the Web Installer interface, navigate to the Obtaining factory images section.

   
   

2. Click Download release.

   
   

3. The Web Installer will automatically detect your device model codename (e.g., tokay, comet, cheetah) and download the verified, signed factory image payload archive to your browser cache.

   
   

4. Wait for both the Download and Unpacking/Verification status bars to reach 100%.

   
   

Step 3: Flash System Firmware to Partitions

1. Scroll down to the Flashing factory images section on the Web Installer page.

   
   

2. Click Flash release.

   
   

3. CRITICAL: Do not touch the physical cable, close the browser, or interact with the phone during writing.

   
   

4. The installation script will write the bootloader, radio, vendor, baseband, and core partitions (system, system_ext, product, vendor_dlkm).

   
   

5. Expected Interface Behavior: During this phase, the phone will automatically reboot out of standard Fastboot Mode into FastbootD Mode (indicated by a blue screen listing hardware details).

   
   

6. Re-connection Prompt: If the browser displays a prompt stating that connection was lost, click Connect, select the target device from the list (it may now appear as FastbootD or Pixel), and confirm to resume partition flashing.

   
   

7. Process completes when the web terminal log displays: Flashing completed successfully.

   
   

6. Hardware Bootloader Relocking & Security Provisioning

MANDATORY SECURITY STEP: Operating GrapheneOS with an unlocked bootloader disables hardware-level cryptographic isolation, breaks Hardware Security Module (HSM) attestation, and disables Android Verified Boot (AVB). You must relock the bootloader to establish GrapheneOS's custom root key as the trust anchor.

1.Execute Lock Request:Initiated from host interface.

1. On the Web Installer browser page, scroll to the Locking the bootloader section.

   
   

2. Click the Lock bootloader button.

   
   

3. A WebUSB browser prompt will appear. Select your device and click Connect.

   
   

2.Hardware Confirmation:Executed on target phone hardware.

1. The target phone screen will switch to a confirmation menu reading "Do not lock the bootloader".

   
   

2. Press the physical Volume Down button once to highlight Lock the bootloader.

   
   

3. Press the physical Power button to confirm.

   
   

4. The device will wipe its cache state once more and return to the primary Fastboot Mode menu.

   
   

3.First System Initialization:Verifying cryptographic trust anchor.

1. On the phone's Fastboot menu, ensure Start is highlighted at the top of the screen.

   
   

2. Press the Power button to boot the OS.

   
   

3. The device will show a yellow boot screen displaying the text: "Your device is loading a different operating system..." along with the GrapheneOS root key fingerprint. This is normal behavior indicating Verified Boot is enforcing your custom OS installation.

   
   

4. The device will initialize and present the GrapheneOS First-Time Setup Wizard.

   
   

7. Post-Installation Hardening & Cleanup

Complete these final configuration adjustments after finishing the OS First-Time Setup Wizard to seal system security boundaries:

1. Open Settings > System > Developer options.

   
   

2. Locate OEM unlocking and toggle the setting to OFF.

   
   

3. Scroll to the top of the menu and toggle Use developer options to OFF.

   
   

4. Disconnect the USB-C cable from the target phone.

   
   

5. Reboot the device (Settings > Power options > Restart) to confirm clean boot execution under hardened state.

8. Diagnostic & Troubleshooting Matrix

Error Code / Symptom	Primary Cause	Technical Resolution Procedure
Claiming interface failed	Host OS has another process bound to the USB port (e.g., active background adb server instance).	Open host terminal/command prompt and run adb kill-server. Close software like Android Studio or device management suites. Restart host browser.
Failed to allocate memory / Browser Crash	Storage quota exhaustion due to browser sandbox limits or insufficient system RAM.	Ensure browser is not running in Private/Incognito mode. Free up at least 32 GB of space on the primary system drive (C: for Windows / / for Linux).
Device stuck on FastbootD screen with failed write message	Interrupted data transmission via unstable cable or unbuffered USB hub.	Re-seat connection using a direct mother-board port. Click Flash release on the Web Installer again to resume payload delivery from the failed partition state.
Red Boot Warning / Your device has failed verification	Firmware partition image flash was corrupted prior to attempting a bootloader lock.	Do not lock bootloader. Return to Fastboot mode (Volume Down + Power), execute Unlock bootloader, re-download factory images, and repeat Section 5 payload flashing.