AI agents and scripts

An AI coding agent, a script or a CI job can test an Android app on a real phone without a person at the keyboard. It rents a phone with a spending cap, installs the build, checks it with screenshots, Logcat or adb, and ends the rental. Every pocketshare command runs without prompts, prints JSON with --json and returns an exit code a script can check.

What a rented phone gives an agent

• A real phone in adb devices through pocketshare connect or pocketshare run. adb install, adb shell (am start, input tap, uiautomator dump, screencap), port forwarding and test frameworks such as Espresso, Appium and Maestro then work on it as on a phone plugged into the machine.
• CLI commands that need no adb: install, screenshot, logcat, status and stop.
• An MCP server with tools to rent, install, read the screen’s UI elements, tap, swipe, type, take screenshots, read Logcat and run shell commands. See MCP server for AI agents.

There is no root, and a short list of actions that would break cleanup is blocked (Limits). The phone belongs to a host: use test accounts and test data only.

One-time setup by a person

1. Sign up at pocketshare.io/app. A new account starts with $1 of credit.
2. On the API keys page, create a key with phones:read, rentals:read and rentals:write, and tick Agent key. Rentals made with an agent key count against a daily agent spending limit ($5.00 by default) and end after 5 idle minutes (see below); the key can lower those limits but never raise them.
3. Give the agent the key as the environment variable POCKETSHARE_API_KEY. Keep it out of the repository and out of logs.

pocketshare login also works, but it shows a code that a person approves in the browser; an agent should use the key.

Install the CLI

The CLI is one executable. This installs it on Linux x64 after checking its SHA-256 against the release’s checksums:

base=https://pocketshare.io/downloads/cli/latest
curl -fsSLO "$base/pocketshare-linux-x64" -O "$base/SHA256SUMS"
sha256sum --ignore-missing -c SHA256SUMS
install -D -m 755 pocketshare-linux-x64 "$HOME/.local/bin/pocketshare"
export PATH="$HOME/.local/bin:$PATH"
pocketshare version

Other machines use pocketshare-linux-arm64, pocketshare-darwin-arm64, pocketshare-darwin-x64 or pocketshare-windows-x64.exe. To check the checksums’ signature too, and for Windows, see Install. For connect and run you also need adb (Android SDK platform-tools); the CLI finds it in $ANDROID_HOME, Android Studio’s SDK or your PATH.

Check that the key works and see what is free now:

pocketshare phones search --android ">=13" --json

Test a build: CLI commands

set -e
rental=$(pocketshare rent --android ">=13" --max-spend 1 --wait 10m --json | jq -r .rentalId)
trap 'pocketshare stop "$rental"' EXIT            # always end the rental
pocketshare install "$rental" app/build/outputs/apk/debug/app-debug.apk --grant
pocketshare screenshot "$rental" -o home.png
pocketshare logcat "$rental" --package com.example.app --priority E --lines 200

rent picks the cheapest free phone that matches (--model, --brand, --android, --max-price), or takes a phone ID from phones search. --max-spend is the most the rental can cost, in dollars; it ends when the next minute would go over it. install, screenshot and logcat wait until the host’s hub has the phone ready, and each one resets an agent rental’s idle timer.

Test with adb: pocketshare run

run does the whole rental around one command: it rents a phone, connects it to adb, runs the command with ANDROID_SERIAL set (so plain adb goes to the rented phone), saves a screenshot and Logcat to the artifacts directory, and always ends the rental, also when the command fails or times out.

pocketshare run --android ">=13" --max-spend 1 --wait 10m --timeout 15m --artifacts out -- \
  sh -c 'adb install -r app-debug.apk &&
         adb shell am start -W -n com.example.app/.MainActivity &&
         sleep 3 && adb exec-out screencap -p > out/home.png'

It exits with the command’s own exit code (124 after --timeout), so it fits test runners: -- ./gradlew connectedDebugAndroidTest, -- maestro test flow.yaml or your Appium suite. See Use PocketShare in CI for GitLab and GitHub templates.

To keep adb open across several steps instead, start pocketshare connect "$rental" --json in the background and wait for the JSON line with "event": "connected"; its serial (such as 127.0.0.1:15600) is the phone in adb devices, for adb -s <serial>. connect runs until it is stopped, and the rental runs until pocketshare stop.

Idle timeout

An agent rental ends after its idle timeout, 5 minutes by default, without a PocketShare action: renting, connecting, install, screenshot, logcat and every MCP tool call count; adb traffic on its own does not. For long adb-only steps, a person can raise the timeout up to 30 minutes on the website or with a regular (non-agent) key:

pocketshare agent-limits --idle-minutes 30

CI jobs that run long test suites with pocketshare run should use a regular key with the same three scopes instead of an agent key.

Use the MCP server instead

Agents that speak MCP can use the tools directly, with no CLI:

claude mcp add --transport http pocketshare https://pocketshare.io/mcp

The hosted server signs in with OAuth, or takes Authorization: Bearer psk_… with an agent key. pocketshare mcp runs the same tools locally over stdio and can install APK files from disk. Setup for Cursor, VS Code and other clients is on MCP server.

Exit codes

Code	Meaning	What to do
0	Done
1	Failed, for example the install failed or the rental ended	Read the message
2	Bad usage: unknown command or option	Fix the command (pocketshare prints the usage)
3	Not signed in, key revoked, or the key lacks a scope	Ask the person for a working key
4	Credit or a spending limit stopped it	Don’t retry; tell the person
5	PocketShare unreachable or busy	Retry later
6	No matching phone free	Widen the filters or use --wait

With --json, errors print {"error": "<code>", "message": "..."} and still set the exit code.

Rules for agents

• Set a spending cap you can justify on every rental (--max-spend, max_spend).
• End every rental: pocketshare stop, the MCP end_session tool, or pocketshare run, which ends it for you. Stopping wipes the phone, so copy off anything you need first.
• Use test accounts and test data only.
• adb root, remount, rebooting into the bootloader or recovery, and removing PocketShare’s tools fail by design; don’t retry them.

Note

A plain-text index of these docs for agents is at pocketshare.io/llms.txt.