Virtual Screen
v0.2.1About Application
Virtual Screen · 虚拟屏
A separate Android display for your agent. Your phone stays yours.
简体中文 · English
Virtual Screen is an Android app that gives an AI agent an isolated virtual display and runs an authenticated MCP server on the phone. The agent can discover, launch, and operate apps on that display while you keep using the phone's main screen. You can view, take over, or stop an operation at any time.
Release 0.2.1
Download the APK for your architecture plus SHA256SUMS from GitHub Releases: virtual-screen-0.2.1-arm64-v8a.apk, virtual-screen-0.2.1-armeabi-v7a.apk, virtual-screen-0.2.1-x86_64.apk (emulators), or virtual-screen-0.2.1-universal.apk when the architecture is unknown. The app requires Android 13 (API 33) or later and either a working Root su or a running, authorized Shizuku / Stellar service. Device compatibility and background behavior can vary by ROM.
Features
- Isolated virtual display. Agent launches and input are scoped to a display created by this app. Failed operations never fall back to the phone's main screen. Cross-display conflicts require phone approval before an app is restarted, or can be auto-approved via a Display & control switch.
- Visible progress and takeover. PiP shows the remote display; PiP is read-only and can be turned off entirely in settings. Expand the app's full-screen preview or use the notification to take over locally, which revokes the remote control lease.
- 19 MCP tools. Control, display, app, observation, input, and wait operations. Tree observations can skip screenshots; fresh observation IDs and session receipts reject stale operations and let clients check uncertain results without replaying input.
- Root and Shizuku / Stellar. Both privilege backends share the virtual-display engine, MCP protocol, and input constraints; devices running Stellar automatically use its native API.
- Flexible connections. Loopback, LAN, frpc, and Cloudflare Tunnel. MCP and tunnels start disabled; starting MCP restores the previously connected tunnel; credentials are stored in the app's private encrypted storage.
- On-device settings. English, Simplified Chinese, and Traditional Chinese; light and dark themes, dynamic color, onboarding, and local activity logs.
Get Started
-
Install the 0.2.1 APK and install a compatible Root manager or Shizuku / Stellar. If using Shizuku or Stellar, start its service first.
-
Open Virtual Screen, select Root or Shizuku / Stellar under Permissions and backend, and grant access. Enable the app's accessibility service for node targeting and Unicode text editing. Allow notifications for approval and takeover actions, and PiP for automatic previews.
-
Enable MCP. For a USB debugging connection, run this on the computer:
adb forward tcp:8732 tcp:8732The default MCP endpoint is
http://127.0.0.1:8732/mcp. Enable LAN access in settings for a computer on the same network, or configure frpc or Cloudflare Tunnel for public access. -
Put the phone-generated Bearer Token in your MCP client configuration:
{ "mcpServers": { "android-virtual-screen": { "type": "http", "url": "http://127.0.0.1:8732/mcp", "headers": { "Authorization": "Bearer <phone-generated-token>" } } } } -
The agent acquires exclusive control, creates a virtual display, discovers and launches an app, observes its nodes or screenshot, and performs actions. Release control when finished. See MCP integration for protocol details, tool parameters, and client-specific notes.
Use Case Diagram
flowchart LR owner[Phone owner] agent[AI agent / MCP client] subgraph app[Virtual Screen Android app] authorize([Select and authorize Root / Shizuku / Stellar]) configure([Configure MCP and network access]) approve([Approve control requests and app restarts]) takeover([View preview, take over, or stop]) authenticate([Authenticate with Bearer Token and discover tools]) lease([Acquire / release exclusive control]) manage([Create display and launch apps]) observe([Read nodes / capture screenshots]) operate([Perform display-scoped input]) end owner --> authorize owner --> configure owner --> approve owner --> takeover agent --> authenticate agent --> lease agent --> manage agent --> observe agent --> operate configure -. optional .-> tunnel[frpc / Cloudflare Tunnel] takeover --> display[App on the virtual display] manage --> display observe --> display operate --> display
Architecture
flowchart TB client[AI agent / MCP client] subgraph phone[Android phone] subgraph app[Virtual Screen app] ui[Compose home, settings, and preview] service[Foreground service and runtime coordination] mcp[Ktor Streamable HTTP MCP] auth[Bearer auth, sessions, and request receipts] lease[Control leases, approvals, and observation checks] tools[19-tool MCP registry] session[VirtualScreenSessionManager] backend[VirtualScreenBackend interface] root[RootBackend / su process] shizuku[ShizukuBackend / UserService or Stellar native API] engine[Shared PrivilegedDisplayEngine] display[Android virtual display and target app] access[Accessibility node service] preview[Surface mirror and PiP / full-screen preview] tunnel[TunnelManager] frpc[Bundled frpc / cloudflared] end end client -->|HTTP + Bearer Token| mcp mcp --> auth --> tools --> lease --> session ui --> service service --> mcp service --> tunnel --> frpc session --> backend backend --> root --> engine backend --> shizuku --> engine engine --> display access --> session display --> preview owner[Phone owner] --> ui owner -->|Local takeover| preview frpc -. tunnel connection .-> client
Security and Behavior Boundaries
- All remote MCP requests require a Bearer Token. Rotating it invalidates old tokens. Do not commit tokens or put them in logs or public messages.
- Device operations require an exclusive lease owned by the current session. Each authorized operation extends its five-minute idle deadline. Expired leases, stale observations, and ambiguous selectors are rejected.
- Input is restricted to the virtual display. Remote PiP only displays the screen; phone touch or notification takeover revokes the remote lease. An agent cannot approve permission dialogs on the phone's main display.
- MCP and tunnels start disabled. LAN and public tunnels increase network reachability; enable them only when needed and protect the client token.
- Accessibility provides node access and assists text entry. Node features are limited without it. Multi-display, PiP, and background behavior varies across apps and ROMs.
Development and Validation
Use JDK 25 and Android SDK 37 (platforms;android-37.0, build-tools;37.0.0):
./gradlew :app:testDebugUnitTest :app:lintDebug :app:assembleDebug
Run the same full build used by GitHub Actions:
./gradlew --no-daemon :app:testDebugUnitTest :app:lintDebug :app:assembleDebug :app:assembleRelease :device-fixture:assembleDebug :app:assembleDebugAndroidTest
Actions run JVM tests, Lint, Debug / unsigned Release, fixture, and instrumentation APK builds on main, pull requests, and manual dispatch. A matching vX.Y.Z or vX.Y.Z-beta[.N] tag runs signing and publishes the APK with SHA256SUMS; beta tags become GitHub prereleases. Signing material stays in repository secrets. See Build and release for the toolchain and the pinned provenance and build steps for frpc / cloudflared.
See the changelog and 0.1.0 device report for current fixes and validation. The previous physical Android 17 / HyperOS 4 Root run passed all 19 tools; see Android 17 and home validation. Shizuku's Android 15 emulator results are in Beta backend comparison. See 1033 validation for continuous Cloudflare health checks and the 200-second background device test, and background connection validation for vendor freezing, the app-specific unrestricted battery setting, and screen-off testing while charging. Unplugged deep Doze and all ROM combinations remain untested. Historical results are in home layout validation and release validation.
| Guide | Contents |
|---|---|
| MCP integration | Authentication, client setup, tools, leases, observations, and receipts |
| Public tunnels | frpc, Cloudflare, credentials, and network requirements |
| Build and release | Toolchain, native programs, signing, and GitHub Actions |
| Release validation | Device coverage, measurements, and known limits |
| Getting started and testing | Authorization and device validation workflows |
| Contributing | Repository structure, conventions, tests, and security boundaries |
Credits and License
Parts of the virtual-display engine are adapted from ETA. The UI uses Jetpack Compose Material 3; tunnels use frp and cloudflared. Tool design draws on research into Mobile Next, Android-MCP, android-remote-control-mcp, and PhoneUse.
Licensed under PolyForm Noncommercial 1.0.0 with upstream Required Notices preserved. See THIRD_PARTY_NOTICES.md for component licenses and native provenance.
Release Notes & Changelog
虚拟屏 0.2.1
稳定性与性能维护版本:减少启动期主线程 IO,限制无障碍节点树的采集时间与输出体积,并把画中画设置移入「显示与控制」。要求 Android 13 或更新版本,并使用已授权的 Root 或 Shizuku / Stellar 后端。
主要更新
- 启动期 IO:MCP Token 的 Android Keystore 读取改为后台预热,服务器启动时再兜底加载;隧道目录清理延迟到隧道实际启动、登录或管理时。
Application.onCreate不再同步解密 Token 或递归清理隧道目录。 - 节点树预算:单次采集增加 1500 ms 时间预算,格式化输出最多 2000 节点;结果新增
time_budget_ms、output_limit和time_limit/output_limit截断原因,降低密集页面卡顿与超大 MCP 响应。 - 画中画设置:画中画预览开关和系统画中画设置入口从「权限与后端」移到「显示与控制」的「画中画」分组。
验证范围
- JVM 单元测试 147 项、Android Lint(0 error、69 warning)、Debug 构建通过。
- vivo V2419A / Android 15 / KernelSU Root:
DeviceBackendTest通过(6 tests,2 项 Shizuku 因未安装跳过);DeviceToolProbeTest通过,19/19 个 MCP 工具完成。测试结束后未残留虚拟屏。 - Release 继续使用 R8、资源压缩和按 ABI 分包,由标签触发的 Actions 构建、签名并发布。
说明
节点时间预算和输出上限是保护性上限,不改变 5000 节点/100 层/1000 子项的采集上限;full 模式在预算内最多返回 2000 个节点。更密集的页面仍建议通过 mode=tree 或较小范围观察。
Virtual Screen 0.2.1
A stability and performance maintenance release: startup work is moved off the main thread, accessibility tree collection and output are bounded, and PiP settings move to Display & control. Requires Android 13+ with an authorized Root or Shizuku / Stellar backend.
Highlights
- Startup I/O: MCP token decryption through the Android Keystore is warmed in the background and loaded as a fallback when the server starts; tunnel directory cleanup is deferred until a tunnel actually starts, logs in, or is managed.
Application.onCreateno longer decrypts the token or recursively cleans the tunnel directory synchronously. - Tree budgets: each collection has a 1,500 ms time budget and formatted output is capped at 2,000 nodes. Results expose
time_budget_ms,output_limit, andtime_limit/output_limittruncation reasons, reducing jank on dense pages and oversized MCP responses. - PiP settings: the PiP preview switch and system PiP settings entry moved from Permissions and backend to the Picture-in-picture group under Display & control.
Validation
- 147 JVM unit tests, Android Lint (0 errors, 69 warnings), and the Debug build pass.
- vivo V2419A / Android 15 / KernelSU Root:
DeviceBackendTestpassed (6 tests; 2 Shizuku cases skipped because Shizuku is not installed);DeviceToolProbeTestpassed all 19 MCP tools. No virtual display remained after the runs. - Release builds continue to use R8, resource shrinking, and per-ABI APKs; the tagged workflow builds, signs, and publishes them.
Note
The time budget and output cap are protective limits; the collection limits remain 5,000 nodes, depth 100, and 1,000 children per node. full output returns at most 2,000 nodes within the budget. For denser pages, prefer mode=tree or a narrower observation scope.
Declared Android Permissions
10 totalShizuku API Permissions
This application connects to the Shizuku service to execute system-level operations with ADB elevated privileges.
Standard Android Permissions
Specifications
Install via ShizuStore to enable automatic updates and silent installations using Shizuku.
More in AI agents
Other applications in this category