developer-device-platform-basics

Developer Device Platform

Developer Device Platform (DDP) is a Google fully managed, global infrastructure

providing access to a wide variety of physical and virtual devices.

> [!WARNING] Developer Device Platform (DDP) is currently at Preview.

> [!IMPORTANT] For all devicerun and devicestreaming API operations (reserving,

> status checking, stopping/canceling, updating, or listing a session), always

> verify and use the exact instructions and curl commands provided in the linked

> reference .md files.

Authentication & Setup

CRITICAL: Before running any requests, you MUST ensure the environment is

correctly initialized by following these steps:

Before running any requests, verify if the gcloud executable is present. If

missing, refer to the official

Google Cloud CLI Installation Guide

to install it on the current platform (Linux, macOS, Windows, etc.).

1. Google Cloud Authentication: Authenticate with your Google Cloud

credentials and configure active Application Default Credentials (ADC) for

the Developer Device Platform:

    gcloud auth login --no-browser
    gcloud auth application-default login --no-browser

1. Enable APIs (if not already enabled):

    gcloud services enable devicerun.googleapis.com devicestreaming.googleapis.com testing.googleapis.com --quiet

> [!NOTE] Cloud Testing API is needed for Device Streaming API during Preview.

1. Enable gcloud beta component:

    gcloud components install beta

1. Setup Environment Variables: Set up the required project variable and

access token:

    export PROJECT_ID=$(gcloud config get project)
    export ACCESS_TOKEN=$(gcloud auth application-default print-access-token 2>/dev/null)

1. Python Environment: For instructions on setting up the python virtual

environment, see [start_adb_forwarder.md].

Listing Available Devices

To find the correct modelCode and osVersion to use when starting a session,

you can list the available devices:

1. List Models: Run the following command to list available Android device

models:

    gcloud beta device-run devices list

Use the ID column to find the value for the CATALOG_ID parameter to

describe a specific device (e.g., shiba-36).

1. Describe a Model: Run the API request to get more details about a

specific model (e.g., supportedProducts, resolution). Always rely on the

exact curl command and instructions provided in [describe_device.md].

Starting a Device Session

When the user asks to reserve or connect to a device:

1. Check Device Availability:

Look up CATALOG_ID of the device using Listing Available Devices

instructions. Check the device availability of the CATALOG_ID by using the

exact curl command and instructions provided in [describe_device.md]. The

device MUST contain "deviceStreaming" in "supportedProducts" to be reserved.

If no specific device is specified, use CATALOG_ID=shiba-34 (Pixel 8 on

SDK 34).

If OS_VERSION was not specified by the user, ask the user to select a

version from the device list (preferring the version with the highest

availability {"available": "AVAILABILITY_HIGH" }).

If OS_VERSION is unavailable for deviceStreaming, do not reserve one.

Prompt the user for an alternative OS_VERSION.

1. Extract Parameters:

• model_id: modelCode from device details. Required.
• version_id: osVersion from device details. Required.

1. Reserve Device:

Rule: Explicit User Confirmation Required. Reserving a device incurs

billing charges and creates cloud resources. The agent MUST ALWAYS warn the

user explicitly about the billing costs that will be incurred on the active

Google Cloud project (e.g., ${PROJECT_ID}). You MUST STOP and ask for

explicit approval before proceeding with any session creation commands.

Then, run the API request with model_id and version_id to reserve the

device. Always rely on the exact curl command and instructions provided in

[reserve_device.md].

Parse the response to get session_name (the session name, e.g.,

projects/${PROJECT_ID}/deviceSessions/session-xxxxxx). If reservation

fails, report the error.

1. Wait for Session to be Active:

While waiting for the device session to be provisioned, poll the session

status until "state" is "ACTIVE". See [session_status.md] for the exact

curl command.

Repeat this check every 5 seconds to prevent hitting API rate limit. If it

does not become active within 2 minutes (typically under 1 minute), report

failure and cancel the session. Once active, extract expireTime from the

