Getting started

PreviewAPK is the build-to-preview loop for Android: change the app, build, and the build runs on a cloud phone in seconds — no Android Studio, no local SDK, no Play Store upload just to test a feature. You watch and drive it from a browser; your scripts and AI agents drive it through an API, with eyes (screenshots, UI hierarchy) and ears (the app's logs) inside the app they're building — so they verify their own work instead of building blind. This page is the mental model; the rest of the docs are the mechanics.

The model in four ideas

1. Device slots — you pay per device, not per app

Your subscription is a set of device slots ($19/month each). A slot is a designated device space on PreviewAPK's infrastructure — Pixel 9 Pro or Galaxy S24 profile, Android 10–15, chosen in the device's settings. A slot holds one app at a time: attach an APK, run it, stop it, attach a different one. You can swap apps freely; you just can't run two at once on the same slot.

2. Sessions

Running a device is a session. It boots in typically 30–60 seconds, streams the real Android screen to a browser, and auto-stops after 15 minutes idle (any input resets the timer). Starting again re-boots the same device with the same app attached.

While a session runs, the app's debug log is captured continuously. Watch it live in the portal's Session logs panel under the phone (with an errors-only filter and a download button), pull it from the CLI (logs), or let an agent read it via the MCP tool previewapk_get_logs — a crash's exact reason is in there. The last chunk stays readable after the session ends. Lines from the phone's own stack (graphics probing, the software renderer, runtime startup notices) are flagged as emulator noise: dimmed in the portal, folded when they repeat, and left out of every errors-only view (portal filter, CLI --errors, MCP errors_only) — while copies and downloads always carry the complete raw log.

3. Driver modes — exactly one driver

Every session declares who drives:

Mode	Who can tap, swipe, type	Typical use
`user`	You, in the portal	Presenting, manual testing, demos
`agent`	The API (your key): scripts, CI, AI agents	Automated checks, agent self-verification

The other side's input is refused while a session runs — with a plain-language error — and control can be handed over mid-session (handoff) without a reboot. The owner can always stop a session.

Links never drive. Every link PreviewAPK issues is view-only. Driving requires your portal login or your API key. A forwarded link can never hand a stranger control of your app — this is a design guarantee, not a setting.

4. One kind of link

Link	Shape	Lifetime	Use it for
Session link	`/v/<token>`	Dies when the session ends	Live shares: "watch this run, right now"

The session link is the only link PreviewAPK issues. It is view-only, and the page it opens carries exactly one QR code — of the link itself, so a viewer can scan it and keep watching on their phone. Nothing on a share page can be downloaded. (An earlier permanent per-device link was removed: a link that never expires is a leak waiting for a timestamp.)

Owners do have one file path, and it lives in the portal: Install on my phone mints a 15-minute link (/i/<token>) whose QR installs the build on the owner's own phone. It exists because the owner asked, inside their account — never on a share page.

Get your API key

Agent-led (fastest): hand your agent /setup.md — or just have it run previewapk setup. It prints a short code; you approve the code on the portal grant page while signed in; the portal mints a normal API key and setup saves it on the agent's machine. The key never passes through a chat.

Manual:

Log in to the portal.
Open the Developers — API, CLI & agents card. Your account API key is there, with copy buttons.
Treat it like a password: it can push builds and drive your devices. Send it to tools via the X-Api-Key header or the PREVIEWAPK_API_KEY environment variable — never in a URL, never in a link you share.

Push your first build (60 seconds)

curl -o previewapk https://previewapk.siteport.site/cli/previewapk.py
export PREVIEWAPK_API_KEY=<your key>
python3 previewapk push app.apk --run        # attaches the APK and starts a session
python3 previewapk status                    # poll until "live"
python3 previewapk links                     # the share link for the live session

How agents should look: two senses, two jobs. The UI hierarchy (API · CLI tree · MCP) gives the screen as elements with labels, bounds, and state — navigate and assert with it. Screenshots give pixels — verify visual correctness with them. Agents that navigate by tree and verify by screenshot are faster, cheaper, and land their taps.

Open the session link and the app is running. Full surface: CLI reference, API reference, MCP server, CI recipes. Building with an AI agent? Hand it the agent guide (or /llms.txt) — it's written to be read by one.