Google is committed to advancing racial equity for Black communities. See how.

Cuttlefish: Multi-tenancy and Powerwashing

Cuttlefish multi-tenancy allows for your host machine to launch multiple virtual guest devices with a single launch invocation.

These multiple Cuttlefish virtual machines can share some of the host disk resources, allowing you to conserve disk space. Each virtual machine gets a distinct disk overlay covering the Android partitions (such as super, userdata, boot). Any modification to the guest disk is placed in a guest-specific disk overlay, giving each Cuttlefish virtual machine a copy-on-write view of its disk partitions. As each virtual device writes more data to its view of the disk, the overlay files on the host disk increase in size because they're capturing the delta between the original state and their current state.

The overlay files can be reset to return the Cuttlefish disk to its original state. This process is known as powerwashing.

Instance numbers

Cuttlefish devices create and consume resources on the host tied to their instance number. For example, an adb connection is exposed through a TCP server socket at port 6520 for the Cuttlefish device with instance number 1. When multiple instances are launched, it creates a TCP server socket at port 6520 for the first device, 6521 for the second device, and increments the port number for each additional device.

Modifying maximum number of supported instances

Host-side resources, such as TAP network devices, must be preallocated for Cuttlefish virtual machines. By default, the cuttlefish-common Debian package provisions resources for instance numbers 1 through 10.

This can be changed through modifying num_cvd_accounts in /etc/default/cuttlefish-common and restarting the cuttlefish-common service by running the following command:

sudo systemctl restart cuttlefish-common

Controlling multi-tenant instances

This section describes how to start, stop, and powerwash devices. This applies to both single-tenant and multi-tenant launch_cvd invocations.

Starting

To launch multiple Cuttlefish devices at once, use the --num_instances=N flag, where N is the number of devices to launch. By default, devices starts from the instance number 1.

launch_cvd --num_instances=N

To change the starting instance number, do one of the following:

  • Add the --base_instance_num=N flag with N as the first instance number.

    launch_cvd --base_instance_num=N
    
  • Launch Cuttlefish with a user account matching vsoc-NN, where NN is the base instance number in two digit form. For example, to launch Cuttlefish with a user account vsoc-01, run:

    launch_cvd --base_instance_num=1
    

Stopping

To stop all the devices launched by the last launch_cvd invocation, run:

stop_cvd

Powerwashing

To start the device in its original state (state from build), add the --resume=false flag with the launch_cvd command.

// Launch and interact with your devices
launch_cvd --num_devices=N --daemon
// Stop all your devices
stop_cvd
// Restart devices in their original states
launch_cvd --daemon --num_devices=N --resume=false