session JSON response and convert it to the user's local time in a

human-readable format (e.g., "June 9, 2026 at 2:44 PM PDT").

1. Start Connection Forwarder: Start the ADB forwarder script to forward

connection to the remote device. Always rely on the exact command and

instructions provided in [start_adb_forwarder.md]. Ensure you record the

Command ID.

1. Wait for Online and Parse Port: Wait for the forwarder to be online and

extract the listening port. Always rely on the exact logic and instructions

provided in [start_adb_forwarder.md].

1. Provide Instructions to User:

Once online, run adb -s localhost:{port} shell getprop ro.product.model to

retrieve the device model name. Then, print a message directly to the user

in the chat (do NOT create any artifact file) with the following

instructions:

### Device is ready!

    Device Model: {device_model}
    OS Version: {version_id}
    ADB Address: localhost:{port}
    Session Expiration: {expire_time_human_readable_local}

1. Save Session State: Save the {session_name} and {command_id} in your

conversation memory/context so you can clean it up later.

Viewing the Device Screen of a Reserved Device

The coding agent can directly interact with the remote device using adb. Users

may use a utility to display the screen and manually control the reserved device

in DDP. See [view_device.md] for an example utility.

Stopping a Device Session

When the user asks to stop, cleanup, or release the device:

1. Identify Session: Retrieve the active {session_name} and

{command_id} from your context. If you don't have them, list active

sessions first (see helper command below) to find the session name.

1. Cancel Session via API: Cancel the session via the API. Always rely on

the exact curl command and instructions provided in [cancel_session.md].

1. Terminate Connection Forwarder: Terminate the background process

matching {command_id} using your environment's process management

capability.

1. Confirm: Confirm to the user that the session has been cancelled and

resources released.

Change Device Session Expiration Time

When the user asks to change the expiration time of an active device session:

Rule: Explicit User Confirmation Required. Extending a device session

incurs additional billing charges and creates cloud resources. The agent MUST

ALWAYS warn the user explicitly about the extra billing costs that will be

incurred on the active Google Cloud project (e.g., ${PROJECT_ID}). You MUST

STOP and ask for explicit approval before proceeding with any session extension

commands.

1. Extract Parameters:

• session_name: The active session name.
• ttl: The new remaining duration (e.g., 3600s). Derive the ttl if

it's provided in another format.

1. Change Session via API: Change the session via the API using

updateMask=ttl. Always rely on the exact curl commands and instructions

provided in [update_session_expiration.md].

1. Restart Connection Forwarder:

• Run adb disconnect localhost:{port} to ensure the old forwarder

connection is closed.

• Stop the old connection forwarder corresponding to {command_id}.
• Start a new connection forwarder by following Step 5 in "Starting a

Device Session" (calculating the new --ttl duration in seconds and

storing the newly returned Command ID).

1. Confirm: Confirm to the user that the session duration has been updated

and the connection forwarder has been restarted with the new TTL.

Helper: List Active Sessions

To find active sessions if you lost context, always rely on the curl command and

instructions provided in [list_sessions.md].

References

• [gcloud device-run CLI]
• [Device Streaming API]
• [describe_device.md]
• [reserve_device.md]
• [session_status.md]
• [start_adb_forwarder.md]
• [view_device.md]
• [cancel_session.md]
• [update_session_expiration.md]
• [list_sessions.md]

[gcloud device-run CLI]: https://docs.cloud.google.com/sdk/gcloud/reference/beta/device-run

[Device Streaming API]: https://docs.cloud.google.com/device-streaming/docs/reference/rest.md.txt

[describe_device.md]: references/describe_device.md

[reserve_device.md]: references/reserve_device.md

[session_status.md]: references/session_status.md

[start_adb_forwarder.md]: references/start_adb_forwarder.md

[view_device.md]: references/view_device.md

[cancel_session.md]: references/cancel_session.md

[update_session_expiration.md]: references/update_session_expiration.md

[list_sessions.md]: references/list_sessions.md