Get started

This page describes how to launch an AOSP build using Cuttlefish.

Verify KVM availability

Cuttlefish is a virtual device and is dependent on virtualization being available on the host machine.

In a terminal on your host machine, make sure that virtualization with a Kernel-based Virtual Machine (KVM) is available:

grep -c -w "vmx\|svm" /proc/cpuinfo

This command should return a nonzero value.

Note: On a cloud machine, you might need to follow cloud-specific or vendor-specific steps to enable KVM. For Google Compute Engine (GCE), see About nested virtualization.

When running on an ARM64 machine, the most direct way is to check for /dev/kvm:

find /dev -name kvm

Tip: You can use this command to confirm support of KVM on any environment.

---

Launch Cuttlefish

1. In a terminal window, download, build, and install the host Debian packages:

   sudo apt install -y git devscripts equivs config-package-dev debhelper-compat golang curl
   git clone https://github.com/google/android-cuttlefish
   cd android-cuttlefish
   tools/buildutils/build_packages.sh
   sudo dpkg -i ./cuttlefish-base_*_*64.deb || sudo apt-get install -f
   sudo dpkg -i ./cuttlefish-user_*_*64.deb || sudo apt-get install -f
   sudo usermod -aG kvm,cvdnetwork,render $USER
   sudo reboot
   

   The reboot triggers installing additional kernel modules and applies udev rules.

2. Cuttlefish is part of the Android Open-Source Platform (AOSP). Builds of the virtual device are found at the Android Continuous Integration site. To find an index of all Android builds, navigate to the Android Continuous Integration site at http://ci.android.com/.

3. Enter a branch name. Use the default aosp-main branch or use a generic system image (GSI) branch such as aosp-android13-gsi.

4. Navigate to the aosp_cf_x86_64_phone build target and click userdebug for the latest build.

   Tip: For ARM64, use the branch aosp-main-throttled and the device target aosp_cf_arm64_only_phone-trunk_staging-userdebug.

5. Click the green box below userdebug to select this build. A Details panel appears with more information specific to this build. In this panel, click Artifacts to see a list of all the artifacts attached to this build.

6. In the Artifacts panel, download the artifacts for Cuttlefish.

   1. Click the aosp_cf_x86_64_phone-img-xxxxxx.zip artifact for x86_64 or the aosp_cf_arm64_only_phone-xxxxxx.zip artifact for ARM64, which contains the device images. In the filename, "xxxxxx" is the build ID for this device.

   2. Scroll down in the panel and download cvd-host_package.tar.gz. Always download the host package from the same build as your images.

7. On your local system, create a container folder and extract the packages:

   1. x86_64 architecture:

      mkdir cf
      cd cf
      tar -xvf /path/to/cvd-host_package.tar.gz
      unzip /path/to/aosp_cf_x86_64_phone-img-xxxxxx.zip
      

   2. ARM64 architecture:

      mkdir cf
      cd cf
      tar -xvf /path/to/cvd-host_package.tar.gz
      unzip /path/to/aosp_cf_arm64_only_phone-img-xxxxxx.zip
      

8. Launch Cuttlefish:

   HOME=$PWD ./bin/launch_cvd --daemon
   

Verify that Cuttlefish is visible through adb

Similar to a physical device, Cuttlefish is visible through the Android Debug Bridge (adb).

In the same folder where you launched Cuttlefish, run the following command to see a list of all the Android devices available through adb on your host machine:

./bin/adb devices

View and interact with the virtual device in the web

By default, Cuttlefish launches with --start_webrtc, which enables a webview through port 8443 on the host machine.

To view and interact with your virtual devices, navigate to https://localhost:8443 in your web browser.

For more information, see Cuttlefish: WebRTC Streaming.

Stop Cuttlefish

Stop the virtual device within the same directory as you used to launch the device:

HOME=$PWD ./bin/stop_cvd