DOCSEARCHbyAlgolia
Submit Docs

Android Cuttlefish Documentation

repository·main·Indexed 20 days ago

https://github.com/google/android-cuttlefish

Host-side utilities for preparing Linux hosts to boot configurable Android Virtual Devices (AVDs). Includes documentation on the Cuttlefish CLI (cvd), host filesystem setup via assemble_cvd, device lifecycle management with run_cvd and cvd_internal_start, and specialized components like the gnss_grpc_proxy for location data, secure_env for TEE emulation, and WebRTC browser endpoints for display streaming. Also covers building and deploying Cuttlefish via Bazel, Docker, and Podman.

Tokens
127.9K
Snippets
351
Records
550
Agent score
71%

What's inside Android Cuttlefish

  4. Overview of the GNSS gRPC Proxy service

    main

    The gnss_grpc_proxy is a virtual device location data manager that serves a gRPC interface. It is designed to manage and provide GNSS (Global Navigation Satellite System) location data to a Cuttlefish virtual device.

    End-users typically interact with this service through specialized client executables rather than calling the gRPC interface directly. The primary clients are:

    • cvd_import_locations: Used to import a sequence of location points into the service.
    • cvd_update_location: Used to set a new fixed location for the device.

  5. What is secure_env and when to use it

    main

    secure_env is a host process that acts as a substitute for a Trusted Execution Environment (TEE). It is used to run backing implementations of Android Hardware Abstraction Layers (HALs) that typically require a TEE environment.

    Specifically, it supports:

    • ConfirmationUI: The display component runs in the webRTC host process, which delegates signing operations to secure_env.
    • Gatekeeper: Communicates with secure_env via virtio-console channels connected to FIFO files on the host.
    • Keymint: Communicates with secure_env via virtio-console channels connected to FIFO files on the host.

    During the boot process, the u-boot bootloader writes device image information into the Keymint channel to prepare the environment with the authenticated version number of the operating system.

  6. How the Cuttlefish CLI architecture works

    main

    The Cuttlefish command-line interface (CLI) is architected as a split system consisting of a thin client and a persistent background server process. This server process is responsible for tracking user state.

    When a user executes a command via the client, the request is processed by handler classes. These handlers can implement complex workflows by delegating tasks to other handler classes using the CommandSequenceExecutor mechanism.

  7. How the ADB connector manages Cuttlefish device state

    main
    The ADB connector is responsible for managing the state of Cuttlefish devices within the ADB server. Because the ADB server does not automatically discover Cuttlefish devices, the ADB connector explicitly sends register and deregister messages to the ADB server. This ensures that the ADB server is correctly informed of when a Cuttlefish device becomes available or is removed, allowing standard ADB commands to interact with the virtual device.

  8. Execute podcvd commands in parallel

    main

    When performing bulk operations (e.g., "create 10 instances" or "remove groups A, B, and C"), you must execute commands in parallel by default to avoid severe performance degradation.

    Exceptions (Execute Sequentially):

    1. The user explicitly requests sequential execution.
    2. Operations target the exact same group_name (state dependency).
    3. The operation is a global command like clear.

  10. Understand the Cuttlefish CLI configuration structure

    main

    The Cuttlefish CLI configuration is organized into a hierarchical UI structure composed of various categories. These categories group related configuration parameters and classes, allowing users to manage different aspects of the virtual device through a structured interface.

    Key configuration categories include:

    • vm: Virtual Machine settings.
    • graphics: Display and rendering configurations.
    • adb: Android Debug Bridge settings.
    • streaming: Media and data streaming parameters.
    • disk: Storage and disk image configurations.
    • connectivity: Network and connection settings.
    • camera: Emulated camera configurations.
    • audio: Sound and audio output settings.
    • location: GPS and location emulation.
    • vehicle: Automotive/Vehicle-specific configurations.

  11. Manage Cuttlefish instance groups with podcvd

    main

    Use podcvd to orchestrate the lifecycle of Cuttlefish instances.

    Critical Rules:

    • Exclusive ADB Control: podcvd manages all ADB connections automatically. Do not use external ADB tools or MCP servers to connect to these instances, as it will cause system conflicts.
    • Isolation from cvd: podcvd and standard cvd do not share state. Do not mix them. Instances created with cvd will not appear in podcvd fleet, and vice versa.
    • Group Management: When running podcvd create, you must capture the returned "group_name" from the JSON response. This name is required for subsequent operations like stop, start, or remove using the --group_name=<group_name> flag.
    • Boot Latency: Booting/starting instances takes ~1 minute. During this time, status will be "Starting". Wait for the status to transition to "Running" via podcvd fleet before attempting to use ADB or performing teardown operations.
    PODCVD_CLIENT_ID="<client_id>" podcvd create --vhost_user_vsock=true --report_anonymous_usage_stats=n

  12. Download the Gigabyte Ampere Cuttlefish image

    main

    You can download the Debian installer image from the Google Artifact Registry. Use the ARM_OS_IMAGE_VERSION environment variable to specify the desired version (e.g., unstable). The image is downloaded as a compressed preseed-mini.iso.xz file.

    ARM_OS_IMAGE_VERSION=unstable # Modify the version if it's needed.
wget -O preseed-mini.iso.xz "https://artifactregistry.googleapis.com/download/v1/projects/android-cuttlefish-artifacts/locations/us/repositories/gigabyte-ampere-server-installer/files/debian-installer:${ARM_OS_IMAGE_VERSION}:preseed-mini.iso.xz:download?alt=media"