dsh-apk-vm 0.11.1 → 0.12.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +167 -0
- package/DEMO.md +38 -10
- package/README.md +286 -47
- package/SECURITY.md +26 -10
- package/client.js +910 -13
- package/cordis.patch.yml +30 -3
- package/docs/PRIVACY.md +34 -8
- package/docs/README.md +3 -5
- package/docs/RELEASING.md +3 -1
- package/docs/demo.gif +0 -0
- package/index.js +870 -33
- package/lib/activity-log.js +481 -0
- package/lib/android.js +1797 -58
- package/lib/autosetup.js +773 -0
- package/lib/cdp.js +241 -1
- package/lib/installed-apps.js +310 -0
- package/lib/jdk.js +1163 -0
- package/lib/scrcpy.js +1 -1
- package/lib/setup.js +99 -19
- package/package.json +9 -3
- package/scripts/make-demo-gif.mjs +1307 -0
- package/scripts/privacy-scan.mjs +17 -6
package/README.md
CHANGED
|
@@ -45,7 +45,7 @@ same-origin, loopback-only debug HTTP API and an `apk_vm` Agent tool.
|
|
|
45
45
|
> 当前 **Windows x64 与 Linux x86_64(headless)为端到端已验证平台**;macOS 仅做探测/CI
|
|
46
46
|
> 覆盖,详见 `docs/LINUX-E2E.md`。
|
|
47
47
|
|
|
48
|
-
**Status:** `0.
|
|
48
|
+
**Status:** `0.12.0` · Apache-2.0 · no npm runtime dependencies · no build step.
|
|
49
49
|
|
|
50
50
|
This is an open-source DSH plugin published on npm as **`dsh-apk-vm`**. Repository:
|
|
51
51
|
[github.com/yuxiaole-bili/dsh-apk-vm](https://github.com/yuxiaole-bili/dsh-apk-vm).
|
|
@@ -90,7 +90,9 @@ and Agent-facing UI automation for development workflows.
|
|
|
90
90
|
**Requirements**
|
|
91
91
|
|
|
92
92
|
- Android SDK with `adb`, emulator, `sdkmanager`/`avdmanager`, a matching system image and an AVD
|
|
93
|
-
(the Environment card checks all of this;
|
|
93
|
+
(the Environment card checks all of this; on a cold machine the default `autoSetup` provisions
|
|
94
|
+
it — JDK 17, SDK, system image and AVD — on first use, downloading roughly 2.5 GB; set
|
|
95
|
+
`autoSetup: false` to keep setup manual).
|
|
94
96
|
- Hardware virtualization: AEHD/WHPX on Windows, KVM on Linux, or HVF on macOS.
|
|
95
97
|
- Node.js ≥ 20 only for the repository's headless checks; the plugin itself has no npm
|
|
96
98
|
dependencies or build step.
|
|
@@ -106,8 +108,10 @@ and Agent-facing UI automation for development workflows.
|
|
|
106
108
|
- `/apk-vm/*` HTTP routes and WebSocket upgrades are same-origin and **loopback-only by
|
|
107
109
|
default**; `allowRemote: true` is an explicit opt-in for use behind a trusted authenticated
|
|
108
110
|
proxy.
|
|
109
|
-
- No telemetry. Network access only occurs for
|
|
110
|
-
|
|
111
|
+
- No telemetry. Network access only occurs for `autoSetup` provisioning (a SHA-256-verified
|
|
112
|
+
Temurin JDK 17 from `api.adoptium.net`, then the user's own `sdkmanager` for SDK packages and
|
|
113
|
+
the system image — roughly 2.5 GB on a cold machine), for manual downloads you trigger, or
|
|
114
|
+
when you configure a remote adb device.
|
|
111
115
|
|
|
112
116
|
**Compatibility**
|
|
113
117
|
|
|
@@ -132,11 +136,16 @@ Real screenshots from the reference host:
|
|
|
132
136
|
|
|
133
137
|

|
|
134
138
|
|
|
139
|
+
28-second capture of the loop: home screen → sample APK installed and driven by the API →
|
|
140
|
+
60 fps animation in the guest (720×1280, 3.2 MiB):
|
|
141
|
+
|
|
142
|
+

|
|
143
|
+
|
|
135
144
|
| Asset | Status |
|
|
136
145
|
| --- | --- |
|
|
137
146
|
| `docs/screenshot-panel.png` | ✅ main panel: Environment, guest H.264, controls |
|
|
138
147
|
| `docs/screenshot-sidebar.png` | ✅ right-sidebar layout next to a session |
|
|
139
|
-
| `docs/demo.gif` |
|
|
148
|
+
| `docs/demo.gif` | ✅ 28 s loop (720×1280, 3.2 MiB); reproducible from the guest-side screencap loop in [DEMO.md](DEMO.md) |
|
|
140
149
|
|
|
141
150
|
The [Performance](#performance) and [Verification](#verification) sections list exactly what was
|
|
142
151
|
measured, on which host, and how. Real `apk_vm` output from the reference run:
|
|
@@ -162,6 +171,12 @@ key {"text":"HOME"} -> returned to launcher
|
|
|
162
171
|
installed, and — when `allowSetupDownloads: true` — install missing SDK components, or
|
|
163
172
|
**bootstrap a completely empty host** (download Google command-line tools, extract, accept
|
|
164
173
|
licenses, install platform-tools/emulator/build-tools/platform).
|
|
174
|
+
- **Zero-config first run (即装即用).** `autoSetup: true` (default) provisions a completely cold
|
|
175
|
+
host on first use: it downloads a SHA-256-verified Temurin JDK 17 from Adoptium, bootstraps the
|
|
176
|
+
SDK command-line tools, installs `platform-tools`/`emulator`/`build-tools`/`platforms`, the
|
|
177
|
+
configured system image and the AVD, with live progress plus cancel/retry in the Environment
|
|
178
|
+
card (`autoSetup` on `GET/POST /apk-vm/setup`). The normal `autoStart` flow then boots the VM;
|
|
179
|
+
set `autoSetup: false` to keep setup manual.
|
|
165
180
|
- **Multi-agent isolation / multi-instance.** Several DSH Agents can drive separate VMs at the
|
|
166
181
|
same time: each conversation owns a renewable lease on the VM it uses, so a second
|
|
167
182
|
conversation never silently steals the first one's emulator. The first conversation gets the
|
|
@@ -212,6 +227,25 @@ key {"text":"HOME"} -> returned to launcher
|
|
|
212
227
|
- **Installed-app management.** The panel's **Installed apps** card lists third-party packages
|
|
213
228
|
for the active instance and offers force-stop, clear-data and uninstall; it uses the same
|
|
214
229
|
rooted `debug/packages` + `debug/action` API as the Agent tool.
|
|
230
|
+
- **Remembered APKs and auto-reinstall.** APKs installed through the panel or the tool are
|
|
231
|
+
remembered in `<profile>/.apk-vm/installed-apps.json` (path, package, label, launch activity,
|
|
232
|
+
instance). When a quick-boot snapshot reset, a recreated AVD or a plugin/emulator upgrade leaves
|
|
233
|
+
the guest without one of those packages, the plugin reinstalls it automatically on the next boot
|
|
234
|
+
(`autoReinstall: true`, default) and records the pass in the activity journal. Uploaded APKs are
|
|
235
|
+
archived under `<profile>/.apk-vm/apks` (newest 10) so the reinstall does not depend on the
|
|
236
|
+
original temp file.
|
|
237
|
+
- **Agent activity log (图形化工作日志).** Every `apk_vm` tool call is journaled locally — action,
|
|
238
|
+
bounded argument preview, result, error, duration, instance, and an optional screenshot for
|
|
239
|
+
mutating actions. The sidebar **Agent activity** card renders it as a filterable timeline with
|
|
240
|
+
thumbnails, a full-screen overlay and 3 s auto-refresh, so you can see exactly what an Agent did
|
|
241
|
+
to the VM. See [Agent activity log](#agent-activity-log).
|
|
242
|
+
- **Device resilience and recovery.** Screenshot timeouts return a structured
|
|
243
|
+
`DEVICE_UNRESPONSIVE`-style error with an actionable message instead of a bare 180 s timeout;
|
|
244
|
+
`ui_dump`/`inspect_ui` supplement WebView content with a guest-side `uiautomator dump` text
|
|
245
|
+
fallback; `shell` gains an explicit `root: true` path (`su 0`); `tap`/`text` can verify and
|
|
246
|
+
retry; network mode switches repair the guest default route; watchdog/ANR crashes are detected
|
|
247
|
+
with a recovery hint; reinstall re-grants the install/unknown-sources appop on debug VMs.
|
|
248
|
+
See [Troubleshooting](#troubleshooting) for each case.
|
|
215
249
|
- **Optional [`dsh-better-sidebar`](https://github.com/omdsh-dev/DSH-better-sidebar) tab.**
|
|
216
250
|
When that community plugin is installed, this plugin registers a real tab type
|
|
217
251
|
(`apk-vm:preview`) through its service — no fork, no DOM hacks, and it degrades cleanly when
|
|
@@ -282,7 +316,14 @@ to the running WebView: it discovers `webview_devtools_remote` sockets, forwards
|
|
|
282
316
|
`tap_selector`, `tap_css`, `type_text`, `wait_for`.
|
|
283
317
|
- `webviewAction=list` returns sanitized target metadata (`id`, `title`, `url`, `type`), never a
|
|
284
318
|
DevTools WebSocket URL or token. Select a target with `targetId` or `webviewTarget`.
|
|
285
|
-
- `webviewAction=eval` evaluates a
|
|
319
|
+
- `webviewAction=eval` evaluates a single JavaScript expression and returns `result.value` plus a
|
|
320
|
+
compact preview in `summary`. JSON values come back as-is; values that do not survive
|
|
321
|
+
`JSON.stringify` by value (`DOMRect`, `MediaQueryList`, other objects) come back as a JSON-safe
|
|
322
|
+
property snapshot, so `document.querySelector("#x").getBoundingClientRect().width` and
|
|
323
|
+
`matchMedia("(pointer: coarse)").matches` read correctly instead of returning `null`. Statement
|
|
324
|
+
blocks fall back to plain CDP evaluation (no property snapshot; the result is whatever the
|
|
325
|
+
runtime returns, often `null`); wrap a sequence in an expression instead: `(() => { const r = document.querySelector("#x").getBoundingClientRect(); return { width: r.width, height: r.height }; })()`.
|
|
326
|
+
- `click` and `wait_for` accept
|
|
286
327
|
ordinary CSS and `testid:VALUE` (which maps to `[data-testid="VALUE"]`). **Open** shadow roots
|
|
287
328
|
are traversed; closed shadow roots and iframes are not.
|
|
288
329
|
- `tap_selector` uses the same deep query and clicks through CDP. `tap_css` is for canvas or
|
|
@@ -297,6 +338,8 @@ Example Agent sequence for a hybrid App:
|
|
|
297
338
|
|
|
298
339
|
```text
|
|
299
340
|
apk_vm { action: "webview", webviewAction: "list" }
|
|
341
|
+
apk_vm { action: "webview", webviewAction: "eval", script: "matchMedia('(pointer: coarse)').matches" }
|
|
342
|
+
apk_vm { action: "webview", webviewAction: "eval", script: "document.querySelector('#file-card').getBoundingClientRect()" }
|
|
300
343
|
apk_vm { action: "webview", webviewAction: "click", selector: "testid:login" }
|
|
301
344
|
apk_vm { action: "type_text", text: "中文角色名" }
|
|
302
345
|
apk_vm { action: "wait_for", selector: "[data-testid=home]" }
|
|
@@ -393,6 +436,48 @@ or `project`), session id, workspace, and `since` / `lastSeenAt` timestamps; lea
|
|
|
393
436
|
- Closing a DSH conversation (the `session/disposed` event) automatically releases its leases,
|
|
394
437
|
with the 30-minute TTL as a fallback if that event is unavailable.
|
|
395
438
|
|
|
439
|
+
## Multiple instances, physical devices and snapshots
|
|
440
|
+
|
|
441
|
+
- **Isolated extra instances.** `POST /apk-vm/instances {"name":"agent-a","start":true}` creates a
|
|
442
|
+
dedicated AVD + emulator (+ its own H.264 stream) for another Agent conversation; lease rules
|
|
443
|
+
are in [VM ownership](#vm-ownership-and-dedicated-conversationproject-vms). Extra instances are
|
|
444
|
+
idle-stopped after `instanceIdleMs`; the AVD is kept for quick reuse.
|
|
445
|
+
- **Physical / network devices.** `GET /apk-vm/devices` lists adb devices;
|
|
446
|
+
`POST /apk-vm/device {"serial":"…"}` attaches an online USB/physical/network device and
|
|
447
|
+
detaches back to the managed AVD with `{"serial":""}`. `GET/POST /apk-vm/remote` manages an
|
|
448
|
+
SSH adb tunnel (`allowRemote` / `remote` config; never a shell). The Environment card offers
|
|
449
|
+
the same attach/detach actions.
|
|
450
|
+
- **Named AVD snapshots.** `GET /apk-vm/snapshots` lists snapshots;
|
|
451
|
+
`POST /apk-vm/snapshots {"action":"save|load|delete","name":"…"}` manages them. The quick-boot
|
|
452
|
+
snapshot (`snapshotName`, default `default_boot`) is handled automatically. The panel's
|
|
453
|
+
Snapshot card stores, restores and deletes snapshots and shows their footprint; they live under
|
|
454
|
+
`~/.android/avd/<avd>.avd/snapshots/`.
|
|
455
|
+
|
|
456
|
+
## Agent activity log
|
|
457
|
+
|
|
458
|
+
Every `apk_vm` tool call and every mutating panel/HTTP action (tap, swipe, typed text, install,
|
|
459
|
+
snapshot save/load, debug shell, ...) is journaled locally, so you can see what an Agent — or a
|
|
460
|
+
person clicking in the panel — actually did to the VM, when, and with what result. The panel adds
|
|
461
|
+
a sidebar **Activity** card that renders the journal as a timeline.
|
|
462
|
+
|
|
463
|
+
- Storage: `<profile>/.apk-vm/activity/activity.jsonl` plus `screenshots/<id>.png`; ring-pruned
|
|
464
|
+
(1000 entries / 250 MB by default). `activityDir` overrides the location.
|
|
465
|
+
- Each entry records `source` (`tool` for the agent tool, `http` for panel/API operations,
|
|
466
|
+
`system`), `tool` (`apk_vm`, `panel` or a client label), `action`, `summary`, `ok` / `error`,
|
|
467
|
+
`durationMs`, `instanceId`, a bounded `argsPreview`, and an optional screenshot for mutating
|
|
468
|
+
actions (`tap`/`swipe`/`key`/`text`/`install`/`type_text`/…).
|
|
469
|
+
- HTTP (same origin, local only):
|
|
470
|
+
`GET /apk-vm/activity?limit=&beforeId=&action=&instanceId=&source=&ok=` (newest first + `stats`),
|
|
471
|
+
`GET /apk-vm/activity/<id>` (one entry), `GET /apk-vm/activity/<id>/shot` (PNG),
|
|
472
|
+
`POST /apk-vm/activity/clear`.
|
|
473
|
+
- The card filters by source (Agent/User) / instance / action / errors only, lazy-loads thumbnails, opens a full-screen
|
|
474
|
+
overlay with metadata, auto-refreshes every 3 s while open and clears with a confirmation.
|
|
475
|
+
- The journal is local-only and is never uploaded, but it can contain screen content and command
|
|
476
|
+
arguments — clear it before recording or sharing the panel. Typed text is journaled as a
|
|
477
|
+
character count, not its content.
|
|
478
|
+
|
|
479
|
+
A worked, dependency-free example is in [examples/agent-workflow.mjs](examples/agent-workflow.mjs): it drives state → install → UI tree → tap → assertion → screenshot and then prints the activity timeline the call just produced.
|
|
480
|
+
|
|
396
481
|
## Storage management
|
|
397
482
|
|
|
398
483
|
`GET /apk-vm/storage` reports the logical size of every AVD, its quick-boot snapshots, the
|
|
@@ -470,10 +555,10 @@ APK, private key or host-specific path is required.
|
|
|
470
555
|
| Requirement | Notes |
|
|
471
556
|
| --- | --- |
|
|
472
557
|
| **DeepSeek Harness** | A profile that can install local plugin bundles (the desktop Web UI or any agent with the `plugin_manager` tool). |
|
|
473
|
-
| **Android SDK** | `platform-tools` (adb), `emulator`, `build-tools` (for `aapt2`), command-line tools (`sdkmanager`/`avdmanager`) and an AOSP system image.
|
|
558
|
+
| **Android SDK** | `platform-tools` (adb), `emulator`, `build-tools` (for `aapt2`), command-line tools (`sdkmanager`/`avdmanager`) and an AOSP system image. The SDK command-line tools need a JDK (17 works); on a cold machine the default `autoSetup` downloads a portable Temurin JDK 17 and bootstraps the SDK itself. |
|
|
474
559
|
| **AOSP system image** | `system-images;android-34;default;x86_64` (Android 14, API 34) — the image used for all measurements below. Configurable with `systemImage`. |
|
|
475
560
|
| **Hardware virtualization** | Required for the x86_64 image: AEHD or WHPX on Windows, KVM on Linux, HVF on macOS. See [acceleration matrix](#cpu-acceleration-matrix). |
|
|
476
|
-
| **Disk / RAM** | A few GB for the SDK + system image and the AVD; an emulator with a modern desktop GPU is recommended. |
|
|
561
|
+
| **Disk / RAM** | A few GB for the SDK + system image and the AVD (first-run provisioning downloads roughly 2.5 GB: JDK ≈190 MB + command-line tools + SDK packages + system image); an emulator with a modern desktop GPU is recommended. |
|
|
477
562
|
| **Node.js 24+** *(optional)* | Only for running this repository's checks ([Verification](#verification)). The plugin itself has no npm dependencies. |
|
|
478
563
|
|
|
479
564
|
The plugin's **Environment** card performs this check for you (see
|
|
@@ -527,13 +612,29 @@ Then pick one:
|
|
|
527
612
|
After installing or upgrading the plugin, **reload the DSH Web page** so the new client bundle
|
|
528
613
|
is loaded.
|
|
529
614
|
|
|
530
|
-
### 3. Provide an Android SDK, system image and AVD
|
|
615
|
+
### 3. Provide an Android SDK, system image and AVD (automatic by default)
|
|
616
|
+
|
|
617
|
+
With the shipped `autoSetup: true` this step is automatic: the first `/apk-vm/state` or
|
|
618
|
+
`/apk-vm/setup` request — opening the panel, or an Agent's first `apk_vm` call — detects what is
|
|
619
|
+
missing and provisions it in the background while the **Environment** card shows the current
|
|
620
|
+
step. The chain is:
|
|
621
|
+
|
|
622
|
+
1. **JDK 17** — when no system JDK/`JAVA_HOME` is found, a portable Temurin build is downloaded
|
|
623
|
+
from Adoptium (`api.adoptium.net`, SHA-256 verified) into `~/.dsh/apk-vm/jdk` (override with
|
|
624
|
+
`jdkRoot`). Adoptium's archive is hosted on GitHub; when that is unreachable (for example on
|
|
625
|
+
mainland-China networks) a built-in Tsinghua mirror is tried next with the same checksum.
|
|
626
|
+
2. **Command-line tools** — `commandlinetools` are unpacked and SDK licenses accepted.
|
|
627
|
+
3. **SDK packages** — `platform-tools`, `emulator`, `build-tools` and `platforms`.
|
|
628
|
+
4. **System image** — the configured `systemImage` (default `system-images;android-34;default;x86_64`).
|
|
629
|
+
5. **AVD** — `avdName` (default `dsh_apk`) is created.
|
|
630
|
+
|
|
631
|
+
**Cancel** / **Retry** are available in the card, and the same state is exposed as `autoSetup`
|
|
632
|
+
in `GET /apk-vm/setup`. Set `autoSetup: false` to provision manually instead:
|
|
531
633
|
|
|
532
634
|
The plugin auto-discovers the SDK (`sdkRoot`, `ANDROID_HOME`, `ANDROID_SDK_ROOT`, then common
|
|
533
|
-
per-OS locations) and adb/emulator
|
|
534
|
-
|
|
535
|
-
`
|
|
536
|
-
otherwise install it yourself:
|
|
635
|
+
per-OS locations) and adb/emulator; the Environment card's one-click actions remain available as
|
|
636
|
+
a fallback (including **Create AVD** and, with `allowSetupDownloads: true`, an
|
|
637
|
+
`sdkmanager --install` for the image). The manual commands are:
|
|
537
638
|
|
|
538
639
|
```bash
|
|
539
640
|
sdkmanager --install "platform-tools" "emulator" "build-tools;34.0.0" \
|
|
@@ -575,7 +676,12 @@ config:
|
|
|
575
676
|
instanceReapIntervalMs: 60000
|
|
576
677
|
leaseTtlMs: 1800000 # VM owner lease lifetime; renewed by apk_vm calls
|
|
577
678
|
allowRemote: false # reject non-loopback VM API clients
|
|
578
|
-
|
|
679
|
+
autoSetup: true # zero-config first run: auto-provision JDK 17 + SDK + image + AVD
|
|
680
|
+
# jdkRoot: 'C:/tools/dsh-jdk' # where the auto-downloaded JDK 17 lives
|
|
681
|
+
# jdkVersion: 17 # Temurin major version to provision (known-good table covers 17.0.21+9)
|
|
682
|
+
# jdkMirror: 'https://mirrors.tuna.tsinghua.edu.cn/Adoptium' # override the JDK mirror fallback
|
|
683
|
+
# activityDir: 'C:/tools/apk-vm-activity' # journal + screenshot storage (default <profile>/.apk-vm/activity)
|
|
684
|
+
allowSetupDownloads: false # gate the optional manual system-image download action
|
|
579
685
|
scrcpy: true
|
|
580
686
|
scrcpyMaxSize: 960
|
|
581
687
|
scrcpyMaxFps: 60
|
|
@@ -590,10 +696,12 @@ to attach an existing device instead.
|
|
|
590
696
|
|
|
591
697
|
### 5. First run
|
|
592
698
|
|
|
593
|
-
1. Open the DSH sidebar and click **APK Virtual Machine**.
|
|
594
|
-
|
|
595
|
-
|
|
596
|
-
|
|
699
|
+
1. Open the DSH sidebar and click **APK Virtual Machine**. On a cold machine the **Environment**
|
|
700
|
+
card shows **Setup needed** and starts the automatic provisioning chain (progress with
|
|
701
|
+
**Cancel** / **Retry**; see
|
|
702
|
+
[step 3](#3-provide-an-android-sdk-system-image-and-avd-automatic-by-default)). Green
|
|
703
|
+
**Ready** means the SDK, image, AVD and acceleration were found. Hypervisor setup is the one
|
|
704
|
+
prerequisite the plugin cannot do for you — see [Prerequisites](#1-prerequisites).
|
|
597
705
|
2. Press **Start VM** (or let `prewarm`/`autoStart` boot it). The **first start is a cold boot**
|
|
598
706
|
(measured 29.5 s on the reference host); the plugin then saves the quick-boot snapshot
|
|
599
707
|
`default_boot`, and later starts restore it (measured 8.4–10.5 s).
|
|
@@ -618,7 +726,7 @@ All keys are optional; defaults are shown in the **Default** column.
|
|
|
618
726
|
| `port` | `5558` | Emulator console port used when spawning. |
|
|
619
727
|
| `sdkRoot` | `ANDROID_HOME` / `ANDROID_SDK_ROOT` | Android SDK root for `adb`, `aapt2`, `emulator-check`, `sdkmanager`/`avdmanager`. |
|
|
620
728
|
| `adbPath` | `<sdk>/platform-tools/adb` | Explicit adb executable. |
|
|
621
|
-
| `systemImage` | `system-images;android-34;default;x86_64` | System image required by the Environment card and used for AVD creation. |
|
|
729
|
+
| `systemImage` | `system-images;android-34;default;x86_64` (`arm64-v8a` on arm64 hosts) | System image required by the Environment card and used for AVD creation. |
|
|
622
730
|
| `spawnEmulator` | `true` | Set `false` to only attach (never spawn). |
|
|
623
731
|
| `emulatorArgs` | `[]` | Extra argv appended to the emulator command line. |
|
|
624
732
|
| `roots` | `[]` | Extra APK discovery roots. The DSH working directory, `process.cwd()` and the home directory are added automatically. |
|
|
@@ -632,6 +740,7 @@ All keys are optional; defaults are shown in the **Default** column.
|
|
|
632
740
|
| `prewarm` | `false` | Boot the VM in the background shortly after plugin activation. |
|
|
633
741
|
| `prewarmDelayMs` | `3000` | Delay before the prewarm start. |
|
|
634
742
|
| `autoStart` | `true` | Start the VM on the first `/apk-vm/state` or `/apk-vm/frame` request. |
|
|
743
|
+
| `autoReinstall` | `true` | Remember APKs installed through the plugin and reinstall missing ones on the next boot (registry in `<profile>/.apk-vm/installed-apps.json`, archived APKs in `<profile>/.apk-vm/apks`). Set `false` to opt out. |
|
|
635
744
|
| `multiInstance` | `true` | Allow isolated extra VMs for concurrent Agents. |
|
|
636
745
|
| `maxInstances` | `3` | Maximum number of extra instances (in addition to the default VM). Each running instance costs guest RAM/CPU. |
|
|
637
746
|
| `instanceIdleMs` | `900000` | Stop an extra instance after this long without panel frames, a video client, or an Agent command (AVD is kept). |
|
|
@@ -639,6 +748,11 @@ All keys are optional; defaults are shown in the **Default** column.
|
|
|
639
748
|
| `leaseTtlMs` | `1800000` | Lifetime of a VM owner lease. Every `apk_vm` call that routes to the VM renews it; set `0` to disable expiry. |
|
|
640
749
|
| `allowRemote` | `false` | Allow non-loopback clients to reach `/apk-vm/*` and `/apk-vm/ws` (only behind your own authenticated proxy). |
|
|
641
750
|
| `allowSetupDownloads` | `false` | Allow the Environment card's `install-image` action to run `sdkmanager --install` (large download). |
|
|
751
|
+
| `autoSetup` | `true` | Provision a missing JDK 17 / SDK packages / system image / AVD automatically on first use (roughly 2.5 GB on a cold machine). Set `false` to keep setup manual. |
|
|
752
|
+
| `jdkRoot` | `~/.dsh/apk-vm/jdk` | Where the auto-downloaded Temurin JDK 17 is installed. A system JDK / `JAVA_HOME` is preferred when present. |
|
|
753
|
+
| `jdkVersion` | `17` | Temurin major version to provision when `autoSetup` needs a JDK. |
|
|
754
|
+
| `jdkMirror` | built-in Tsinghua mirror | Mirror base URL (or array of bases) used for the Temurin JDK archive when the GitHub-hosted Adoptium download is unreachable, verified with the same SHA-256 checksum. Env: `DSH_APK_VM_JDK_MIRROR`; an empty value disables the fallback. |
|
|
755
|
+
| `activityDir` | `<profile>/.apk-vm/activity` | Where the Agent activity journal (`activity.jsonl`) and its screenshots are stored. |
|
|
642
756
|
| `frameFps` | `2` | PNG fallback target frame rate, 1–10 (the H.264 path is not affected). |
|
|
643
757
|
| `scrcpy` | `true` | Enable the H.264/WebCodecs transport. |
|
|
644
758
|
| `scrcpyMaxSize` | `960` | Encoder max size; 960 yields 540×960 video. |
|
|
@@ -649,8 +763,12 @@ All keys are optional; defaults are shown in the **Default** column.
|
|
|
649
763
|
|
|
650
764
|
The Environment report (`GET /apk-vm/setup`) returns `ok`, `platform`, `sdkRoot`, `adbPath`,
|
|
651
765
|
`emulatorPath`, `avdmanagerPath`, `sdkmanagerPath`, `emulatorVersion`, `systemImage` +
|
|
652
|
-
`systemImagePresent`, `avdName` + `avdPresent` + `avdPath`, `
|
|
653
|
-
detail }`, `hypervisorNotes`, `missing[]` and `actions[]` with
|
|
766
|
+
`systemImagePresent`, `avdName` + `avdPresent` + `avdPath`, `javaHome` + `javaPresent`,
|
|
767
|
+
`accel { available, backend, detail }`, `hypervisorNotes`, `missing[]` and `actions[]` with
|
|
768
|
+
per-action availability. It also carries the auto-setup state: `autoSetupEnabled` plus
|
|
769
|
+
`autoSetup { state, step, totalSteps, stepId, message, error, warnings[], startedAt,
|
|
770
|
+
finishedAt }`; `POST /apk-vm/setup` with `{ action: "auto-setup" }` starts/retries provisioning
|
|
771
|
+
and `{ action: "cancel-auto-setup" }` cancels it.
|
|
654
772
|
|
|
655
773
|
---
|
|
656
774
|
|
|
@@ -683,7 +801,9 @@ detail }`, `hypervisorNotes`, `missing[]` and `actions[]` with per-action availa
|
|
|
683
801
|
| Layer | Implementation | Role |
|
|
684
802
|
| --- | --- | --- |
|
|
685
803
|
| VM | AOSP Android Emulator (`emulator` + `system-images;android-34;default;x86_64`) | Boots the open-source Android system image; driven through adb. |
|
|
686
|
-
| Setup | [lib/setup.js](lib/setup.js) | Dependency-free SDK / adb / emulator / AVD / acceleration detection plus one-click `create-avd` and optional `install-image
|
|
804
|
+
| Setup | [lib/setup.js](lib/setup.js), [lib/jdk.js](lib/jdk.js), [lib/autosetup.js](lib/autosetup.js) | Dependency-free SDK / adb / emulator / AVD / acceleration detection plus one-click `create-avd` and optional `install-image`; `lib/jdk.js` provisions a managed Temurin JDK 17 and `lib/autosetup.js` runs the first-use auto-provisioning chain. |
|
|
805
|
+
| Journal | [lib/activity-log.js](lib/activity-log.js) | Records every `apk_vm` tool call and every mutating panel/HTTP request (`source: tool|http|system`; action, argument preview, result/error, duration, instance, screenshot for mutating actions) as local JSONL + PNGs; backs the panel timeline and the `/apk-vm/activity` routes. |
|
|
806
|
+
| Installed apps | [lib/installed-apps.js](lib/installed-apps.js) | Persists APKs installed through the plugin (`<profile>/.apk-vm/installed-apps.json`, archived copies under `<profile>/.apk-vm/apks`) and re-installs missing packages on the next boot (`autoReinstall`). |
|
|
687
807
|
| Streaming | scrcpy 5.0.1 server (`lib/vendor/scrcpy-server-v5.0.1.jar`, pushed to `/data/local/tmp/scrcpy-server.jar`) + [lib/scrcpy.js](lib/scrcpy.js) | H.264 screen capture and the scrcpy control protocol, without the desktop scrcpy client. |
|
|
688
808
|
| Device bridge | `adb` from Android SDK platform-tools | install / launch / screencap / input / logcat / file push-pull. |
|
|
689
809
|
| Plugin runtime | DSH plugin APIs (`slots`, `locale`, `webServer`, `tools`, `dsh.client`) | Sidebar entry, main panel, same-origin HTTP/WebSocket control plane, agent tool. |
|
|
@@ -736,7 +856,7 @@ JSON bodies are bounded to 64 KiB; the raw APK upload is bounded to 500 MiB.
|
|
|
736
856
|
| --- | --- | --- |
|
|
737
857
|
| GET | `/apk-vm/state` | VM state, serial, boot time/kind, accel/GPU, root/debug status, display size, current APK, stream counters, log tail. |
|
|
738
858
|
| GET | `/apk-vm/setup?force=1` | Environment report (SDK/adb/emulator/tools/image/AVD/acceleration, missing items, available actions). Cached ~15 s. |
|
|
739
|
-
| POST | `/apk-vm/setup` | `{"action":"refresh"\|"create-avd"\|"install-image"\|"install-tools"\|"bootstrap-sdk"}
|
|
859
|
+
| POST | `/apk-vm/setup` | `{"action":"refresh"\|"create-avd"\|"install-image"\|"install-tools"\|"bootstrap-sdk"}` plus `"auto-setup"` / `"cancel-auto-setup"` for first-use provisioning. `install-tools`/`bootstrap-sdk` accept optional `packages`; manual download actions require `allowSetupDownloads: true` or `confirmDownload: true` (otherwise `403`). |
|
|
740
860
|
| GET | `/apk-vm/apks` | Discover `*.apk` files under the configured roots. |
|
|
741
861
|
| GET | `/apk-vm/apk-info?path=…` | Static APK metadata (package/version/targetSdk/permissions/features/native code/launch activity/icon path) via `aapt2`. |
|
|
742
862
|
| GET/HEAD | `/apk-vm/apk-icon?path=…` | Extract the raster launcher icon from the APK ZIP (PNG/WebP/JPEG). |
|
|
@@ -761,6 +881,9 @@ JSON bodies are bounded to 64 KiB; the raw APK upload is bounded to 500 MiB.
|
|
|
761
881
|
| POST | `/apk-vm/instances` | `{"name":"agent-a","start":true}` — create an isolated AVD/VM; every extra instance has its own H.264 stream. |
|
|
762
882
|
| DELETE | `/apk-vm/instances/:id` | Stop/dispose an extra instance (the default cannot be destroyed). |
|
|
763
883
|
| GET/POST | `/apk-vm/instances/:id/...` | Per-instance mirror of `state`, `frame`, `vm`, `input`, `install`, `upload`, `debug/*`. |
|
|
884
|
+
| GET | `/apk-vm/activity?limit=&beforeId=&action=&instanceId=&ok=` | Agent activity journal, newest first, with `stats`; `enabled: true`. |
|
|
885
|
+
| GET | `/apk-vm/activity/<id>/shot` | PNG screenshot attached to one activity entry. |
|
|
886
|
+
| POST | `/apk-vm/activity/clear` | Clear the activity journal and its screenshots. |
|
|
764
887
|
|
|
765
888
|
Uploaded APKs are written under `<os temp>/dsh-apk-vm-uploads` and that directory is removed
|
|
766
889
|
when the plugin is disposed (best-effort stale-file cleanup also runs before each upload).
|
|
@@ -955,6 +1078,8 @@ for f in lib/*.js; do node --check "$f"; done
|
|
|
955
1078
|
node spike/ui-smoke.cjs
|
|
956
1079
|
node spike/ui-better-sidebar-smoke.cjs
|
|
957
1080
|
node spike/setup-smoke.mjs
|
|
1081
|
+
node spike/cdp-test.mjs
|
|
1082
|
+
node spike/installed-apps-test.mjs
|
|
958
1083
|
node spike/android/mock-device.mjs
|
|
959
1084
|
node spike/android/launch-plan.mjs
|
|
960
1085
|
```
|
|
@@ -969,15 +1094,32 @@ node spike/android/launch-plan.mjs
|
|
|
969
1094
|
### The Environment card says "Setup needed"
|
|
970
1095
|
|
|
971
1096
|
The report lists each missing item: SDK path, `adb`, emulator, `sdkmanager`/`avdmanager`, the
|
|
972
|
-
configured system image, the AVD, or CPU acceleration.
|
|
973
|
-
|
|
974
|
-
|
|
975
|
-
|
|
976
|
-
- Missing
|
|
977
|
-
|
|
978
|
-
- Missing
|
|
1097
|
+
configured system image, the AVD, or CPU acceleration. With the default `autoSetup: true` the
|
|
1098
|
+
card starts provisioning automatically; while it runs you see the current step plus **Cancel** /
|
|
1099
|
+
**Retry**.
|
|
1100
|
+
|
|
1101
|
+
- Missing JDK: auto-setup downloads Temurin JDK 17 into `~/.dsh/apk-vm/jdk` automatically; a
|
|
1102
|
+
system JDK / `JAVA_HOME` is used instead when present.
|
|
1103
|
+
- Missing SDK/emulator: auto-setup installs the SDK packages; or set `sdkRoot` (or
|
|
1104
|
+
`ANDROID_HOME` / `ANDROID_SDK_ROOT`) to an existing SDK.
|
|
1105
|
+
- Missing system image: auto-setup installs it; or install it with `sdkmanager`, or set
|
|
1106
|
+
`allowSetupDownloads: true` and use **Download image** in the card.
|
|
1107
|
+
- Missing AVD: auto-setup creates it; or use **Create AVD** / run
|
|
979
1108
|
`avdmanager create avd -n dsh_apk -k "system-images;android-34;default;x86_64"`.
|
|
980
|
-
- Missing acceleration: see the next section
|
|
1109
|
+
- Missing acceleration: see the next section — this is a host-level requirement auto-setup cannot
|
|
1110
|
+
satisfy.
|
|
1111
|
+
|
|
1112
|
+
### Auto-setup fails or is stuck
|
|
1113
|
+
|
|
1114
|
+
The card shows the last step and the error (`autoSetup.error` in `GET /apk-vm/setup`). Common
|
|
1115
|
+
causes: no network access to `api.adoptium.net` / `dl.google.com` (or to `github.com`, where
|
|
1116
|
+
Adoptium hosts the JDK archive — the built-in Tsinghua mirror is tried automatically), a proxy or
|
|
1117
|
+
firewall, an antivirus locking freshly extracted files, or less than ~3 GB free disk space. Press
|
|
1118
|
+
**Retry**: the JDK archive is reused when its SHA-256 checksum matches, so retries do not
|
|
1119
|
+
re-download it; a mirror can be pinned with `jdkMirror` (or `DSH_APK_VM_JDK_MIRROR`).
|
|
1120
|
+
You can also set `autoSetup: false` and provision manually (see
|
|
1121
|
+
[step 3](#3-provide-an-android-sdk-system-image-and-avd-automatic-by-default)); parts that already
|
|
1122
|
+
succeeded are skipped on the next attempt.
|
|
981
1123
|
|
|
982
1124
|
### "No usable CPU hypervisor (AEHD/WHPX) was found"
|
|
983
1125
|
|
|
@@ -1027,6 +1169,92 @@ is not expected to finish booting that way.
|
|
|
1027
1169
|
- If a stale offline adb emulator is attached, `adb kill-server` (or kill the leftover
|
|
1028
1170
|
`emulator`/`qemu-system-*` process) and retry.
|
|
1029
1171
|
|
|
1172
|
+
### `push` reports "outside the allowed roots" or "local file not found"
|
|
1173
|
+
|
|
1174
|
+
`apk_vm push` accepts only local files under the allowed roots: the DSH workspace,
|
|
1175
|
+
`process.cwd()`, the home directory and the OS temp dir, plus anything you add to `roots`.
|
|
1176
|
+
The two failures are distinct now — *outside the allowed roots* lists the roots and how to extend
|
|
1177
|
+
them; *local file not found* means the path really does not exist (both used to share one
|
|
1178
|
+
misleading message). On Windows the comparison is case- and separator-insensitive after
|
|
1179
|
+
`realpath` normalization, so mixed separators in the same home directory match. If the file legitimately
|
|
1180
|
+
lives elsewhere, add its directory to `roots` in the plugin config, or copy it under the
|
|
1181
|
+
workspace / temp dir first.
|
|
1182
|
+
|
|
1183
|
+
### `adb` or `storage` tool actions fail with a JavaScript error
|
|
1184
|
+
|
|
1185
|
+
Fixed in 1.0.0: `adb` used to fail with `Cannot access 'api' before initialization` for every
|
|
1186
|
+
call (an initialization-order bug) and `storage` failed with `storageSdkRoot is not defined`.
|
|
1187
|
+
Both paths are covered by `spike/tool-core-test.mjs`; no configuration workaround is needed after
|
|
1188
|
+
updating.
|
|
1189
|
+
|
|
1190
|
+
### A screenshot times out, the WebView UI tree is empty, or taps seem lost
|
|
1191
|
+
|
|
1192
|
+
- A screenshot that hangs usually means the guest UI is wedged (`SurfaceFlinger`/`system_server`
|
|
1193
|
+
stopped producing frames). The tool now returns a structured error (`DEVICE_UNRESPONSIVE` /
|
|
1194
|
+
`SCREENSHOT_TIMEOUT`) with a recovery hint instead of an opaque timeout, and the optional
|
|
1195
|
+
auto-recovery path (adb reconnect, then at most one emulator reboot with a cooldown) is used
|
|
1196
|
+
when enabled. A quick manual recovery is `apk_vm reboot`, or stop/start the VM in the panel.
|
|
1197
|
+
- `ui_dump` / `inspect_ui` on a WebView can return very few nodes with no visible text. The tool
|
|
1198
|
+
now supplements the tree with a guest-side `uiautomator dump` text pass, so card titles and
|
|
1199
|
+
button labels inside WebViews still show up (the original UIAutomator JSON shape is
|
|
1200
|
+
unchanged).
|
|
1201
|
+
- A `tap` inside a WebView that appears to do nothing may have been injected but ignored by the
|
|
1202
|
+
page. `tap` can verify the frame changed and retry once with a small offset; when the screen is
|
|
1203
|
+
byte-identical before and after, the result reports `changed: false` so you can distinguish a
|
|
1204
|
+
lost injection from a page that is genuinely stuck.
|
|
1205
|
+
- `shell` runs as the `shell` user (`uid 2000`) even though the VM is rooted. Use the explicit
|
|
1206
|
+
root path (`shell` with `root: true`, i.e. `su 0 sh -c …`) for `/data/data` reads and
|
|
1207
|
+
`shared_prefs` writes; writing app-private files also needs the app's SELinux category
|
|
1208
|
+
(`u:object_r:app_data_file:s0:c<…>`) because `toybox chcon` has no `--reference`.
|
|
1209
|
+
- Chinese `text` injection can succeed on the input channel but not reach a WebView field; the
|
|
1210
|
+
text path now verifies the field and falls back to a clipboard/`input text` style delivery,
|
|
1211
|
+
reporting which method worked.
|
|
1212
|
+
|
|
1213
|
+
### Panel / WebView testing from a phone
|
|
1214
|
+
|
|
1215
|
+
Driving the panel and a hybrid App from a phone surfaces a few coordinate and lifecycle pitfalls:
|
|
1216
|
+
|
|
1217
|
+
- **Coordinates are physical pixels.** The panel streams a 720×1280 screen and `tap`/`swipe`
|
|
1218
|
+
take device pixels, while `getBoundingClientRect()` inside the WebView returns CSS pixels at
|
|
1219
|
+
the page's device pixel ratio (2 on the default AVD). Convert with `info.coordinateMap`:
|
|
1220
|
+
`device = round(css * dpr) + offset`. Prefer `tap_css` / `tap_selector` (both CDP-based) for
|
|
1221
|
+
DOM UI instead of converting by hand; `tap_css` is for canvas / non-DOM UI.
|
|
1222
|
+
- **Pin the instance.** When more than one VM exists, pass `instance: "default"` (or the id you
|
|
1223
|
+
own) on every `apk_vm` call so a start or install never lands on a clean extra instance.
|
|
1224
|
+
- **`webviewAction=eval` now returns values**, including non-JSON-by-value objects (`DOMRect`,
|
|
1225
|
+
`MediaQueryList`) via a property snapshot — see
|
|
1226
|
+
[WebView and Chrome DevTools Protocol](#webview-and-chrome-devtools-protocol).
|
|
1227
|
+
- **The soft keyboard moves the layout.** Typing raises the keyboard and pans the page, so a
|
|
1228
|
+
second `tap` can land on the previous field and concatenate account/password. Send `BACK` after
|
|
1229
|
+
each field before tapping the next one, or use `insert_text` / `type_text` with a selector.
|
|
1230
|
+
- **A wedged emulator can make the guest look reset.** If `screencap` hangs and the state flips to
|
|
1231
|
+
`starting`, stop/start the instance or `apk_vm reboot`. Installed APKs are remembered and
|
|
1232
|
+
re-installed after a quick-boot reset (`autoReinstall`, default on), but Android-side login state
|
|
1233
|
+
is app data: `clear_data` wipes it. The 180 s screenshot timeout and the `adb` action error are
|
|
1234
|
+
fixed in 1.0.0 (see the earlier sections).
|
|
1235
|
+
|
|
1236
|
+
### The guest loses its network after switching to shared mode
|
|
1237
|
+
|
|
1238
|
+
Switching an instance to `shared` can leave the guest with a link-scope route but no default
|
|
1239
|
+
gateway, and a reboot clears it again. The plugin now detects and repairs the default route
|
|
1240
|
+
(`ip route add default via <emulator host alias>`) when the mode becomes shared, and the network
|
|
1241
|
+
status reports `ENETUNREACH` explicitly. If a repair still fails, reboot the VM once — the route
|
|
1242
|
+
is restored by the normal environment restore.
|
|
1243
|
+
|
|
1244
|
+
### The VM stops responding after a watchdog / ANR crash
|
|
1245
|
+
|
|
1246
|
+
A `system_server` watchdog crash (`DeadSystemException`, `WAITED_HALF`) can kill the foreground
|
|
1247
|
+
app, drop focus to `FallbackHome` and make screenshots fail. The plugin now probes a few cheap
|
|
1248
|
+
health signals and reports a structured `unresponsive` status with the ANR trace location
|
|
1249
|
+
(`/data/anr`) and a recovery action; stop/start (or `apk_vm reboot`) restores the VM.
|
|
1250
|
+
|
|
1251
|
+
### "Install unknown apps" is reset after reinstalling an APK
|
|
1252
|
+
|
|
1253
|
+
Android clears the per-package `REQUEST_INSTALL_PACKAGES` appop when a package is reinstalled, so
|
|
1254
|
+
an auto-update test can fail right after `install`. On debug/local VMs the plugin snapshots and
|
|
1255
|
+
re-grants the previously allowed appops after install (configurable); otherwise re-open the
|
|
1256
|
+
settings toggle for that package.
|
|
1257
|
+
|
|
1030
1258
|
### APK upload fails
|
|
1031
1259
|
|
|
1032
1260
|
- The upload endpoint accepts raw `.apk`/ZIP bytes up to **500 MiB**; larger files return `413`
|
|
@@ -1093,8 +1321,12 @@ before pointing the DSH Web UI at an untrusted network.
|
|
|
1093
1321
|
- **Upload and environment setup are privileged local actions.** Upload accepts only APK/ZIP
|
|
1094
1322
|
bytes up to 500 MiB and installs them into the guest; `create-avd` writes an AVD; and
|
|
1095
1323
|
`install-image` runs `sdkmanager --install` only when the user opted in with
|
|
1096
|
-
`allowSetupDownloads: true` (default `false`).
|
|
1097
|
-
|
|
1324
|
+
`allowSetupDownloads: true` (default `false`). Automatic provisioning (`autoSetup`, default
|
|
1325
|
+
`true`) also downloads the JDK 17 from `api.adoptium.net` (SHA-256 verified; when the
|
|
1326
|
+
GitHub-hosted asset is unreachable the built-in mirror is used with the same checksum) and
|
|
1327
|
+
runs the user's own `sdkmanager`/`avdmanager` for the SDK packages, image and AVD on first
|
|
1328
|
+
use; set `autoSetup: false` to disable it. All of these are reachable only from the same origin and
|
|
1329
|
+
loopback clients.
|
|
1098
1330
|
- **The `apk_vm` Agent tool is available to every agent in the DSH profile.** Grant agent access
|
|
1099
1331
|
to this plugin with the same care as giving an agent a terminal on an Android device.
|
|
1100
1332
|
- **Loopback-only by default.** In addition to the same-origin check, every `/apk-vm/*` HTTP
|
|
@@ -1104,10 +1336,14 @@ before pointing the DSH Web UI at an untrusted network.
|
|
|
1104
1336
|
- **Keep the DSH Web server local.** If you expose the DSH Web UI beyond localhost (reverse
|
|
1105
1337
|
proxy, LAN bind, tunnel), you also expose the plugin routes. Add authentication at the proxy
|
|
1106
1338
|
layer or keep the port local; do not disable the same-origin/loopback checks.
|
|
1107
|
-
- **No telemetry.** The plugin makes no network requests of its own to
|
|
1108
|
-
|
|
1109
|
-
`
|
|
1110
|
-
repository).
|
|
1339
|
+
- **No telemetry.** The plugin makes no network requests of its own to analytics or tracking
|
|
1340
|
+
services; network activity is limited to `autoSetup` provisioning (Temurin JDK from
|
|
1341
|
+
`api.adoptium.net` or its mirror, then the SDK packages/image through the user's own
|
|
1342
|
+
`sdkmanager`, which contacts Google's SDK repository) and the same-origin DSH Web server.
|
|
1343
|
+
- **The Agent activity log is local-only.** Tool-call journal entries and screenshots are written
|
|
1344
|
+
under `<profile>/.apk-vm/activity` on this host and are never sent anywhere. They can contain
|
|
1345
|
+
screen content and command arguments, so clear the journal before sharing a recording of the
|
|
1346
|
+
panel (the card has a confirmed **Clear** action, or `POST /apk-vm/activity/clear`).
|
|
1111
1347
|
|
|
1112
1348
|
To report a vulnerability, follow [SECURITY.md](SECURITY.md) — please use private disclosure,
|
|
1113
1349
|
not a public issue.
|
|
@@ -1119,13 +1355,11 @@ not a public issue.
|
|
|
1119
1355
|
The features below are **not shipped yet** — they are tracked for future releases. Everything
|
|
1120
1356
|
described above is implemented in this release.
|
|
1121
1357
|
|
|
1122
|
-
- **Physical-device
|
|
1123
|
-
|
|
1124
|
-
|
|
1358
|
+
- **Physical-device attach is available but not exhaustively verified.** `/apk-vm/devices` +
|
|
1359
|
+
`/apk-vm/device` and the SSH adb tunnel are shipped; per-device quirks (OEM adb authorization,
|
|
1360
|
+
screen size/orientation, root availability) still need a device-specific smoke test.
|
|
1125
1361
|
- **Audio streaming** — forward guest audio alongside the video stream.
|
|
1126
1362
|
- **Cloud / remote VM execution** — run the guest on a remote host and stream it to the panel.
|
|
1127
|
-
- **Static APK preview** *(optional)* — inspect an APK's manifest, resources and launcher UI
|
|
1128
|
-
without booting a full VM.
|
|
1129
1363
|
|
|
1130
1364
|
QEMU + Android-x86 for hosts without hardware virtualization and `-writable-system` image
|
|
1131
1365
|
customization remain research notes in [DESIGN.md](DESIGN.md) §8.
|
|
@@ -1135,8 +1369,9 @@ customization remain research notes in [DESIGN.md](DESIGN.md) §8.
|
|
|
1135
1369
|
## Known limitations
|
|
1136
1370
|
|
|
1137
1371
|
- **Windows x64 and Linux x86_64 are the end-to-end verified platforms.** macOS SDK/adb/
|
|
1138
|
-
emulator/AVD discovery
|
|
1139
|
-
|
|
1372
|
+
emulator/AVD discovery is implemented and `arm64` hosts automatically select the
|
|
1373
|
+
`arm64-v8a` system image, but emulator + H.264 behavior on macOS/Apple Silicon is still
|
|
1374
|
+
unverified end-to-end.
|
|
1140
1375
|
- **Hardware virtualization is mandatory** for the x86_64 AOSP image; pure TCG fails by design.
|
|
1141
1376
|
- **Quick boot is snapshot-based.** Changing AVD configuration invalidates the snapshot; recreate
|
|
1142
1377
|
it as described in [Troubleshooting](#quick-boot-fails-different-avd-configuration-black-screen-or-no-snapshot).
|
|
@@ -1144,8 +1379,10 @@ customization remain research notes in [DESIGN.md](DESIGN.md) §8.
|
|
|
1144
1379
|
transport limitation.
|
|
1145
1380
|
- **The rooted debug API is local-only by design.** Do not expose the DSH Web port to untrusted
|
|
1146
1381
|
networks.
|
|
1147
|
-
- **
|
|
1148
|
-
|
|
1382
|
+
- **The activity journal records `apk_vm` tool calls** (the path Agents normally use). Direct HTTP
|
|
1383
|
+
calls to `/apk-vm/*` from a script are not journaled; the journal is capped at 1000 entries /
|
|
1384
|
+
250 MB by default (`activityDir` changes the location; the caps are not configurable yet).
|
|
1385
|
+
- **No audio yet** (see [Roadmap](#roadmap)).
|
|
1149
1386
|
|
|
1150
1387
|
---
|
|
1151
1388
|
|
|
@@ -1166,10 +1403,12 @@ for f in lib/*.js; do node --check "$f"; done
|
|
|
1166
1403
|
node spike/ui-smoke.cjs
|
|
1167
1404
|
node spike/ui-better-sidebar-smoke.cjs
|
|
1168
1405
|
node spike/setup-smoke.mjs
|
|
1406
|
+
node spike/cdp-test.mjs
|
|
1407
|
+
node spike/installed-apps-test.mjs
|
|
1169
1408
|
node spike/android/mock-device.mjs
|
|
1170
1409
|
node spike/android/launch-plan.mjs
|
|
1171
1410
|
node spike/instances-smoke.mjs
|
|
1172
|
-
node scripts/privacy-scan.mjs
|
|
1411
|
+
node scripts/privacy-scan.mjs --untracked
|
|
1173
1412
|
```
|
|
1174
1413
|
|
|
1175
1414
|
Use [.github/ISSUE_TEMPLATE/bug_report.yml](.github/ISSUE_TEMPLATE/bug_report.yml) for bugs and
|
package/SECURITY.md
CHANGED
|
@@ -4,8 +4,8 @@
|
|
|
4
4
|
|
|
5
5
|
| Version | Supported |
|
|
6
6
|
| --- | --- |
|
|
7
|
-
| 0.
|
|
8
|
-
| < 0
|
|
7
|
+
| 1.0.x (current) | Yes |
|
|
8
|
+
| < 1.0 | No |
|
|
9
9
|
|
|
10
10
|
The plugin is a local development tool. It is not designed or hardened as a multi-tenant or
|
|
11
11
|
network-exposed service.
|
|
@@ -93,16 +93,32 @@ they demonstrate a way to exceed the stated boundaries.
|
|
|
93
93
|
`create-avd` writes an AVD under the user's AVD home. `/apk-vm/setup` `install-image` runs
|
|
94
94
|
`sdkmanager --install` only when `allowSetupDownloads: true` is configured (default `false`),
|
|
95
95
|
because it is a large network download; it is never triggered automatically.
|
|
96
|
-
8. **
|
|
97
|
-
the
|
|
98
|
-
|
|
96
|
+
8. **Automatic provisioning (`autoSetup`, default `true`) performs network downloads on first
|
|
97
|
+
use.** On the first `/apk-vm/state` or `/apk-vm/setup` request the plugin may download a
|
|
98
|
+
portable Temurin JDK 17 from `https://api.adoptium.net` — when the GitHub-hosted asset is
|
|
99
|
+
unreachable, a pinned mirror (Tsinghua Adoptium mirror, overridable with `jdkMirror` /
|
|
100
|
+
`DSH_APK_VM_JDK_MIRROR`) is used instead; the SHA-256 checksum published by Adoptium is
|
|
101
|
+
verified for every source before extraction, and extraction uses `Expand-Archive`/`tar` with an
|
|
102
|
+
argv array and a bounded archive. It then runs the user's own `sdkmanager`/`avdmanager`
|
|
103
|
+
against Google's SDK repository to install the command-line tools, `platform-tools`,
|
|
104
|
+
`emulator`, `build-tools`, `platforms`, the configured system image and the AVD. A cold
|
|
105
|
+
machine downloads roughly 2.5 GB into `~/.dsh/apk-vm` (JDK; override with `jdkRoot`) and the
|
|
106
|
+
configured SDK root. The chain is cancellable and retryable from the panel, and
|
|
107
|
+
`autoSetup: false` disables it entirely. It never downloads arbitrary URLs: the JDK asset is
|
|
108
|
+
resolved from Adoptium's API and every SDK artifact comes through the user's own
|
|
109
|
+
`sdkmanager`.
|
|
110
|
+
9. **The plugin does not send telemetry** or contact third-party services on its own; it talks
|
|
111
|
+
to the local adb/emulator and the same-origin DSH Web server. Network activity is limited to
|
|
112
|
+
the `autoSetup` provisioning described above and the user's own `sdkmanager`; no analytics,
|
|
113
|
+
identifiers or usage data are collected.
|
|
99
114
|
|
|
100
115
|
## Hardening status
|
|
101
116
|
|
|
102
117
|
The released plugin applies same-origin and loopback checks to every `/apk-vm/*` HTTP route and
|
|
103
118
|
the `/apk-vm/ws` upgrade, bounded payloads for JSON and uploads, argument-array process spawning,
|
|
104
|
-
|
|
105
|
-
artifact-download routes are part of the
|
|
106
|
-
authentication token of its own: it relies on
|
|
107
|
-
|
|
108
|
-
do not treat the rooted Android guest as a
|
|
119
|
+
a restricted push/pull path set, and checksum-verified downloads for the auto-provisioned JDK.
|
|
120
|
+
The multi-touch (`/touch`), clipboard (`/clipboard`) and artifact-download routes are part of the
|
|
121
|
+
same origin/loopback surface. There is no separate authentication token of its own: it relies on
|
|
122
|
+
the DSH Web server's session and on the operator keeping that server local/trusted. Run this
|
|
123
|
+
plugin only on a machine and local network you trust; do not treat the rooted Android guest as a
|
|
124
|
+
security boundary.
|