Preview your APK build from Codex: the terminal agent gets a phone

Codex lives where Android builds live — the terminal. It writes the code, runs Gradle, reads the failures, iterates. What it never does is see the app: the build succeeds, the summary is confident, and the APK's first real run belongs to a human with a phone. PreviewAPK plugs into Codex over MCP and hands it a cloud phone — so the agent that built your app can also be the agent that ran it.

A strong builder with no device

Codex's loop is observe-and-correct, fed by compiler output and test runs. For Android, the most important observable — the running app — isn't in the loop. Layouts that overflow, flows that dead-end, crashes that only happen on a real tap: all invisible, all discovered later by whoever installs the build. The agent's confidence and the app's quality part ways exactly there.

The terminal-native patch is a local emulator plus adb scripting. It's honest toil: SDK setup, system images, a host machine that must stay awake, and a session nobody else can open. Codex in a cloud sandbox can't reach it at all.

Connect PreviewAPK to Codex (2 minutes)

1. Get the server file: curl -o previewapk_mcp.py https://previewapk.siteport.site/mcp/previewapk_mcp.py
2. Get an API key from your PreviewAPK portal (API keys → create). Free during the private beta — join the waitlist.
3. Add the server with the CLI:

   codex mcp add previewapk \
     --env PREVIEWAPK_API_KEY=<your key> \
     -- python3 /path/to/previewapk_mcp.py

   or by hand in ~/.codex/config.toml:

   [mcp_servers.previewapk]
   command = "python3"
   args = ["/path/to/previewapk_mcp.py"]
   
   [mcp_servers.previewapk.env]
   PREVIEWAPK_API_KEY = "<your key>"

4. Check it: run /mcp in a session — seventeen PreviewAPK tools should be listed (full reference in the MCP docs). Adding a line to your project's AGENTS.md — "verify Android changes on PreviewAPK before reporting done" — makes the habit stick.

Ask for verification, not just code

Build the debug APK, push it to PreviewAPK, and walk the
sign-up flow. Screenshot each step, check the logs, fix
what you find, and rebuild until it runs clean. Finish
with the preview link.

Codex selects its working device, pushes the build — the phone boots it in seconds — and tests with the senses the job actually needs:

• Drive: tap (by coordinates or by a button's label), swipe, hardware keys, and real text typing.
• See: screenshots returned as images inside the conversation, plus the live screen streamed to a browser.
• Understand: the screen's UI hierarchy — elements with labels and positions, so it navigates by meaning, not pixel-guessing.
• Hear: the app's debug log for the session, including the crash trace with its reason attached.

That's the agent testing loop completed in the terminal: build, run, see, fix — with screenshots in the transcript as evidence.

You get the same phone

Codex ends by handing you the wheel and the session's share link. Open it in any browser: the same session it just verified, yours to drive from the portal or to share view-only with a client or reviewer. Links never drive — that's the design, and it's why the link is safe to paste anywhere.

Prefer shell over MCP? The CLI is one Python file, no dependencies. Same server in the editors too: Cursor, Copilot, Cline, Windsurf.

FAQ

Can Codex test an Android app by itself?

Not out of the box. Codex can write code, run your build, and execute shell commands, but it has no Android device: nothing installs the APK, taps through the app, or shows Codex a screenshot of the result. A local emulator wired to the terminal is the DIY route — SDK, a machine that stays on, no shareable session. PreviewAPK connects as an MCP server instead, and Codex gets a cloud phone.

How do I add PreviewAPK to Codex?

Either with the CLI — codex mcp add previewapk --env PREVIEWAPK_API_KEY= -- python3 /path/to/previewapk_mcp.py — or by editing ~/.codex/config.toml and adding an [mcp_servers.previewapk] table (both are on this page). Run /mcp inside a session to confirm the tools loaded.

Codex is terminal-native — can it use the CLI instead of MCP?

Yes. PreviewAPK ships a CLI and an HTTPS API alongside the MCP server, and a terminal agent can drive the whole loop with previewapk push / tap / text / shot / logs. MCP earns its place with typed tools and screenshots returned as images the model can view, but the phone is the same behind every door.

What does Codex need before it can preview?

A built APK — Gradle debug builds land at app/build/outputs/apk/debug/app-debug.apk; EAS and release builds work too — and a PreviewAPK account with an API key (Portal → API keys).

How much does it cost?

A flat $19/month per device — unlimited runs, no per-minute metering. One device runs one app at a time; swap apps freely while it's off.

Is PreviewAPK affiliated with OpenAI?

No. PreviewAPK is an independent product. Codex is a trademark of OpenAI; this page describes a workflow that connects the two, nothing more.