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.).

Google Cloud Authentication: Authenticate with your Google Cloud credentials and configure active Application Default Credentials (ADC) for the Developer Device Platform:
bash
```
gcloud auth login --no-browser
gcloud auth application-default login --no-browser
```

Enable APIs (if not already enabled):

bash

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.

Setup Environment Variables: Set up the required project variable and access token:

bash

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

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:

List Models: Run the following command to list available Android device models:
bash
```
gcloud alpha 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
```
).
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:

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
```
.
Extract Parameters:
- ```
model_id
```
  :
```
modelCode
```
  from device details. Required.
- ```
version_id
```
  :
```
osVersion
```
  from device details. Required.
Reserve Device:

Rule: Explicit User Confirmation Required. Reserving a device incurs billing charges and create cloud resources. The agent MUST ALWAYS warn the user explicitly about the potential extra billing costs. 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.
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").
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.
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.
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}
```
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:

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.
Cancel Session via API: Cancel the session via the API. Always rely on the exact curl command and instructions provided in cancel_session.md.
Terminate Connection Forwarder: Terminate the background process matching
```
{command_id}
```
using your environment's process management capability.
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 create cloud resources. The agent MUST ALWAYS warn the user explicitly about the potential extra billing costs. You MUST STOP and ask for explicit approval before proceeding with any session extension commands.

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.
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.
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).
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

developer-device-platform-basics

NPX Install

Tags

SKILL.md Content