Developer Device Platform: Device Run
Device Run executes a job on remote DDP devices and returns its artifacts (logs,
pulled files) to a Cloud Storage bucket. One session fans out to one job per
requested device.
[!WARNING]
Developer Device Platform (DDP) is currently in Preview. The
gcloud beta device-run commands might change without notice.
When to use this skill
| The user wants to... |
Use |
| Run a native binary or shell script on remote devices |
This skill (android-executable) |
| Run an Android instrumentation test APK on remote devices |
This skill (instrumentation) |
| Reserve a device, connect with adb, stream the screen |
developer-device-platform-basics |
| Extend or cancel an interactive device lease |
developer-device-platform-basics |
| Work with a device connected over USB |
Neither (not DDP) |
The setup below is complete; this skill doesn't depend on another skill for
authentication, project selection or API enablement.
Requests this skill does not handle
For interactive use (reserve a device, adb, screen streaming, leases):
- If
developer-device-platform-basics is installed: do not submit a
Device Run session; switch to developer-device-platform-basics, and note
that interactive reservations are also billed to the active project.
- If
developer-device-platform-basics is not installed: reply in a
single message without calling any tools (no commands, searches, file
reads or scheduling), then stop:
- Say that Device Run is for non-interactive batch jobs, so you will not
submit a Device Run session.
- Point the user to an interactive Device Streaming reservation with the
developer-device-platform-basics skill (or
https://docs.cloud.google.com/device-streaming/docs/overview.md.txt),
and suggest installing the skill.
- Warn that an interactive reservation is also billed to the active
Google Cloud project.
Keep answers fast
Prefer this skill and gcloud beta device-run ... --help over broad web
searches for Device Run syntax. If gcloud or the beta component is not
installed, fall back to the official documentation at
https://docs.cloud.google.com/developer-device-platform/device-run.md.txt and
https://docs.cloud.google.com/sdk/gcloud/reference/beta/device-run. For dry
runs, show the commands instead of running them.
Usage Attribution
MUST READ: Before executing any gcloud, REST API, or MCP command, you
MUST read and follow the instructions in
Usage Attribution.
Setup
Run these checks once per environment. Do not assume tools are installed, and
do not install or update software without the user's approval.
gcloud CLI: Check that gcloud is installed and has Device Run commands:
gcloud --version
gcloud beta device-run sessions submit android-executable --help >/dev/null
If gcloud is missing, point the user to
https://docs.cloud.google.com/sdk/docs/install-sdk.md.txt. If the beta
component or the Device Run commands are missing, ask the user before
running gcloud components install beta or gcloud components update.
Authentication: Check the active account. On a Compute Engine or other
remote VM, the active account may be the VM's default service account
(...@...iam.gserviceaccount.com), which often lacks the scopes Device Run
and billing calls need (No service account scopes specified). If there is
no active account, or only such a service account, ask the user to sign in.
--update-adc also updates Application Default Credentials in the same
flow; add --no-launch-browser in SSH or remote terminals:
gcloud auth list --filter=status:ACTIVE --format="value(account)"
gcloud auth login --update-adc
Project: Use the user's active project, or the one they name. Never
hardcode a project, and don't change the active project without asking.
export PROJECT_ID=$(gcloud config get project)
# Only if the user asks to switch:
gcloud config set project PROJECT_ID
Billing: Device Run is billed to the project. Check that billing is
enabled; if it isn't, stop and tell the user.
gcloud billing projects describe "${PROJECT_ID}" \
--format="value(billingEnabled)"
Enable the Device Run API (if not already enabled; ask first):
gcloud services enable devicerun.googleapis.com --project="${PROJECT_ID}"
IAM roles: The user needs roles/devicerun.admin,
roles/serviceusage.serviceUsageConsumer and roles/viewer on the
project. To read inputs from a bucket in another project, grant the DDP
service agent roles/storage.objectViewer on that bucket (see
https://docs.cloud.google.com/developer-device-platform/device-run/share-storage.md.txt).
Bucket: Sessions store inputs and outputs in Cloud Storage. Without
--bucket-name, gcloud uses or creates gs://${PROJECT_ID}-devicerun.
For project IDs that contain :, . or google, gcloud replaces them
(with -, - and elgoog) before adding -devicerun; read the actual
bucket from the Result files URI printed by submit or describe. A
bucket named explicitly with --bucket-name MUST already exist. Pass the
bucket name only (no gs://, no path). Inputs and outputs under
gs://<bucket>/automation/ are kept until you delete them or a Cloud
Storage lifecycle rule expires them, and storage is billed meanwhile.
Core workflow
Pick devices. Users usually name devices the way they are sold ("Pixel
10", "Galaxy S22"), while --device needs a catalog ID such as
frankel-36 (codename + Android API level). Resolve names to IDs from the
live catalog with
device_selection.md; never guess an ID
from memory. If a device is offered on several Android versions and the
user didn't name one, list the versions, recommend one, and let the user
pick one, several (one job each) or all; never pick silently. Before
submitting, show the user the resolved ID, the device name and the Android
version, and call out any other choice you made for them (physical vs
virtual, variant).
Stage inputs. --executable, --test, --target-app and the source
side of --other-files-to-push accept gs:// paths or local paths. Local
files are uploaded automatically into a fresh
automation/inputs/<timestamp>/ folder, so prefer local paths for files
that change between runs (scripts, freshly built binaries). Upload large,
reused files (models, datasets) to the bucket once and reference them by
gs:// path.
Confirm cost. Explicit user confirmation required. Device Run
sessions are billed to the active Google Cloud project. Before submitting,
tell the user the project (${PROJECT_ID}), the devices, the number of
jobs, and the timeout, warn that this incurs charges, and STOP until they
approve. Include this billing warning in every answer that shows a
submit command, even when you only explain the steps or the user will run
the command themselves.
Submit. Pick the submit type:
- Native executable or shell script: see
android_executable.md.
- Instrumentation test APK: see
instrumentation.md.
- Same binary with several configurations (different flags, inputs or
environment variables) per device: see
multi_config_runs.md.
Wait. For runs longer than a few minutes, submit with --async and
follow session_lifecycle.md.
Collect results. Download and map artifacts to devices with
results.md.
Report one row per device: device ID, job folder (job-NNN), result,
key outputs, and the gs:// path of the session folder. Call out failed,
timed-out or cancelled jobs explicitly instead of dropping them.
Rules
- Always set the timeout.
--executable-timeout (or
--instrumentation-timeout) defaults to 5m; the valid range is 1m to
3h. Estimate the run time and set it explicitly.
- Arguments are comma-separated. Each element of
--executable-args
becomes one argument. Rewrite space-separated command lines. If a value
contains a comma, use the ^SEP^ prefix (see
android_executable.md).
- No shell in the direct call. With a binary as
--executable there is no
shell: set environment variables with --executable-env-vars, not export.
- Do not overwrite shared inputs. DDP fetches inputs when a job starts.
Never overwrite a
gs:// script or binary that a pending session uses; use
local paths (auto-uploaded) or a unique gs:// path per run.
- Label sessions with
--labels (for example purpose=smoke,build=1234)
so they are easy to find later.
- Poll politely. Never poll in a tight loop; poll every 30 to 60 seconds
and report progress (see
session_lifecycle.md).
- Cancel on request. If the user wants to stop, cancel the session (see
session_lifecycle.md) and tell the
user it was cancelled.
- Do not use the Device Streaming API (
devicestreaming.googleapis.com,
deviceSessions) to run batch jobs; that is for interactive leases.
Reference index
- device_selection.md: map device names
such as "Pixel 10" to catalog IDs, OS versions, physical vs virtual.
- android_executable.md: flags, direct
call, shared libraries, script as executable.
- instrumentation.md: APK tests, sharding,
test targets.
- session_lifecycle.md: sync vs async,
wait, describe, cancel, status and result types.
- results.md: bucket layout, job-to-device mapping,
logs.
- multi_config_runs.md: run
the same binary with several configurations per device.
- troubleshooting.md: common failures.
1---2name: developer-device-platform-device-run3description: >-4 Runs automated, non-interactive jobs on remote Android devices with Developer5 Device Platform (DDP) Device Run using `gcloud beta device-run sessions`:6 native Android executables or shell scripts (for example CLI tools, custom7 runners, test harnesses or benchmarks) and8 Android instrumentation tests, on one or many devices, then waits for9 completion and collects per-device outputs and logs. Use when running a10 binary or test suite on remote devices without an interactive connection.11 Don't use it for interactive device reservations, adb tunnels or screen12 streaming (use developer-device-platform-basics), or for local devices.13metadata:14 source: https://skillmd.com/skills/google/developer-device-platform-device-run15 version: "1.0.0"16 category: CloudInfrastructureAndServices17---1819# Developer Device Platform: Device Run2021Device Run executes a job on remote DDP devices and returns its artifacts (logs,22pulled files) to a Cloud Storage bucket. One session fans out to one job per23requested device.2425> [!WARNING]26> Developer Device Platform (DDP) is currently in Preview. The27> `gcloud beta device-run` commands might change without notice.2829## When to use this skill3031The user wants to... | Use32:--------------------------------------------------------- | :--33Run a native binary or shell script on remote devices | This skill (`android-executable`)34Run an Android instrumentation test APK on remote devices | This skill (`instrumentation`)35Reserve a device, connect with adb, stream the screen | `developer-device-platform-basics`36Extend or cancel an interactive device lease | `developer-device-platform-basics`37Work with a device connected over USB | Neither (not DDP)3839The setup below is complete; this skill doesn't depend on another skill for40authentication, project selection or API enablement.4142### Requests this skill does not handle4344For interactive use (reserve a device, adb, screen streaming, leases):4546* **If `developer-device-platform-basics` is installed:** do not submit a47 Device Run session; switch to `developer-device-platform-basics`, and note48 that interactive reservations are also billed to the active project.49* **If `developer-device-platform-basics` is not installed:** reply in a50 single message **without calling any tools** (no commands, searches, file51 reads or scheduling), then stop:52 1. Say that Device Run is for non-interactive batch jobs, so you will not53 submit a Device Run session.54 2. Point the user to an interactive Device Streaming reservation with the55 `developer-device-platform-basics` skill (or56 https://docs.cloud.google.com/device-streaming/docs/overview.md.txt),57 and suggest installing the skill.58 3. Warn that an interactive reservation is also billed to the active59 Google Cloud project.6061### Keep answers fast6263Prefer this skill and `gcloud beta device-run ... --help` over broad web64searches for Device Run syntax. If `gcloud` or the `beta` component is not65installed, fall back to the official documentation at66https://docs.cloud.google.com/developer-device-platform/device-run.md.txt and67https://docs.cloud.google.com/sdk/gcloud/reference/beta/device-run. For dry68runs, show the commands instead of running them.6970## Usage Attribution7172**MUST READ**: Before executing any `gcloud`, REST API, or MCP command, you73MUST read and follow the instructions in74[Usage Attribution](references/attribution.md).7576## Setup7778Run these checks once per environment. Do not assume tools are installed, and79do not install or update software without the user's approval.80811. **gcloud CLI**: Check that gcloud is installed and has Device Run commands:8283 ```bash84 gcloud --version85 gcloud beta device-run sessions submit android-executable --help >/dev/null86 ```8788 If gcloud is missing, point the user to89 https://docs.cloud.google.com/sdk/docs/install-sdk.md.txt. If the `beta`90 component or the Device Run commands are missing, **ask the user** before91 running `gcloud components install beta` or `gcloud components update`.92932. **Authentication**: Check the active account. On a Compute Engine or other94 remote VM, the active account may be the VM's default service account95 (`...@...iam.gserviceaccount.com`), which often lacks the scopes Device Run96 and billing calls need (`No service account scopes specified`). If there is97 no active account, or only such a service account, ask the user to sign in.98 `--update-adc` also updates Application Default Credentials in the same99 flow; add `--no-launch-browser` in SSH or remote terminals:100101 ```bash102 gcloud auth list --filter=status:ACTIVE --format="value(account)"103 gcloud auth login --update-adc104 ```1051063. **Project**: Use the user's active project, or the one they name. Never107 hardcode a project, and don't change the active project without asking.108109 ```bash110 export PROJECT_ID=$(gcloud config get project)111 # Only if the user asks to switch:112 gcloud config set project PROJECT_ID113 ```1141154. **Billing**: Device Run is billed to the project. Check that billing is116 enabled; if it isn't, stop and tell the user.117118 ```bash119 gcloud billing projects describe "${PROJECT_ID}" \120 --format="value(billingEnabled)"121 ```1221235. **Enable the Device Run API** (if not already enabled; ask first):124125 ```bash126 gcloud services enable devicerun.googleapis.com --project="${PROJECT_ID}"127 ```1281296. **IAM roles**: The user needs `roles/devicerun.admin`,130 `roles/serviceusage.serviceUsageConsumer` and `roles/viewer` on the131 project. To read inputs from a bucket in another project, grant the DDP132 service agent `roles/storage.objectViewer` on that bucket (see133 https://docs.cloud.google.com/developer-device-platform/device-run/share-storage.md.txt).1341357. **Bucket**: Sessions store inputs and outputs in Cloud Storage. Without136 `--bucket-name`, gcloud uses or creates `gs://${PROJECT_ID}-devicerun`.137 For project IDs that contain `:`, `.` or `google`, gcloud replaces them138 (with `-`, `-` and `elgoog`) before adding `-devicerun`; read the actual139 bucket from the `Result files` URI printed by `submit` or `describe`. A140 bucket named explicitly with `--bucket-name` MUST already exist. Pass the141 bucket name only (no `gs://`, no path). Inputs and outputs under142 `gs://<bucket>/automation/` are kept until you delete them or a Cloud143 Storage lifecycle rule expires them, and storage is billed meanwhile.144145## Core workflow1461471. **Pick devices.** Users usually name devices the way they are sold ("Pixel148 10", "Galaxy S22"), while `--device` needs a catalog ID such as149 `frankel-36` (codename + Android API level). Resolve names to IDs from the150 live catalog with151 [device_selection.md](references/device_selection.md); never guess an ID152 from memory. If a device is offered on several Android versions and the153 user didn't name one, list the versions, recommend one, and let the user154 pick one, several (one job each) or all; never pick silently. Before155 submitting, show the user the resolved ID, the device name and the Android156 version, and call out any other choice you made for them (physical vs157 virtual, variant).1581592. **Stage inputs.** `--executable`, `--test`, `--target-app` and the source160 side of `--other-files-to-push` accept `gs://` paths or local paths. Local161 files are uploaded automatically into a fresh162 `automation/inputs/<timestamp>/` folder, so prefer local paths for files163 that change between runs (scripts, freshly built binaries). Upload large,164 reused files (models, datasets) to the bucket once and reference them by165 `gs://` path.1661673. **Confirm cost.** **Explicit user confirmation required.** Device Run168 sessions are billed to the active Google Cloud project. Before submitting,169 tell the user the project (`${PROJECT_ID}`), the devices, the number of170 jobs, and the timeout, warn that this incurs charges, and STOP until they171 approve. Include this billing warning in **every** answer that shows a172 submit command, even when you only explain the steps or the user will run173 the command themselves.1741754. **Submit.** Pick the submit type:176177 * Native executable or shell script: see178 [android_executable.md](references/android_executable.md).179 * Instrumentation test APK: see180 [instrumentation.md](references/instrumentation.md).181 * Same binary with several configurations (different flags, inputs or182 environment variables) per device: see183 [multi_config_runs.md](references/multi_config_runs.md).1841855. **Wait.** For runs longer than a few minutes, submit with `--async` and186 follow [session_lifecycle.md](references/session_lifecycle.md).1871886. **Collect results.** Download and map artifacts to devices with189 [results.md](references/results.md).1901917. **Report** one row per device: device ID, job folder (`job-NNN`), result,192 key outputs, and the `gs://` path of the session folder. Call out failed,193 timed-out or cancelled jobs explicitly instead of dropping them.194195## Rules196197* **Always set the timeout.** `--executable-timeout` (or198 `--instrumentation-timeout`) defaults to `5m`; the valid range is `1m` to199 `3h`. Estimate the run time and set it explicitly.200* **Arguments are comma-separated.** Each element of `--executable-args`201 becomes one argument. Rewrite space-separated command lines. If a value202 contains a comma, use the `^SEP^` prefix (see203 [android_executable.md](references/android_executable.md)).204* **No shell in the direct call.** With a binary as `--executable` there is no205 shell: set environment variables with `--executable-env-vars`, not `export`.206* **Do not overwrite shared inputs.** DDP fetches inputs when a job starts.207 Never overwrite a `gs://` script or binary that a pending session uses; use208 local paths (auto-uploaded) or a unique `gs://` path per run.209* **Label sessions** with `--labels` (for example `purpose=smoke,build=1234`)210 so they are easy to find later.211* **Poll politely.** Never poll in a tight loop; poll every 30 to 60 seconds212 and report progress (see213 [session_lifecycle.md](references/session_lifecycle.md)).214* **Cancel on request.** If the user wants to stop, cancel the session (see215 [session_lifecycle.md](references/session_lifecycle.md)) and tell the216 user it was cancelled.217* **Do not use the Device Streaming API** (`devicestreaming.googleapis.com`,218 `deviceSessions`) to run batch jobs; that is for interactive leases.219220## Reference index221222* [device_selection.md](references/device_selection.md): map device names223 such as "Pixel 10" to catalog IDs, OS versions, physical vs virtual.224* [android_executable.md](references/android_executable.md): flags, direct225 call, shared libraries, script as executable.226* [instrumentation.md](references/instrumentation.md): APK tests, sharding,227 test targets.228* [session_lifecycle.md](references/session_lifecycle.md): sync vs async,229 wait, describe, cancel, status and result types.230* [results.md](references/results.md): bucket layout, job-to-device mapping,231 logs.232* [multi_config_runs.md](references/multi_config_runs.md): run233 the same binary with several configurations per device.234* [troubleshooting.md](references/troubleshooting.md): common failures.