dsh-apk-vm: A DSH plugin that runs an Android VM inside the DeepSeek Harness sidebar

What Does It Do?

APK Virtual Machine is a DSH plugin for DeepSeek Harness that brings a local, rooted AOSP Android VM into the sidebar. It solves the friction of previewing and debugging APKs outside the session: no separate emulator window, no manual installs, and no way for an Agent to touch the device. The plugin boots an Android 14 (API 34) userdebug image with root enabled, installs an APK, streams the guest display as H.264/WebCodecs video at up to 60 fps, and forwards tap, swipe, key and text input back into the VM, while exposing a rooted debug API and an apk_vm Agent tool. It is maintained by yuxiaole-bili under Apache-2.0, with no npm runtime dependencies and no build step.

Core Features

• Live sidebar preview: streams the Android screen inside the DSH panel at up to 60 fps, with roughly 29.5 s cold boot and 8.4–10.5 s snapshot boot on the reference machine.
• Drag-and-drop APK install: drop a package onto the panel to install it, with app install, uninstall and launch support.
• Input forwarding: taps, swipes, key events and text typed in the panel are injected into the guest.
• Rooted debugging: the guest is a userdebug image that runs adb root on every boot, giving Agents a root shell and UIAutomator automation.
• Isolated VMs per Agent: each Agent can use its own VM instance, with up to 3 extra VMs by default at roughly 2.5 GB RAM each.
• Environment self-check: an Environment card verifies Android SDK, adb, emulator, system image and AVD, with SDK bootstrap kept opt-in.

How to Use This Plugin?

After enabling it in DSH, an "APK Virtual Machine" entry appears in the sidebar; open its main panel to boot the VM. Start with the Environment card to confirm the SDK, emulator, system image and AVD are ready, and make sure hardware virtualization is on (AEHD/WHPX on Windows, KVM on Linux, HVF on macOS). Then drag an APK into the panel to install it and interact with the screen directly; for automation, let an Agent call the apk_vm tool to install apps, run UIAutomator and inject input. The debug HTTP routes and WebSocket upgrades are loopback-only by default, and remote use behind a trusted authenticated proxy requires explicitly enabling allowRemote. Windows x64 is the only end-to-end verified platform, while macOS and Linux have detection and CI coverage only.

How to Troubleshoot This Plugin?

If the VM fails to start, check the Environment card first: missing adb, emulator, sdkmanager/avdmanager, system image or AVD will block boot, so fill in the missing components per the official instructions. A virtualization error at boot means the host has not enabled AEHD/WHPX, KVM or HVF, which must be turned on at the system level. A black panel or broken stream usually points to H.264/WebCodecs decoding or a loopback connection issue, so verify browser decode support and local port conflicts per the official instructions. When multiple VMs fail for lack of memory, reduce the number of instances running at once.