App Mode — Test Real Native Apps in Real Device Frames
App Mode lets you drive your own iOS or Android app inside the same high-fidelity device frames you already use for web simulation. A real simulator, emulator, or USB-connected phone on your machine streams its screen into the Emuluxe frame; taps, swipes, and typing you make in the frame are executed on that device by a real automation driver.
If Web mode answers "how does my website look on a phone?", App Mode answers "does my actual app work on that phone?"
Web mode vs App Mode
Both lanes share one session spine, one device registry, one AI pipeline, and one quota. They differ in what is being simulated:
| Web mode | App Mode | |
|---|---|---|
| Content | A URL in an iframe | Live stream of a real device screen |
| Computer | Emuluxe-managed browser profile | Your machine (BYOD) or a rented cloud device |
| Install | Nothing | emx app agent + Xcode and/or Android SDK (free) |
| Provenance chip | Emulated profile | Mirrored · Reshaped · Preview (always shown) |
| AI input | HTML / CSS / viewport / UA | UI accessibility tree → outline, plus logs |
| Sessions quota | Shared budget | The same shared budget |
What is faithful, and what is not
App Mode mirrors a real device, so most things are exact. A few things cannot be reproduced and are never claimed to be:
| Property | Faithful? | Why |
|---|---|---|
| Layout, safe areas, DPR text | ✅ Yes | Streamed pixels from the real device |
| OS-version behaviour | ✅ Yes | Behaviour comes from the OS that is running |
| Adaptive / Auto Layout bugs, a11y labels | ✅ Yes | Real UI tree + the same AI pipeline as web |
| 120 Hz feel, camera, thermals, battery drain | ❌ No | The stream is ~5–15 fps; use a physical phone in mirror mode |
| Performance numbers | ⚠️ Only as ingested profiler data | Video lies about frame pacing; profilers do not |
Provenance: always know what you are looking at
Every App Mode frame carries a provenance chip. It is part of the contract, not a decoration:
- Mirrored — the physical screen matches the frame you selected. This is the strongest guarantee: a 1320×2868 iPhone 17 Pro Max stream drawn into the iPhone 17 Pro Max frame at an exact fit.
- Reshaped — the screen geometry does not match the frame, so it is scaled and letterboxed into it. The chip names the real hardware, e.g. "Reshaped · Pixel 9 geometry on real hardware".
- Preview — content came from a different source than the frame (for example a cloud stream, or a frame with no device behind it yet).
A DPR mismatch (device reports @2x, profile expects @3x) still renders, but
the viewer surfaces a warning rather than silently pretending it fits.
Requirements at a glance
| Platform | Minimum | Notes |
|---|---|---|
| Android — macOS / Windows / Linux | Android SDK Platform-Tools (adb), Java 17+, an AVD or a USB phone | emx app doctor tells you exactly what is missing |
| iOS — macOS only | Full Xcode (not just Command Line Tools), licence accepted, iOS simulator runtime 17+ | iOS simulators do not exist on Windows or Linux |
| Automation driver | Maestro (maestro on your PATH) for taps, swipes, typing, and flows | Install per platform, then emx app doctor verifies it |
| Disk | ≥ 15 GB free | Xcode and AVD images are large |
Your code never leaves your machine
App Mode is BYOD — Bring Your Own Device. The agent runs locally, the
simulator/emulator runs locally, and your .apk / .app binary is never
uploaded anywhere. There is no storage bucket for app builds. What leaves your
machine is only metadata: the session record, optional frames you capture, the
UI tree outline, and step results — all written to your own Emuluxe account.
Where you can run it
The same App Mode session powers every surface:
| Surface | How to start |
|---|---|
| Dashboard / Web Studio | Launch an App Mode session from the Simulate view |
| VS Code / Cursor / Windsurf | Run Emuluxe: Start App Mode from the Command Palette |
CLI (emx) | emx app run --build <id> --device <id> |
| AI agents (MCP) | app_simulate, app_tap, app_uitree, … |
Deliberate non-goal: the Chrome extension
App Mode is not offered inside the Emuluxe Chrome extension, and this is intentional rather than an oversight. The extension cannot host App Mode without adding significant cost and risk:
- It runs on Manifest V3, whose service worker is terminated after roughly 30 seconds of inactivity — a poor fit for a multi-minute device stream.
- It has no
nativeMessagingpermission, so it cannot launch or talk to the localemx appagent. Supporting App Mode there would require either a separately installed native messaging host (a second download for users, plus a permission that complicates Web Store review) or a localhost HTTP bridge to the agent. - Both options duplicate lanes that are already served better: VS Code, Cursor, and Windsurf can spawn the agent natively, and Web Studio has a backend to broker the session while the browser acts as a viewer.
If you want App Mode, use the editor extension or the CLI. This may be revisited in a future release if a bridge is built for another reason.
Ready to set it up? Continue with the App Mode Setup Guide.