S
ShizuPortal
ShizuStore

Unofficial ShizuStore Web Portal

This is an unofficial web portal for ShizuStore self-hosted by rdevz-ph. Visit the official portal at https://shizustore.com/.

CatalogAI agentsVirtual Screen
Virtual Screen

Virtual Screen

v0.2.1
by lejw0925•AI agents•PolyForm-Noncommercial-1.0.0
Need ShizuStore app? Download APK

About Application

Virtual Screen

Virtual Screen · 虚拟屏

A separate Android display for your agent. Your phone stays yours.

简体中文 · English

Release 0.2.1 Build Android 13+ PolyForm Noncommercial

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.

PiP preview: the phone stays usable Permissions and backend screen Display and control screen MCP connection settings

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

  1. Install the 0.2.1 APK and install a compatible Root manager or Shizuku / Stellar. If using Shizuku or Stellar, start its service first.

  2. 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.

  3. Enable MCP. For a USB debugging connection, run this on the computer:

    adb forward tcp:8732 tcp:8732
    

    The 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.

  4. 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>"
          }
        }
      }
    }
    
  5. 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.

GuideContents
MCP integrationAuthentication, client setup, tools, leases, observations, and receipts
Public tunnelsfrpc, Cloudflare, credentials, and network requirements
Build and releaseToolchain, native programs, signing, and GitHub Actions
Release validationDevice coverage, measurements, and known limits
Getting started and testingAuthorization and device validation workflows
ContributingRepository 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.onCreate no 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, and time_limit/output_limit truncation 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: DeviceBackendTest passed (6 tests; 2 Shizuku cases skipped because Shizuku is not installed); DeviceToolProbeTest passed 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 total

Shizuku API Permissions

moe.shizuku.manager.permission.API_V23

This application connects to the Shizuku service to execute system-level operations with ADB elevated privileges.

Standard Android Permissions

INTERNET
ACCESS_NETWORK_STATE
POST_NOTIFICATIONS
POST_PROMOTED_NOTIFICATIONS
FOREGROUND_SERVICE
FOREGROUND_SERVICE_SPECIAL_USE
WAKE_LOCK
REQUEST_IGNORE_BATTERY_OPTIMIZATIONS
io.github.lejw0925.virtualscreen.DYNAMIC_RECEIVER_NOT_EXPORTED_PERMISSION

Specifications

CategoryAI agents
Packageio.github.lejw0925.virtualscreen
LicensePolyForm-Noncommercial-1.0.0
GitHub Stars40
Installs489
Target SDKAndroid 14+ (API 37)
Last UpdatedNovember 15, 2026
Release DateNovember 17, 2026
Root RequirementRootless (Shizuku)
ShizuStore Installation

Install via ShizuStore to enable automatic updates and silent installations using Shizuku.