cvdr

This page describes cvdr and its usage.

What's cvdr?

cvdr is a CLI binary tool for accessing and managing Cuttlefish instances remotely. It wraps Cloud Orchestrator, to provide user-friendly interface.

Install and Configure cvdr

Debian Prebuilt Packages

cuttlefish-cvdremote is available to download via apt install with adding the apt repository at Artifact Registry:

sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://us-apt.pkg.dev/doc/repo-signing-key.gpg -o /etc/apt/keyrings/android-cuttlefish-artifacts.asc
sudo chmod a+r /etc/apt/keyrings/android-cuttlefish-artifacts.asc
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/android-cuttlefish-artifacts.asc] \
  https://us-apt.pkg.dev/projects/android-cuttlefish-artifacts android-cuttlefish-unstable main" | \
  sudo tee /etc/apt/sources.list.d/android-cuttlefish-artifacts.list > /dev/null
sudo apt update
sudo apt install cuttlefish-cvdremote
cvdr --help

To configure, modify the configuration file:

• System-level configuration is defined in /etc/cvdr.toml

• User-level configuration is defined in ~/.config/cvdr/cvdr.toml and takes precedence

Manual Build

To build cvdr manually, please run:

git clone https://github.com/google/cloud-android-orchestration.git
cd cloud-android-orchestration # Root directory of git repository
go build ./cmd/cvdr

The cvdr binary will be produced in the cloned repository.

To configure cvdr, you have to provide a configuration file by setting either CVDR_SYSTEM_CONFIG_PATH or CVDR_USER_CONFIG_PATH environment variable.

To create a convenient alias, please run or add to ~/.bashrc:

export CVDR_USER_CONFIG_PATH=/path/to/cvdr.toml
alias cvdr="$(realpath ./cvdr)"

Examples

See either build/debian/cuttlefish_cvdremote/host/etc/cvdr.toml or scripts/on-premises/single-server/cvdr.toml as examples of how to write a configuration file.

Create CVD

Latest Cuttlefish x86_64 Image

To launch with the latest image enrolled in ci.android.com, please run:

cvdr \
--branch=aosp-main \
--build_target=aosp_cf_x86_64_phone-trunk_staging-userdebug \
create

Custom AOSP build

Assuming you build AOSP from scratch, ensure you run lunch $MY_BUILD_TARGET with your target before proceeding, see Build Android for more details.

To create an instance using the build artifacts from your local AOSP repo, please run with your working directory being your AOSP root:

cvdr create --local_image

Alternatively, manually specify the images and create an instance:

cvdr --local_cvd_host_pkg_src="${ANDROID_PRODUCT_OUT}/dist/cvd-host_package.tar.gz --local_images_zip_src=${ANDROID_PRODUCT_OUT}/dist/your-target-img.zip"

For this to work, you have to build the .zip images using m dist in AOSP root beforehand.

On success, we expect the result like below.

Creating Host........................................ OK
Fetching main bundle artifacts....................... OK
Starting and waiting for boot complete............... OK
Connecting to cvd-1.................................. OK
2e8137432a96f93558c838da5e590ec775a97e5a7bb20e66929d1a59eb337351 (http://localhost:8080/v1/zones/local/hosts/2e8137432a96f93558c838da5e590ec775a97e5a7bb20e66929d1a59eb337351/)
  cvd/1
  Status: Running
  ADB: 127.0.0.1:33975
  Displays: [720 x 1280 ( 320 )]
  Logs: http://localhost:8080/v1/zones/local/hosts/2e8137432a96f93558c838da5e590ec775a97e5a7bb20e66929d1a59eb337351/cvds/1/logs/

If you want to validate, please refer the first provided URL in the output log and check if the page seems like below. Also, you should be able to see the device is enrolled via adb devices.

Please run cvdr --help for advanced functionalities of cvdr, including individual commands and their flags, including how to manage or delete CVDs.