Skip to content

About

Smoke-test every Android build on a cloud Android phone from GitHub Actions. No emulator, no KVM.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

5 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Mobilebox: Cloud phones for your agents

Smoke-test every Android build on a cloud Android phone, from any GitHub workflow.
Your APK goes onto a fresh phone, which opens it, waits for one text and keeps a screenshot. No emulator on the runner, and no KVM.

Website · Docs · Usage · Screenshots in every PR · Mobilebox for agents (MCP) · Add to Cursor

Mobilebox: Cloud phones for your agents. Phones for your agents: each agent gets its own cloud Android phone over MCP, reads the screen, taps, types and installs your APK. Ready in ~20 s, $0.01/min, parked phones free.

test MIT license

~23 s from fresh phone to verdict · $0.01 per run · 1 step in your workflow · 0 phones left behind

Times: create to pass on production, Fossify Calculator 1.4.0, three runs on 2026-11-06 (22.7–23.3 s). A run is one phone for its one-minute minimum.

Usage

1. Get a key. Sign up with GitHub ($2 of credit, 200 runs) and create an agent key in the dashboard. Add it to your repository as the secret MOBILESANDBOX_API_KEY.

2. Add the step after your build.

# .github/workflows/android-smoke.yml
name: android-smoke
on:
  push:
    branches: [main]
  pull_request:        # PRs from this repo; GitHub withholds secrets from fork PRs
  workflow_dispatch:
permissions:
  contents: read
  pull-requests: write # the proof comment on PRs; without it no comment is posted
jobs:
  smoke:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-java@v6
        with:
          distribution: temurin
          java-version: 21
      - run: ./gradlew assembleDebug
      - uses: mobilebox-dev/android-smoke-action@v1
        with:
          apk: app/build/outputs/apk/debug/app-debug.apk
          wait-for: Welcome
          api-key: ${{ secrets.MOBILESANDBOX_API_KEY }}

3. Push. The job fails when the text doesn't show, and the run's artifacts hold a screenshot of the screen the phone saw. On a pull request the run leaves one comment, updated on every push:

✅ com.example.app launch tested on a Mobilebox cloud phone · Android 14 · 23 s · $0.01
(the last screen)
Tested on Mobilebox

A real one: the proof comment on this repo's self-test PR.

The screenshot is an image file at an unguessable address on mobilebox.dev, not indexed and not shown anywhere else. It and the comment's line are deleted from Mobilebox after 30 days. Turn the comment off with comment: false: then nothing is posted or stored.

The screenshot artifact from a passing run: Fossify Calculator open on a Mobilebox phone, showing 0 and the keypad
The artifact from a real run: unedited, straight from the phone.

Inputs and outputs

Input Default
apk required Path to the APK: arm64-v8a or universal.
api-key required Your Mobilebox key, from a secret.
wait-for – Text that proves launch, e.g. a button label. Empty: pass when the app is in the foreground after opening.
timeout 60 Seconds to wait for the text.
comment true On a pull request, post the run's proof as one PR comment. false: no comment, nothing stored. Push and other events never comment.
github-token github.token Writes the PR comment; needs pull-requests: write. Without it no comment is posted (and nothing kept), and the job still passes or fails on the app alone.
artifact-name android-smoke-screenshot Set it per call when one job calls the action twice; each name gets its own PR comment.
Output
result pass or fail
phone-id The phone the test ran on, e.g. ph_ohloqltzhm4c
screenshot Path to the PNG of the last screen
comment-url The PR comment with the run's proof, when one was posted

Use continue-on-error: true and steps.<id>.outputs.result to report instead of failing the job.

What a run does

  1. Creates a fresh Android 14 phone and waits until it is ready (boot time is free).
  2. Uploads your APK, installs it with its permissions granted, and opens it.
  3. Waits for wait-for on screen, or checks that the app is still in the foreground.
  4. Saves a screenshot and uploads it as an artifact, on a pass and on a fail.
  5. On a pull request (unless comment: false), posts or updates the proof comment.
  6. Deletes the phone: on a pass, on a fail, and when you cancel the job.

A lost create is retried with the same idempotency key, so a flaky network never makes a second phone.

Log says Next step
"X" did not appear within 60 s + screen text Read the printed screen: a dialog, a crash, a splash screen or another language
is not in the foreground The app closed after launch: check for a crash on startup
unsupported_abi Build an arm64-v8a or universal variant
insufficient_credits Add credit in the dashboard
Cleanup failed Delete the phone from the dashboard

Use a build that runs on its own: a React Native debug APK waits for a Metro server the phone can't reach. The printed screen lands in the CI log, so keep real accounts off the first screen.

Try it locally

The step is one Node script without dependencies:

MOBILESANDBOX_API_KEY=... APK=app-debug.apk WAIT_FOR=Welcome node smoke.mjs

Go further

The same phones are open to your coding agent over MCP: it can tap through the flows a smoke test can't reach, read the screen as numbered elements and tell you what broke. See mobilebox-dev/mobilebox.


Questions: [email protected], or open an issue. MIT for this repository; the hosted service is covered by its terms.

About

Smoke-test every Android build on a cloud Android phone from GitHub Actions. No emulator, no KVM.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages