PreviewAPK

PreviewAPK — a phone for your AI agent

Your agent builds an Android app, and then… neither of you can see it run. No emulator on the machine, no device on the desk, and the Play Store is not a feedback loop.

PreviewAPK gives your agent a real cloud Android phone. Push an APK, it boots in the browser in seconds. The agent drives it — taps, types, screenshots, logs — and verifies its own work before you ever look. You watch the same phone through a link, take the wheel whenever you want, and every session gets a share link you can hand to a client or paste into a PR.

• $19/month per device, unlimited runs. One device runs one app at a time; swap apps freely.
• Links are view-only, always. Only the owner's key (agent) or the owner in the portal drives — one driver per session, switchable mid-session with an explicit handoff.
• No Google Play services on the phones. Apps that need Google sign-in, Maps, or FCM will hit that wall; everything else just runs.

This repo is the open client: the CLI and the MCP server (both single-file, Python standard library only). The PreviewAPK service itself is hosted — you bring an API key from your account at previewapk.siteport.site. PreviewAPK is currently in waitlist beta; join there.

Quick start — CLI

curl -O https://previewapk.siteport.site/cli/previewapk.py
export PREVIEWAPK_API_KEY=pvk_…        # from your portal's Developers card

python3 previewapk.py devices          # see your devices
python3 previewapk.py use "Device 1"   # pick the working device (like cd)
python3 previewapk.py push app.apk --run
python3 previewapk.py tree             # the screen as an element tree
python3 previewapk.py tap --text "Log in"
python3 previewapk.py text "demo@example.com"
python3 previewapk.py shot             # a screenshot you can open
python3 previewapk.py logs --errors    # the app's logcat, noise filtered
python3 previewapk.py relaunch         # app back in front, ~2s, no reboot
python3 previewapk.py handoff user     # hand the human the wheel
python3 previewapk.py links            # the share link for the live session

Pushing to a running device hot-swaps the app in — installed and relaunched in the same session, no reboot.

Coordinates are fractions (0–1), never pixels; the CLI and API reject out-of-range values instead of silently tapping the wrong place, and text refuses when no field is focused instead of typing into the void. Signals an agent can trust: errors say what happened and what to do instead.

Quick start — MCP server

Hosted (zero install): point your MCP client at the remote server — same 27 tools, your API key as a Bearer token, nothing to download or keep current. Claude Code:

claude mcp add --transport http previewapk https://previewapk.siteport.site/mcp \
  --header "Authorization: Bearer pvk_…"

The server issues a session id at connect and your working-device selection rides on it, exactly like the local server. Hosted differences: previewapk_push_apk takes apk_b64 (base64) instead of a local path; file/record downloads return data_b64.

Local (stdio): download previewapk_mcp.py from this repo, then register it with your MCP client. Claude Code:

claude mcp add previewapk \
  --env PREVIEWAPK_API_KEY=pvk_… \
  -- python3 /path/to/previewapk_mcp.py

Cursor / Claude Desktop / other MCP clients (JSON config):

{
  "mcpServers": {
    "previewapk": {
      "command": "python3",
      "args": ["/path/to/previewapk_mcp.py"],
      "env": { "PREVIEWAPK_API_KEY": "pvk_…" }
    }
  }
}

27 tools: list/use devices, push (hot-swaps a running device), start, stop, links, tap by coordinates, by label, or by snapshot ref, swipe, key, type text, relaunch, screenshot (returns a real image, from the framebuffer — it agrees with the hierarchy), UI hierarchy, observe (a compact numbered screen snapshot), act (batched actions), wait_for (elements — or the handback, with condition "driver"), request_human (ask the human for a step only a human should do: a password, a 2FA code, a payment approval — and get back the exact message to relay), finish (file the session wrap-up; the counts in its message — duration, actions, errors — are composed by the server, and finishing does not stop the session unless asked), session logs, handoff, a field-report tool, screen recording (start/stop/download an MP4 of the session), and device controls (timezone, per-app locale, mock GPS location, file push/pull in shared storage, reboot).

The working-device model mirrors the CLI: an agent session selects a device once (previewapk_use_device or previewapk_start), then works on it without repeating its name. Nothing has a default device — an action with no device selected refuses, so a build can never land on the wrong phone by assumption.

How agents should drive

Navigate and assert with the hierarchy (element tree: class, label, center, state flags) — fast, cheap, exact. Verify visuals with a screenshot. Read the logs after actions; a crash's exact reason lives there. Emulator noise (graphics-stack spam from the virtual GPU) is tagged and kept out of errors-only views; copies and downloads are always the full raw log.

Full documentation: previewapk.siteport.site/docs (guides for the API, CLI, MCP, and CI recipes). Agent briefing: previewapk.siteport.site/agents

License

The client tools in this repo are MIT-licensed (see LICENSE). The PreviewAPK service is a separate, hosted product.