eip-pixel8a-forge

Turn a Pixel 8a into a self-contained CVE research device.

EIP CVEForge is an operator-controlled CVE research workbench: agents perform source review, build isolated labs, do bounded proof work, and prepare reviewed publication packages, with a human operator in control at every gate. This repository makes that entire system run on the phone itself.

The phone runs a real Docker Engine on a matched custom kernel - not an emulator, not a chroot, and not a thin client for a server somewhere else. Labs, agents, and the Forge WebUI all execute on the device; apart from installs and updates, the traffic leaving it is the model-provider calls you configure. You get a pocket-sized research host that works anywhere there is Wi-Fi, and that you can wipe back to stock Google firmware whenever you want a clean start.

This repository owns the Pixel host, installer, Forge Control Android app, and release packaging. Forge itself remains in eip-cve-public-v4 and is pinned here by FORGE_REVISION.

Start here: Supported phone | Install | Update | What gets installed | Important limits

Supported phone

Device	Google build	KernelSU-Next	Network
Pixel 8a (akita)	Android 17 CP2A.260805.005	3.3.0, LKM	Wi-Fi

Other phones and Android builds are not supported by this release.

Install

You need an unlocked bootloader, a USB cable, and a computer with adb, fastboot, curl, and unzip. The clean-install path erases the phone.

1. Download two files

Download and extract the latest installer bundle from this repository's Releases page.

Then open Google's official Pixel factory-image page, accept Google's terms, and download the factory ZIP for:

Pixel 8a (akita)
CP2A.260805.005

Keep the Google ZIP intact. You do not need to find or rename partition images yourself.

2. Prepare the Google firmware inputs

With the phone booted, USB debugging enabled, and this computer authorized:

./prepare-firmware.sh \
  --factory-zip ~/Downloads/akita-cp2a.260805.005-factory-*.zip \
  --serial ADB_SERIAL

The command extracts and verifies the exact Google boot images, downloads the pinned Docker and KernelSU-Next inputs, and creates the local KernelSU bootstrap image. Google firmware never enters this repository or its release assets.

3. Wipe the phone

Back up anything you need first. This command erases Android user data:

./install.sh --serial ADB_SERIAL --wipe

4. Finish Android setup and install Forge

Complete Android setup, connect to Wi-Fi, enable USB debugging, and authorize the computer again. Then run:

./install.sh --serial ADB_SERIAL

To install provider keys at the same time:

./install.sh \
  --serial ADB_SERIAL \
  --provider-env /path/to/providers.env

The provider file is ordinary NAME=value lines and stays outside the repository. For example:

OLLAMA_API_KEY=replace-me
OPENAI_API_KEY=replace-me
ANTHROPIC_API_KEY=replace-me
DEEPSEEK_API_KEY=replace-me
GLM_API_KEY=replace-me
OPENROUTER_API_KEY=replace-me

The Docker data image defaults to a sparse 64 GiB allocation. Use --disk-gib 16, --disk-gib 32, or --disk-gib 64 during a clean install when you deliberately want a different size.

Installation is complete only when the final line is:

READY

The installer prints the generated Forge WebUI username and password immediately before READY. Save the password for future logins. Open the Forge Control app on the phone, then tap Open Forge WebUI.

Update an existing installation

Download and extract the latest installer bundle, connect the already installed phone over USB, and run the same command:

./install.sh --serial ADB_SERIAL

The installer recognizes the existing system, downloads the exact public controller and operator image digests over the phone's Wi-Fi connection, waits for current Forge work to become idle, and updates with rollback. It preserves the Docker disk, Forge state, WebUI password, provider keys, and CVE data. Do not run prepare-firmware.sh, --wipe, or --disk-gib for an update.

When the payload module version differs from the installed one, the update parks Forge, reinstalls the module (fetching and hash-verifying the pinned Docker Engine archive when neither the bundle nor the phone holds it), and reboots. Every update and installation resume then proves the installed payload, with the overlay confined to the KernelSU module tree while the Docker daemon runs from the separately managed /data/docker release tree: the payload files are re-staged through a mode-preserving overlay, verified on the phone against a payload-built checksum manifest, and pruned of files the payload no longer contains. The verification exists because KernelSU's module update can preserve previously installed file bytes - observed as a fresh module.prop beside a stale bin/hostctl on a Pixel 11 Pro XL on 2026-09-15 - and a silent mismatch would leave boot-time module code running older behavior than the release claims.

What gets installed

• The matched Pixel kernel and native Docker host
• The controller image built from the pinned public Forge commit, pulled from GHCR by immutable digest
• The Pixel operator image and phone operations
• Forge Control for starting, parking, and inspecting the system
• The Forge WebUI and agent-chat service

New installations default Ollama to https://ollama.com; no local Ollama binary is installed. Local Ollama and every other Forge provider remain available through normal Forge configuration.

Source layout

• deployment/ contains the installer and package builder.
• eip/ contains Pixel-specific Forge and container glue.
• android-app/ contains Forge Control.
• module/, android/, and tools/ contain the native Pixel Docker host.
• kernel/ contains the qualified kernel recipe, configuration, and source identity.
• DEVICE.json records the exact firmware, source, boot, KernelSU-Next, and Docker identities qualified on the phone.

Run the source checks with:

tools/check.sh

Pull requests run the same checks, focused installer contracts, Android host contracts, image validation, and an independent code review.

Important limits

• The installer writes the active boot and init_boot partitions.
• Never use firmware from a different device or build.
• Keep the matching factory image available for fastboot recovery.
• Do not accept an Android OTA on an installed Forge phone. Return to the recorded build before reinstalling.
• Container networking is qualified over Wi-Fi only.
• Unlocking the bootloader and installing a custom kernel weaken the stock Android security model.

First-party source is MIT licensed. Kernel materials retain their upstream licenses. See NOTICE.md.