PreviewAPK

PreviewAPK — AI エージェント向けのスマートフォン

エージェントが Android アプリをビルドしても、そのあと……あなたもエージェントも、実行中の様子を確認できません。 マシンにエミュレーターはなく、デスクに端末もなく、Play Store はフィードバックループにはなりません。

PreviewAPK は、エージェントに本物のクラウド Android スマートフォンを提供します。 APK をアップロードすると、数秒でブラウザー上に起動します。エージェントはタップ、入力、スクリーンショット、ログの確認を行い、あなたが確認する前に自分の作業を検証できます。同じスマートフォンをリンクから確認でき、必要なときはいつでも操作を引き継げます。また、デバイスごとに固定のプレビューリンクが用意されるので、クライアントに共有したり、PR に貼り付けたりできます。

• デバイスごとに月額 $19 で、実行回数は無制限です。1 台のデバイスで同時に実行できるアプリは 1 つです。アプリは自由に切り替えられます。
• リンクは常に閲覧専用です。操作できるのは所有者のキーを持つエージェント、またはポータル上の所有者だけです。1 セッションにつき操作できるのは 1 人で、明示的に引き継げばセッション中でも切り替えられます。
• スマートフォンには Google Play services がありません。Google サインイン、Maps、FCM が必要なアプリでは利用上の制約が生じますが、それ以外はすべて動作します。

このリポジトリはオープンクライアントです。CLI と MCP サーバーの両方が含まれ、どちらも単一ファイルで、Python 標準ライブラリだけを使用します。PreviewAPK サービス自体はホスト型です。previewapk.siteport.site のアカウントから API キーを取得してください。PreviewAPK は現在ウェイトリスト制のベータ版です。そちらから登録してください。

クイックスタート — 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 "[email protected]"
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            # your permanent preview link

実行中のデバイスにプッシュすると、アプリがその場でホットスワップされます。同じセッション内でインストールして再起動するため、再起動は不要です。

座標はピクセルではなく、0～1 の割合で指定します。CLI と API は範囲外の値を拒否するため、誤った場所を黙ってタップすることはありません。また、フォーカスされているフィールドがない場合、text は何もないところに入力せず、処理を拒否します。エージェントが信頼できるシグナルとして、エラーには何が起きたかと、代わりに何をすべきかが記載されます。

クイックスタート — MCP サーバー

このリポジトリから previewapk_mcp.py をダウンロードし、MCP クライアントに登録します。Claude Code の場合：

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

Cursor／Claude Desktop／その他の MCP クライアントの場合（JSON 設定）：

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

17 個のツールを利用できます。デバイスの一覧表示と選択、プッシュ（実行中のデバイスではホットスワップ）、起動、停止、リンクの取得、座標またはラベルによるタップ、スワイプ、キー入力、テキスト入力、再起動、スクリーンショット（フレームバッファーから取得した実際の画像を返し、階層情報と一致します）、UI 階層の取得、セッションログの取得、操作の引き継ぎに対応しています。

作業デバイスのモデルは CLI と同じです。エージェントのセッションでデバイスを一度選択すると（previewapk_use_device または previewapk_start）、デバイス名を繰り返し指定せずに操作できます。デフォルトのデバイスはありません。デバイスが選択されていない状態で操作すると拒否されるため、ビルドが思い込みで別のスマートフォンに適用されることはありません。

エージェントの操作方法

階層情報（クラス、ラベル、中心座標、状態フラグを含む要素ツリー）を使って、画面を移動し、状態を確認します。高速で低コスト、かつ正確です。画面の見た目はスクリーンショットで確認します。操作後はログを読みます。クラッシュの正確な理由はログに記録されています。エミュレーターのノイズ（仮想 GPU のグラフィックススタックによる大量出力）にはタグが付けられ、エラーのみの表示から除外されます。ログのコピーとダウンロードでは、常に完全な生ログが取得されます。

詳細なドキュメント：previewapk.siteport.site/docs（API、CLI、MCP、CI のレシピのガイド）。 エージェント向けガイド：previewapk.siteport.site/agents

ライセンス

このリポジトリのクライアントツールは MIT ライセンスです（LICENSE を参照）。PreviewAPK サービスは、別個のホスト型製品です。