Cuttlefish packages the host side of Google's Android virtual device

This repository is the host side, not the device

This repository holds supporting tools that prepare a host to boot Cuttlefish, which is a configurable Android Virtual Device (AVD) that targets both locally hosted Linux x86/arm64 and remotely hosted Google Compute Engine (GCE) instances rather than physical hardware.

That distinction is the thing to hold on to. Cuttlefish itself is an AOSP project, and this repository is the Debian packaging and host tooling around it. The repository description says it plainly: Cuttlefish host support debian package.

The reason the split exists is that a virtual device is only half the problem. A device that boots is useful; a device you can attach a debugger to, snapshot, restore, drive from a browser and script in CI is what platform development actually needs, and that host side is what this repository packages.

The target platforms are Linux x86 and arm64 locally, and GCE remotely. Notably absent are macOS and Windows, which is where the standard Android emulator lives, and that difference shapes who uses this. The QEMU-based Android emulator is a GUI application you point at an APK. Cuttlefish is closer to a real device that happens to be virtual, and it is the vehicle for testing system-level behaviour, permissions, boot-time behaviour and hardware integration, which is what the host tooling here is built to support.

The project is C++, with a last push on 2026-10-20 and tagged releases v1.57.0, v1.55.4 and v1.55.3 in August 2026. The licence field reads Other, a custom licence GitHub cannot classify, pointing to the LICENSE file.

Five packages, and one of them is on its way out

The package list is the clearest description of what each piece does.

`cuttlefish-base` creates the static resources needed by the Cuttlefish devices, so it is the core of the system. `cuttlefish-user` provides a local web server that enables interactions with the devices through the browser, which is the piece that turns a set of virtual devices into something you can click on and drive. `cuttlefish-integration` installs additional utilities to run Cuttlefish in Google Compute Engine.

`cuttlefish-orchestration` replaces `cuttlefish-user` in the Orchestration project at github.com/google/cloud-android-orchestration, so there are two mutually exclusive ways to run the same devices: locally with the browser server, or through a fleet management layer.

And `cuttlefish-common` is marked DEPRECATED, provided for compatibility only, and is a metapackage that depends on `cuttlefish-base` and `cuttlefish-user`. The deprecation is worth noting because it means an existing script somewhere probably still installs it, and it will pull in the pair of packages that the newer setups install directly.

For an install decision the practical guidance from the documentation is that Cuttlefish requires only `cuttlefish-base` to be installed, but `cuttlefish-user` is recommended to enjoy a better user experience. So the minimum is one package and the comfortable setup is two or three.

Installing from Artifact Registry needs the apt signing key

The packages are published on Google's Artifact Registry, and registering the repository takes four commands.

First the signing key, fetched and written into the trusted key directory:

sudo curl -fsSL https://us-apt.pkg.dev/doc/repo-signing-key.gpg \
    -o /etc/apt/trusted.gpg.d/artifact-registry.asc
sudo chmod a+r /etc/apt/trusted.gpg.d/artifact-registry.asc

Then the source list entry, appended rather than written so a rerun does not clobber an existing file:

echo "deb https://us-apt.pkg.dev/projects/android-cuttlefish-artifacts android-cuttlefish main" \
    | sudo tee -a /etc/apt/sources.list.d/artifact-registry.list
sudo apt update

And then the install:

sudo apt install cuttlefish-base cuttlefish-user cuttlefish-orchestration

One detail in that documentation is easy to skim past. Only `cuttlefish-base`, `cuttlefish-user` and `cuttlefish-orchestration` are deployed to Artifact Registry. The other two packages, `cuttlefish-integration` and the deprecated `cuttlefish-common`, are not published there, so an install from the registry cannot give you the GCE integration utilities, and a script that expects all five will fail partway.

The consequence for automation is that a machine provisioned from Artifact Registry can boot a local device with the browser interface and can be orchestrated, but the GCE integration path needs a different source.

Building from source ends with a reboot and three group memberships

The manual build path exists for people working from a source checkout rather than from the registry.

The packages are built with a single script:

tools/buildutils/build_packages.sh

And then installed with the local debs and the group setup:

sudo apt install ./cuttlefish-base_*.deb ./cuttlefish-user_*.deb
sudo usermod -aG kvm,cvdnetwork,render $USER
sudo reboot

The last two commands are the interesting ones, and the reason for the reboot is stated: they add the user to the groups necessary to run the Cuttlefish Virtual Device and reboot the machine to trigger the installation of additional kernel modules and apply udev rules.

So the three group names tell you what the device needs from the host. `kvm` is hardware virtualisation access, `render` is the graphics group, and `cvdnetwork` is a group Cuttlefish creates for its own networking. The kernel modules and udev rules are what make the device's virtual network interfaces appear with the right ownership.

The reboot is not optional, and that is worth flagging for anyone provisioning machines automatically. Group membership changes do not apply to a running session, and the modules and rules are installed during boot, so a script that installs the packages and then immediately tries to boot a device will fail in a way that looks like a permissions problem.

The same device runs on cloud images and on Gigabyte ARM hardware

Beyond the local Debian packages, the repository carries the other two ways people run Cuttlefish, and they are the reason the tree is as large as it is.

For Google Compute Engine, a script can be used to build a host image, and it is in the AOSP tree at device/google/cuttlefish/tools/create_base_image.go, with a link to the Android source download page to obtain the script. The point of a purpose-built host image is that a virtual device can be started and stopped in the cloud on demand, which is what makes fleet-scale testing of Android system behaviour practical rather than merely possible.

The top-level entries also show dedicated installer directories for Gigabyte hardware: `gigabyte-ampere-cloud-installer/`, `gigabyte-ampere-cuttlefish-installer/` and `cuttlefish-integration-gigabyte-arm64/`. Gigabyte makes ARM servers, and Ampere is the ARM architecture, so the naming is telling: this is the path for running Cuttlefish on ARM server hardware rather than on x86.

That combination, a virtual device running on real ARM silicon, is the configuration that matters for a class of problem where an x86 emulator will not do, because the thing under test is the interaction with the hardware.

The rest of the tree is the surrounding infrastructure. There is a cloud-init-image-for-cuttlefish/ directory for machine initialisation, a container/ directory with its own README explaining how to build and use a Docker or Podman image containing the Cuttlefish Debian packages, an e2etests/ directory, a staging/ directory, a skills/ directory, and the frontend/ directory for the web interface. The build is Bazel, with BUILD.bazel at the root, and there is a .kokoro/ directory for continuous integration.

Editorial conclusion

Adopt these packages if you are working on Android platform code and need a virtual device you can boot, snapshot and script on a local Linux host, because the Cuttlefish workflow gives you a device you can restart in seconds rather than a physical handset. Skip it if you need an emulator with a GUI on macOS or Windows, since the packages are Debian packages and the device targets locally hosted Linux x86 or arm64 and GCE instances. Verify first that your host has the kvm, cvdnetwork and render groups set up, since the install instructions add your user to them and require a reboot, and that you can reach the Artifact Registry, because only three of the five packages are published there.

Frequently asked questions

Official sources

1. google/android-cuttlefish on GitHub
2. Issues
3. Project website
4. README
5. Releases