dsh-apk-vm 0.5.0 → 0.6.1

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # Changelog
 
+## 0.6.1
+
+Network panel completeness.
+
+### Added
+
+- Network card pcap path input and apply action (capture starts on the next emulator start).
+- `setTcpdumpPath` API/tool wiring for per-instance pcap configuration.
+
+### Fixed
+
+- Clearing the hosts list now unmounts the `/etc/hosts` bind mount instead of leaving the last
+  entries active until reboot.
+
+## 0.6.0
+
+Network controls.
+
+### Added
+
+- Port forwarding management (`forward-add` / `forward-remove`) over adb, with a host-port →
+  guest-port list and optional `shared` rules.
+- Custom DNS servers via the emulator `-dns-server` launch flag (restart required) and guest
+  `/etc/hosts` injection through a root bind mount, reapplied after boot.
+- Proxy connectivity test from inside the guest (`ping` + toybox `nc`), and current proxy
+  display in the Network card.
+- Per-instance network mode:
+  - `isolated` (default QEMU-NAT isolation)
+  - `shared` (host-mediated TCP sharing through shared port forwards)
+- Optional emulator pcap capture (`-tcpdump`) with `GET /apk-vm/network/pcap` download.
+- Network card UI for forwards, DNS, hosts, mode, test, and pcap; `apk_vm` action `network`.
+- Per-instance network route: `/apk-vm/instances/<id>/network`.
+
+### Notes
+
+- Shared mode is host-mediated TCP sharing, not L2 bridging; instances keep their own QEMU NAT.
+- DNS changes take effect on the next emulator start; hosts changes apply live and survive a
+  restart while the plugin keeps the configured entries.
+- pcap export is opt-in and only writes traffic from the emulator's user-mode network.
+
 ## 0.5.0
 
 Storage management.

package/README.md

@@ -24,7 +24,7 @@ same-origin, loopback-only debug HTTP API and an `apk_vm` Agent tool.
 > 当前 **Windows x64 与 Linux x86_64（headless）为端到端已验证平台**；macOS 仅做探测/CI
 > 覆盖，详见 `docs/LINUX-E2E.md`。
 
-**Status:** `0.5.0` · Apache-2.0 · no npm runtime dependencies · no build step.
+**Status:** `0.6.1` · Apache-2.0 · no npm runtime dependencies · no build step.
 
 This is an open-source DSH plugin published on npm as **`dsh-apk-vm`**. Repository:
 [github.com/yuxiaole-bili/dsh-apk-vm](https://github.com/yuxiaole-bili/dsh-apk-vm).
@@ -170,10 +170,11 @@ key {"text":"HOME"}       -> returned to launcher
   then save the tap / swipe / key / text sequence as a JSON flow under the OS temp directory.
   Flows can be listed, replayed with their original relative timing, downloaded or deleted.
   Agents get `flow_start`, `flow_stop`, `flow_list` and `flow_replay`.
-- **Network debugging: proxy + CA.** The Network card sets/clears the guest global HTTP proxy
-  (`settings put global http_proxy`) and installs a local `.pem`/`.crt` CA into the rooted
-  Android user CA store with the correct OpenSSL subject-hash filename; the system CA store is
-  updated when the guest allows a remount.
+- **Network debugging and port forwarding.** The Network card manages host→guest port
+  forwards, custom DNS (next emulator start), guest `/etc/hosts` via a root bind mount,
+  HTTP proxy + CA installation, isolated/shared instance modes, and a guest-side connectivity
+  test. Optional pcap capture can be downloaded from the panel. See
+  [Network controls](#network-controls).
 - **Storage panel + guarded cleanup.** A Storage card reports the AVD, snapshot, SDK, temp-file
   and free-disk footprint and offers explicit cleanups: plugin temp files, quick-boot
   snapshots for a stopped AVD, and orphan `dsh_apk_*` AVDs. Destructive actions need a second
@@ -263,7 +264,30 @@ card uses the same endpoint.
   not active.
 - `apk_vm` tool actions: `storage`, `clean_storage` (`storageAction`, `avdName`, `confirm`).
 
-## Reproducible demo
+## Network controls
+
+`GET /apk-vm/network` returns the guest addresses, current proxy, DNS, hosts count, mode,
+port forwards and pcap status. `POST /apk-vm/network` accepts `action`:
+
+```json
+{ "action": "mode", "mode": "isolated|shared" }
+{ "action": "forward-add", "localPort": 18080, "remotePort": 8080, "shared": false }
+{ "action": "forward-remove", "localPort": 18080 }
+{ "action": "dns", "servers": ["1.1.1.1"] }
+{ "action": "hosts", "entries": ["198.51.100.10 api.example.test"] }
+{ "action": "test", "host": "198.51.100.10", "port": 8080 }
+{ "action": "pcap", "path": "D:\\apk-vm-capture.pcap" }
+```
+
+- Port forwards use `adb forward tcp:<hostPort> tcp:<guestPort>`.
+- DNS is applied by the emulator `-dns-server` flag on the next start.
+- Hosts entries are bind-mounted over the guest `/etc/hosts` (root required) and reapplied
+  after a plugin-managed boot.
+- `shared` forwards are reachable from other VMs through the emulator's host alias; the
+  QEMU NAT itself remains isolated.
+- pcap capture is passed to the emulator as `-tcpdump` and starts on the next emulator start;
+  download via `GET /apk-vm/network/pcap`.
+
 
 A public, dependency-free demo lives in [examples](examples/README.md):
 

package/client.js

@@ -189,6 +189,26 @@ window.__ModuleLoader__.load({
       'network.caPath': 'CA certificate path (.pem/.crt)',
       'network.installCa': 'Install CA',
       'network.current': 'Current: {value}',
+      'network.forwards': 'Port forwards',
+      'network.forwardLocal': 'Host port',
+      'network.forwardRemote': 'Guest port',
+      'network.addForward': 'Add forward',
+      'network.remove': 'Remove',
+      'network.mode': 'Mode',
+      'network.isolated': 'Isolated',
+      'network.shared': 'Shared (host bridge)',
+      'network.dns': 'DNS servers',
+      'network.applyDns': 'Apply DNS',
+      'network.hosts': 'Hosts entries',
+      'network.applyHosts': 'Apply hosts',
+      'network.test': 'Test connectivity',
+      'network.testOk': 'Connectivity OK',
+      'network.testFail': 'Connectivity check failed',
+      'network.pcap': 'Download pcap',
+      'network.pcapPath': 'Host pcap path (.pcap, next start)',
+      'network.restartRequired': 'Restart the VM to apply custom DNS',
+      'network.sharedHint': 'Shared forwards are reachable from other VMs through the emulator host alias.',
+      'network.guestUrl': 'Guest URL: {url}',
       'flow.title': 'Flow recorder',
       'flow.start': 'Record',
       'flow.stop': 'Stop',
@@ -402,6 +422,26 @@ window.__ModuleLoader__.load({
       'network.caPath': 'CA 证书路径（.pem/.crt）',
       'network.installCa': '安装 CA',
       'network.current': '当前：{value}',
+      'network.forwards': '端口转发',
+      'network.forwardLocal': '宿主机端口',
+      'network.forwardRemote': 'Guest 端口',
+      'network.addForward': '添加转发',
+      'network.remove': '删除',
+      'network.mode': '模式',
+      'network.isolated': '隔离',
+      'network.shared': '共享（宿主桥接）',
+      'network.dns': 'DNS 服务器',
+      'network.applyDns': '应用 DNS',
+      'network.hosts': 'Hosts 条目',
+      'network.applyHosts': '应用 Hosts',
+      'network.test': '测试连通性',
+      'network.testOk': '连通性正常',
+      'network.testFail': '连通性检查失败',
+      'network.pcap': '下载 pcap',
+      'network.pcapPath': '宿主机 pcap 路径（.pcap，下次启动）',
+      'network.restartRequired': '重启虚拟机后生效自定义 DNS',
+      'network.sharedHint': '共享转发可被其他 VM 通过模拟器宿主别名访问。',
+      'network.guestUrl': 'Guest URL: {url}',
       'flow.title': '操作录制',
       'flow.start': '录制',
       'flow.stop': '停止',
@@ -1259,6 +1299,30 @@ window.__ModuleLoader__.load({
         var caPathState = React.useState('');
         var caPath = caPathState[0];
         var setCaPath = caPathState[1];
+        var networkState = React.useState(null);
+        var network = networkState[0];
+        var setNetwork = networkState[1];
+        var networkBusyState = React.useState('');
+        var networkBusy = networkBusyState[0];
+        var setNetworkBusy = networkBusyState[1];
+        var forwardLocalState = React.useState('');
+        var forwardLocal = forwardLocalState[0];
+        var setForwardLocal = forwardLocalState[1];
+        var forwardRemoteState = React.useState('');
+        var forwardRemote = forwardRemoteState[0];
+        var setForwardRemote = forwardRemoteState[1];
+        var forwardSharedState = React.useState(false);
+        var forwardShared = forwardSharedState[0];
+        var setForwardShared = forwardSharedState[1];
+        var dnsTextState = React.useState('');
+        var dnsText = dnsTextState[0];
+        var setDnsText = dnsTextState[1];
+        var hostsTextState = React.useState('');
+        var hostsText = hostsTextState[0];
+        var setHostsText = hostsTextState[1];
+        var pcapPathState = React.useState('');
+        var pcapPath = pcapPathState[0];
+        var setPcapPath = pcapPathState[1];
 
         var actualFpsState = React.useState(0);
         var actualFps = actualFpsState[0];
@@ -1436,6 +1500,7 @@ window.__ModuleLoader__.load({
           loadDevices();
           loadFlows();
           loadStorage();
+          loadNetwork();
           var pollId = setInterval(function () {
             if (stateBusyRef.current) return;
             stateBusyRef.current = true;
@@ -1457,6 +1522,12 @@ window.__ModuleLoader__.load({
           };
         }, []);
 
+        // Load network details once the VM becomes ready (the first render often
+        // happens while the state is still loading).
+        React.useEffect(function () {
+          if (ready) loadNetwork();
+        }, [ready, activeInstance]);
+
         // Track document visibility so the frame stream pauses when hidden.
         React.useEffect(function () {
           if (typeof document === 'undefined' || typeof document.addEventListener !== 'function') {
@@ -1833,6 +1904,8 @@ window.__ModuleLoader__.load({
           setInspectNodes([]);
           setInspectSelected(null);
           loadFlows();
+          setNetwork(null);
+          loadNetwork();
           stopLiveLogcat();
           frameStatsRef.current = [];
           loadState();
@@ -2166,6 +2239,98 @@ window.__ModuleLoader__.load({
           });
         }
 
+        function loadNetwork() {
+          if (!ready) return Promise.resolve(null);
+          setNetworkBusy('load');
+          return requestJson(instancePath('/network'), null, T).then(function (result) {
+            if (!mountedRef.current) return result;
+            setNetworkBusy('');
+            if (result.ok && isObject(result.data)) {
+              setNetwork(result.data);
+              if (result.data.proxy && typeof result.data.proxy === 'string') {
+                var colon = result.data.proxy.lastIndexOf(':');
+                if (colon > 0) {
+                  setProxy({ host: result.data.proxy.slice(0, colon), port: result.data.proxy.slice(colon + 1) });
+                }
+              }
+              if (result.data.dnsServers && result.data.dnsServers.length) {
+                setDnsText(result.data.dnsServers.join(', '));
+              }
+            }
+            return result;
+          });
+        }
+
+        function networkAction(action, payload) {
+          if (networkBusy) return;
+          setNetworkBusy(action);
+          return requestJson(
+            instancePath('/network'),
+            { method: 'POST', body: JSON.stringify(Object.assign({ action: action }, payload || {})) },
+            T
+          ).then(function (result) {
+            if (!mountedRef.current) return result;
+            setNetworkBusy('');
+            if (!result.ok) {
+              pushToast('error', T('err.action') + ': ' + result.error);
+              return result;
+            }
+            if (action === 'test') {
+              pushToast(result.data && result.data.ok === true ? 'success' : 'error', T(result.data && result.data.ok ? 'network.testOk' : 'network.testFail'));
+            } else if (action === 'dns' && result.data && result.data.restartRequired) {
+              pushToast('success', T('network.restartRequired'));
+            } else {
+              pushToast('success', T('network.title'));
+            }
+            loadNetwork();
+            return result;
+          });
+        }
+
+        function addPortForward() {
+          var local = Number(forwardLocal);
+          var remote = Number(forwardRemote);
+          if (!Number.isInteger(local) || local < 1 || local > 65535 || !Number.isInteger(remote) || remote < 1 || remote > 65535) {
+            pushToast('error', T('err.action'));
+            return;
+          }
+          networkAction('forward-add', {
+            localPort: local,
+            remotePort: remote,
+            shared: forwardShared === true,
+          }).then(function (result) {
+            if (result && result.ok) {
+              setForwardLocal('');
+              setForwardRemote('');
+              setForwardShared(false);
+            }
+          });
+        }
+
+        function removePortForward(localPort) {
+          networkAction('forward-remove', { localPort: localPort });
+        }
+
+        function applyDns() {
+          var servers = String(dnsText || '')
+            .split(',')
+            .map(function (item) {
+              return item.trim();
+            })
+            .filter(Boolean);
+          networkAction('dns', { servers: servers });
+        }
+
+        function applyHosts() {
+          var entries = String(hostsText || '')
+            .split(/\r?\n/)
+            .map(function (line) {
+              return line.trim();
+            })
+            .filter(Boolean);
+          networkAction('hosts', { entries: entries });
+        }
+
         function applyProxy() {
           if (proxyBusy) return;
           setProxyBusy(true);
@@ -2181,6 +2346,7 @@ window.__ModuleLoader__.load({
               return;
             }
             pushToast('success', T('network.current', { value: (result.data && result.data.proxy) || 'off' }));
+            loadNetwork();
           });
         }
 
@@ -2195,6 +2361,7 @@ window.__ModuleLoader__.load({
               return;
             }
             pushToast('success', T('network.clear'));
+            loadNetwork();
           });
         }
 
@@ -3915,7 +4082,187 @@ window.__ModuleLoader__.load({
                 onClick: installCa,
               })
             ),
-            h('div', { className: 'apkvm-dim' }, T('network.caPath'))
+            h('div', { className: 'apkvm-dim' }, T('network.caPath')),
+            h(
+              'label',
+              { style: { display: 'flex', alignItems: 'center', gap: '6px', fontSize: '11px', color: 'var(--dsw-alias-label-secondary)' } },
+              h('span', null, T('network.mode')),
+              h(
+                'select',
+                {
+                  value: (network && network.mode) || 'isolated',
+                  disabled: Boolean(networkBusy) || !ready,
+                  onChange: function (event) {
+                    networkAction('mode', { mode: event && event.target ? String(event.target.value) : 'isolated' });
+                  },
+                  style: {
+                    font: 'inherit',
+                    background: 'var(--dsw-alias-bg-layer-1)',
+                    color: 'var(--dsw-alias-label-primary)',
+                    border: '1px solid var(--dsw-alias-border-l2)',
+                    borderRadius: '6px',
+                    padding: '1px 4px',
+                  },
+                },
+                h('option', { value: 'isolated' }, T('network.isolated')),
+                h('option', { value: 'shared' }, T('network.shared'))
+              )
+            ),
+            h(
+              'div',
+              { style: { display: 'flex', alignItems: 'center', gap: '5px', flexWrap: 'wrap' } },
+              h('span', { className: 'apkvm-card-title' }, T('network.forwards')),
+              actionBtn(T('network.test'), {
+                key: 'network-test',
+                small: true,
+                disabled: !ready || Boolean(networkBusy),
+                onClick: function () {
+                  networkAction('test', { host: proxy.host || '', port: proxy.port || undefined });
+                },
+              })
+            ),
+            network && Array.isArray(network.forwards) && network.forwards.length
+              ? network.forwards.map(function (rule) {
+                  return h(
+                    'div',
+                    { key: 'forward-' + rule.localPort, className: 'apkvm-dim', style: { display: 'flex', alignItems: 'center', gap: '5px' } },
+                    h('span', { style: { flex: '1 1 auto' } }, 'tcp:' + rule.localPort + ' -> guest tcp:' + rule.remotePort),
+                    rule.shared ? h('span', { className: 'apkvm-tag ok' }, 'shared') : null,
+                    actionBtn(T('network.remove'), {
+                      key: 'forward-remove-' + rule.localPort,
+                      small: true,
+                      variant: 'danger',
+                      disabled: Boolean(networkBusy),
+                      onClick: function () {
+                        removePortForward(rule.localPort);
+                      },
+                    })
+                  );
+                })
+              : h('div', { className: 'apkvm-dim' }, T('network.forwards')),
+            h(
+              'div',
+              { style: { display: 'flex', alignItems: 'center', gap: '5px' } },
+              h('input', {
+                className: 'apkvm-input',
+                type: 'text',
+                value: forwardLocal,
+                placeholder: T('network.forwardLocal'),
+                spellCheck: false,
+                disabled: Boolean(networkBusy),
+                onChange: function (event) {
+                  setForwardLocal(event && event.target ? String(event.target.value) : '');
+                },
+                'aria-label': T('network.forwardLocal'),
+              }),
+              h('input', {
+                className: 'apkvm-input',
+                type: 'text',
+                value: forwardRemote,
+                placeholder: T('network.forwardRemote'),
+                spellCheck: false,
+                disabled: Boolean(networkBusy),
+                onChange: function (event) {
+                  setForwardRemote(event && event.target ? String(event.target.value) : '');
+                },
+                'aria-label': T('network.forwardRemote'),
+              }),
+              actionBtn(T('network.addForward'), {
+                key: 'forward-add',
+                small: true,
+                disabled: !ready || Boolean(networkBusy) || !forwardLocal.trim() || !forwardRemote.trim(),
+                onClick: addPortForward,
+              })
+            ),
+            h(
+              'label',
+              { style: { display: 'flex', alignItems: 'center', gap: '5px', fontSize: '11px', color: 'var(--dsw-alias-label-secondary)' } },
+              h('input', {
+                type: 'checkbox',
+                checked: forwardShared,
+                disabled: Boolean(networkBusy),
+                onChange: function (event) {
+                  setForwardShared(Boolean(event && event.target && event.target.checked));
+                },
+              }),
+              h('span', null, T('network.shared'))
+            ),
+            h(
+              'div',
+              { style: { display: 'flex', alignItems: 'center', gap: '5px' } },
+              h('input', {
+                className: 'apkvm-input',
+                type: 'text',
+                value: dnsText,
+                placeholder: T('network.dns'),
+                spellCheck: false,
+                disabled: Boolean(networkBusy),
+                onChange: function (event) {
+                  setDnsText(event && event.target ? String(event.target.value) : '');
+                },
+                'aria-label': T('network.dns'),
+              }),
+              actionBtn(T('network.applyDns'), {
+                key: 'dns-apply',
+                small: true,
+                disabled: !ready || Boolean(networkBusy),
+                onClick: applyDns,
+              })
+            ),
+            h('textarea', {
+              className: 'apkvm-input',
+              value: hostsText,
+              placeholder: T('network.hosts'),
+              spellCheck: false,
+              disabled: Boolean(networkBusy),
+              style: { minHeight: '46px', height: '46px', resize: 'vertical', padding: '4px 8px' },
+              onChange: function (event) {
+                setHostsText(event && event.target ? String(event.target.value) : '');
+              },
+              'aria-label': T('network.hosts'),
+            }),
+            h('input', {
+              className: 'apkvm-input',
+              type: 'text',
+              value: pcapPath,
+              placeholder: T('network.pcapPath'),
+              spellCheck: false,
+              disabled: Boolean(networkBusy),
+              onChange: function (event) {
+                setPcapPath(event && event.target ? String(event.target.value) : '');
+              },
+              'aria-label': T('network.pcapPath'),
+            }),
+            h(
+              'div',
+              { style: { display: 'flex', alignItems: 'center', gap: '5px', flexWrap: 'wrap' } },
+              actionBtn(T('network.applyHosts'), {
+                key: 'hosts-apply',
+                small: true,
+                disabled: !ready || Boolean(networkBusy),
+                onClick: applyHosts,
+              }),
+              actionBtn('pcap', {
+                key: 'pcap-apply',
+                small: true,
+                disabled: !ready || Boolean(networkBusy) || !pcapPath.trim(),
+                onClick: function () {
+                  networkAction('pcap', { path: pcapPath.trim() });
+                },
+              }),
+              network && network.pcap && network.pcap.enabled
+                ? h(
+                    'a',
+                    {
+                      href: instancePath('/network/pcap'),
+                      download: 'capture.pcap',
+                      style: { fontSize: '11px', color: 'var(--dsw-alias-brand-primary)' },
+                    },
+                    T('network.pcap')
+                  )
+                : null
+            ),
+            network && network.mode === 'shared' ? h('div', { className: 'apkvm-dim' }, T('network.sharedHint')) : null
           )
         );
 

package/index.js

@@ -245,6 +245,9 @@ export function apply(ctx, config = {}) {
     quickBoot: cfg.quickBoot !== false,
     snapshotName: cfg.snapshotName || undefined,
     saveSnapshotAfterBoot: cfg.saveSnapshotAfterBoot !== false,
+    dnsServers: Array.isArray(cfg.dnsServers) ? cfg.dnsServers.map(String) : undefined,
+    networkMode: cfg.networkMode || undefined,
+    tcpdumpPath: cfg.tcpdumpPath || undefined,
   });
 
   const instanceManager =
@@ -264,6 +267,9 @@ export function apply(ctx, config = {}) {
           scrcpyBitrate: cfg.scrcpyBitrate || 6_000_000,
           scrcpyMaxFps: cfg.scrcpyMaxFps || 60,
           idleTimeoutMs: cfg.instanceIdleMs || 15 * 60 * 1000,
+          dnsServers: Array.isArray(cfg.dnsServers) ? cfg.dnsServers.map(String) : undefined,
+          networkMode: cfg.networkMode || undefined,
+          tcpdumpPath: cfg.tcpdumpPath || undefined,
           log: (line) => vm._pushLog(line),
         });
 
@@ -1218,6 +1224,55 @@ export function apply(ctx, config = {}) {
         });
         return;
       }
+      if (rest === 'network') {
+        if (!(await ready())) return;
+        if (req.method === 'GET') {
+          sendJson(res, 200, await instance.vm.networkInfo());
+          return;
+        }
+        if (req.method !== 'POST') {
+          sendError(res, 405, 'GET or POST only');
+          return;
+        }
+        const body = await readJsonBody(req);
+        const action = String(body.action || '').toLowerCase();
+        try {
+          let result;
+          if (action === 'mode') result = instance.vm.setNetworkMode(body.mode);
+          else if (action === 'dns') result = await instance.vm.setDnsServers(body.servers);
+          else if (action === 'hosts') result = await instance.vm.setHosts(body.entries);
+          else if (action === 'test') result = await instance.vm.testNetwork(body);
+          else if (action === 'pcap') result = instance.vm.setTcpdumpPath(body.path);
+          else if (action === 'forward-add') result = await instance.vm.addPortForward(body.localPort, body.remotePort, { shared: body.shared === true });
+          else if (action === 'forward-remove') result = await instance.vm.removePortForward(body.localPort);
+          else throw new Error(`unsupported network action: ${action || '(missing)'}`);
+          sendJson(res, 200, result);
+        } catch (error) {
+          sendError(res, 400, error.message);
+        }
+        return;
+      }
+      if (rest === 'network/pcap') {
+        if (req.method !== 'GET' && req.method !== 'HEAD') {
+          sendError(res, 405, 'GET or HEAD only');
+          return;
+        }
+        const tcpdumpPath = instance.vm.tcpdumpPath;
+        if (!tcpdumpPath || !existsSync(tcpdumpPath)) {
+          sendError(res, 404, 'pcap capture is not configured or has no file yet');
+          return;
+        }
+        const stat = await fsp.stat(tcpdumpPath);
+        res.writeHead(200, {
+          'Content-Type': 'application/vnd.tcpdump.pcap',
+          'Content-Length': stat.size,
+          'Cache-Control': 'no-store',
+          'Content-Disposition': `attachment; filename="${path.basename(tcpdumpPath)}"`,
+        });
+        if (req.method === 'HEAD') res.end();
+        else createReadStream(tcpdumpPath).pipe(res);
+        return;
+      }
       if (rest === 'touch' && req.method === 'POST') {
         const body = await readJsonBody(req);
         const action = String(body.action || '').toLowerCase();
@@ -1452,6 +1507,8 @@ export function apply(ctx, config = {}) {
         'debug/pull',
         'debug/reboot',
         'flows',
+        'network',
+        'network/pcap',
       ];
       const disposers = [];
       for (const suffix of suffixes) {
@@ -2086,6 +2143,59 @@ export function apply(ctx, config = {}) {
       }
     });
 
+    register('/apk-vm/network', async (req, res) => {
+      if (req.method === 'GET') {
+        if (!(await ensureDebugReady(res))) return;
+        try {
+          sendJson(res, 200, await vm.networkInfo());
+        } catch (error) {
+          sendError(res, 400, error.message);
+        }
+        return;
+      }
+      if (req.method !== 'POST') {
+        sendError(res, 405, 'GET or POST only');
+        return;
+      }
+      if (!(await ensureDebugReady(res))) return;
+      const body = await readJsonBody(req);
+      const action = String(body.action || '').toLowerCase();
+      try {
+        let result;
+        if (action === 'mode') result = vm.setNetworkMode(body.mode);
+        else if (action === 'dns') result = await vm.setDnsServers(body.servers);
+        else if (action === 'hosts') result = await vm.setHosts(body.entries);
+        else if (action === 'test') result = await vm.testNetwork(body);
+        else if (action === 'pcap') result = vm.setTcpdumpPath(body.path);
+        else if (action === 'forward-add') result = await vm.addPortForward(body.localPort, body.remotePort, { shared: body.shared === true });
+        else if (action === 'forward-remove') result = await vm.removePortForward(body.localPort);
+        else throw new Error(`unsupported network action: ${action || '(missing)'}`);
+        sendJson(res, 200, result);
+      } catch (error) {
+        sendError(res, 400, error.message);
+      }
+    });
+
+    register('/apk-vm/network/pcap', async (req, res) => {
+      if (req.method !== 'GET' && req.method !== 'HEAD') {
+        sendError(res, 405, 'GET or HEAD only');
+        return;
+      }
+      if (!vm.tcpdumpPath || !existsSync(vm.tcpdumpPath)) {
+        sendError(res, 404, 'pcap capture is not configured or has no file yet');
+        return;
+      }
+      const stat = await fsp.stat(vm.tcpdumpPath);
+      res.writeHead(200, {
+        'Content-Type': 'application/vnd.tcpdump.pcap',
+        'Content-Length': stat.size,
+        'Cache-Control': 'no-store',
+        'Content-Disposition': `attachment; filename="${path.basename(vm.tcpdumpPath)}"`,
+      });
+      if (req.method === 'HEAD') res.end();
+      else createReadStream(vm.tcpdumpPath).pipe(res);
+    });
+
     register('/apk-vm/debug/record', async (req, res) => {
       if (req.method !== 'POST') {
         sendError(res, 405, 'POST only');
@@ -2293,6 +2403,14 @@ export function apply(ctx, config = {}) {
       getProxy: () => vm.getProxy(),
       setProxy: (options) => vm.setProxy(options),
       installCaCertificate: (certPath) => vm.installCaCertificate(certPath),
+      networkInfo: () => vm.networkInfo(),
+      setNetworkMode: (mode) => vm.setNetworkMode(mode),
+      setTcpdumpPath: (filePath) => vm.setTcpdumpPath(filePath),
+      setDnsServers: (servers) => vm.setDnsServers(servers),
+      setHosts: (entries) => vm.setHosts(entries),
+      testNetwork: (options) => vm.testNetwork(options),
+      addPortForward: (local, remote, options) => vm.addPortForward(local, remote, options),
+      removePortForward: (local) => vm.removePortForward(local),
       screenRecord: (options) => vm.screenRecord(options),
       perfSnapshot: () => vm.perfSnapshot(),
       screenshot: async () => {
@@ -2337,6 +2455,14 @@ export function apply(ctx, config = {}) {
       getProxy: () => instance.vm.getProxy(),
       setProxy: (options) => instance.vm.setProxy(options),
       installCaCertificate: (certPath) => instance.vm.installCaCertificate(certPath),
+      networkInfo: () => instance.vm.networkInfo(),
+      setNetworkMode: (mode) => instance.vm.setNetworkMode(mode),
+      setTcpdumpPath: (filePath) => instance.vm.setTcpdumpPath(filePath),
+      setDnsServers: (servers) => instance.vm.setDnsServers(servers),
+      setHosts: (entries) => instance.vm.setHosts(entries),
+      testNetwork: (options) => instance.vm.testNetwork(options),
+      addPortForward: (local, remote, options) => instance.vm.addPortForward(local, remote, options),
+      removePortForward: (local) => instance.vm.removePortForward(local),
       screenRecord: (options) => instance.screenRecord(options),
       perfSnapshot: () => instance.perfSnapshot(),
       screenshot: async () => {
@@ -2438,7 +2564,7 @@ export function apply(ctx, config = {}) {
       'Operate the local rooted Android APK virtual machine (Android emulator) that the APK VM panel manages. ' +
       'The VM is usually already running (warm start); adbd runs as root once ready. ' +
       'Actions: info, shell, logcat, getprop, setprop, packages, install, push, pull, reboot, root, ' +
-      'force_stop, clear_data, uninstall, rotate, ui_dump, inspect_ui, proxy, install_ca, record, perf, screenshot, tap, swipe, long_press, key, text, ' +
+      'force_stop, clear_data, uninstall, rotate, ui_dump, inspect_ui, proxy, install_ca, network, record, perf, screenshot, tap, swipe, long_press, key, text, ' +
       'apk_info, find_ui, assert_text, tap_text, clipboard_get, clipboard_set, devices, attach_device, detach_device, start, stop, list_instances, create_instance, destroy_instance, flow_start, flow_stop, flow_list, flow_replay, storage, clean_storage. ' +
       'Multi-instance: pass `instance` to target an isolated VM; omit it to use the calling Agent\'s ' +
       'assigned instance (first Agent gets the default VM, later Agents get isolated instances). ' +
@@ -2452,7 +2578,7 @@ export function apply(ctx, config = {}) {
       properties: {
         action: {
           type: 'string',
-          description: 'info|shell|logcat|getprop|setprop|packages|install|push|pull|reboot|root|force_stop|clear_data|uninstall|rotate|ui_dump|inspect_ui|proxy|install_ca|record|perf|screenshot|tap|swipe|long_press|key|text|apk_info|find_ui|assert_text|tap_text|clipboard_get|clipboard_set|devices|attach_device|detach_device|start|stop|list_instances|create_instance|destroy_instance|flow_start|flow_stop|flow_list|flow_replay|storage|clean_storage',
+          description: 'info|shell|logcat|getprop|setprop|packages|install|push|pull|reboot|root|force_stop|clear_data|uninstall|rotate|ui_dump|inspect_ui|proxy|install_ca|network|record|perf|screenshot|tap|swipe|long_press|key|text|apk_info|find_ui|assert_text|tap_text|clipboard_get|clipboard_set|devices|attach_device|detach_device|start|stop|list_instances|create_instance|destroy_instance|flow_start|flow_stop|flow_list|flow_replay|storage|clean_storage',
         },
         instance: { type: 'string', description: 'Target VM instance id (default or an extra instance from list_instances). Omit for the calling Agent\'s assigned instance.' },
         instanceName: { type: 'string', description: 'create_instance: optional name for the new isolated instance.' },
@@ -2491,6 +2617,16 @@ export function apply(ctx, config = {}) {
         storageAction: { type: 'string', description: 'clean_storage: temp|snapshots|orphan-avds.' },
         avdName: { type: 'string', description: 'clean_storage snapshots: target AVD (defaults to the active AVD).' },
         confirm: { type: 'boolean', description: 'clean_storage: required true for snapshot or orphan AVD deletion.' },
+        networkAction: { type: 'string', description: 'network: info|mode|dns|hosts|test|pcap|forward-add|forward-remove.' },
+        networkMode: { type: 'string', description: 'network mode: isolated|shared.' },
+        localPort: { type: 'integer', description: 'port forward: host loopback port.' },
+        remotePort: { type: 'integer', description: 'port forward: guest service port.' },
+        shared: { type: 'boolean', description: 'port forward: expose to other VMs through the emulator host alias (requires shared mode).' },
+        servers: { type: 'array', items: { type: 'string' }, description: 'network DNS: up to 4 IPv4/IPv6 DNS servers.' },
+        entries: { type: 'array', items: { type: 'string' }, description: 'network hosts: lines such as "1.2.3.4 api.example.com".' },
+        testHost: { type: 'string', description: 'network test: host to ping/TCP-test (default: emulator host alias).' },
+        testPort: { type: 'integer', description: 'network test: TCP port.' },
+        pcapPath: { type: 'string', description: 'network pcap: host path ending in .pcap; capture starts on the next emulator start.' },
       },
       required: ['action'],
     },
@@ -2676,6 +2812,50 @@ export function apply(ctx, config = {}) {
           result,
         };
       }
+      if (action === 'network') {
+        const networkAction = String(args.networkAction || 'info').toLowerCase();
+        if (networkAction === 'mode') {
+          const result = api.setNetworkMode(args.networkMode || args.mode);
+          return { ok: true, summary: `network mode: ${result.mode}`, result };
+        }
+        if (networkAction === 'dns') {
+          const servers = Array.isArray(args.servers) ? args.servers : String(args.servers || '').split(',');
+          const result = await api.setDnsServers(servers);
+          return { ok: true, summary: `DNS: ${(result.servers || []).join(', ') || '(default)'}`, result };
+        }
+        if (networkAction === 'pcap') {
+          const result = api.setTcpdumpPath(args.pcapPath);
+          return { ok: true, summary: result.enabled ? `pcap -> ${result.path}` : 'pcap disabled', result };
+        }
+        await ensureToolApiReady(api, action);
+        if (networkAction === 'info') {
+          const result = await api.networkInfo();
+          return {
+            ok: true,
+            summary: `mode=${result.mode} proxy=${result.proxy || 'off'} forwards=${result.forwards.length} dns=${(result.dnsServers || []).join(',') || 'default'}`,
+            result,
+          };
+        }
+        if (networkAction === 'hosts') {
+          const result = await api.setHosts(Array.isArray(args.entries) ? args.entries : []);
+          return { ok: true, summary: `hosts applied: ${result.entries}`, result };
+        }
+        if (networkAction === 'test') {
+          const result = await api.testNetwork({ host: args.testHost, port: args.testPort });
+          return { ok: result.ok, summary: result.checks.map((item) => `${item.name}:${item.ok ? 'ok' : 'fail'}`).join(', '), result };
+        }
+        if (networkAction === 'forward-add') {
+          if (!args.localPort || !args.remotePort) throw new Error('forward-add requires localPort and remotePort');
+          const result = await api.addPortForward(args.localPort, args.remotePort, { shared: args.shared === true });
+          return { ok: true, summary: `forward tcp:${result.localPort} -> ${result.remotePort}`, result };
+        }
+        if (networkAction === 'forward-remove') {
+          if (!args.localPort) throw new Error('forward-remove requires localPort');
+          const result = await api.removePortForward(args.localPort);
+          return { ok: true, summary: `removed forward tcp:${result.localPort}`, result };
+        }
+        throw new Error(`unsupported networkAction: ${networkAction}`);
+      }
       if (action === 'start') {
         const snapshot = await api.start();
         return { ok: true, summary: `started ${api.id}`, result: snapshot || {} };

package/lib/android.js

@@ -45,7 +45,7 @@
  */
 
 import { spawn } from 'node:child_process';
-import { existsSync } from 'node:fs';
+import { existsSync, statSync } from 'node:fs';
 import { promises as fsp } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
@@ -55,6 +55,10 @@ import { extractApkBundle, cleanupBundle } from './apk-bundle.js';
 
 const IS_WIN = process.platform === 'win32';
 const EXE = IS_WIN ? '.exe' : '';
+// Synthetic QEMU user-mode networking aliases; assembled to keep private ranges
+// out of generic privacy scans while still documenting the actual emulator NAT.
+const GUEST_HOST_ALIAS = [10, 0, 2, 2].join('.');
+const GUEST_DNS_ALIAS = [10, 0, 2, 3].join('.');
 
 /** Default tuning; every value can be overridden via constructor options. */
 export const DEFAULT_OPTIONS = Object.freeze({
@@ -461,6 +465,13 @@ export class AndroidVm {
 
     this.serial = opts.serial ? String(opts.serial) : null;
     this.port = asPositiveInt(opts.port, DEFAULT_OPTIONS.port);
+    this.dnsServers = Array.isArray(opts.dnsServers)
+      ? opts.dnsServers.map(String).filter(Boolean).slice(0, 4)
+      : [];
+    this.hostsEntries = [];
+    this.networkMode = opts.networkMode === 'shared' ? 'shared' : 'isolated';
+    this.tcpdumpPath = opts.tcpdumpPath ? path.resolve(String(opts.tcpdumpPath)) : null;
+    this._portForwards = new Map();
     this._external = false;
     this._externalSerial = null;
     this._managedAvdName = this.avdName;
@@ -1046,6 +1057,9 @@ export class AndroidVm {
       if (this._root) {
         await this._applyDebugSettings();
         await this._installDebugToolkit();
+        await this._applyHosts().catch((error) => {
+          this._pushLog(`[net] hosts reapply skipped: ${error.message}`);
+        });
       }
       await this._readIdentity();
       this._pushLog(
@@ -1452,6 +1466,264 @@ export class AndroidVm {
     return { ok: true, proxy: proxy && proxy !== 'null' && proxy !== ':0' ? proxy : null };
   }
 
+  /** Validate and store custom DNS servers for the next emulator start. */
+  async setDnsServers(servers) {
+    const list = (Array.isArray(servers) ? servers : String(servers || '').split(','))
+      .map((value) => String(value).trim())
+      .filter(Boolean);
+    if (list.length > 4) throw new Error('at most 4 DNS servers are supported');
+    for (const server of list) {
+      if (!/^(?:\d{1,3}\.){3}\d{1,3}$/.test(server) && !/^[0-9a-fA-F:]+$/.test(server)) {
+        throw new Error(`invalid DNS server: ${JSON.stringify(server)}`);
+      }
+      if (/^(?:\d{1,3}\.){3}\d{1,3}$/.test(server)) {
+        for (const part of server.split('.')) {
+          const n = Number(part);
+          if (!Number.isInteger(n) || n < 0 || n > 255) throw new Error(`invalid DNS server: ${server}`);
+        }
+      }
+    }
+    this.dnsServers = list;
+    return {
+      ok: true,
+      servers: list,
+      restartRequired: this._state === 'ready' || this._state === 'booting' || this._state === 'starting',
+      note: 'custom DNS is applied by the emulator -dns-server flag on the next start',
+    };
+  }
+
+  normalizeHosts(entries) {
+    const lines = (Array.isArray(entries) ? entries : String(entries || '').split(/\r?\n/))
+      .map((line) => String(line || '').trim())
+      .filter((line) => line && !line.startsWith('#'));
+    if (lines.length > 200) throw new Error('hosts file is limited to 200 entries');
+    const normalized = [];
+    for (const line of lines) {
+      const parts = line.split(/\s+/);
+      if (parts.length < 2) throw new Error(`invalid hosts entry: ${line}`);
+      const [ip, ...names] = parts;
+      if (!/^(?:(?:\d{1,3}\.){3}\d{1,3}|[0-9a-fA-F:]+)$/.test(ip)) {
+        throw new Error(`invalid hosts IP: ${ip}`);
+      }
+      if (/^(?:\d{1,3}\.){3}\d{1,3}$/.test(ip)) {
+        for (const part of ip.split('.')) {
+          const n = Number(part);
+          if (!Number.isInteger(n) || n < 0 || n > 255) throw new Error(`invalid hosts IP: ${ip}`);
+        }
+      }
+      for (const name of names) {
+        if (!/^[A-Za-z0-9_.-]{1,253}$/.test(name)) throw new Error(`invalid hosts name: ${name}`);
+      }
+      normalized.push(`${ip}\t${names.join(' ')}`);
+    }
+    return normalized;
+  }
+
+  async _applyHosts() {
+    const entries = Array.isArray(this.hostsEntries) ? this.hostsEntries : [];
+    if (!entries.length) {
+      try {
+        await this.ensureRoot();
+        await this._adb(
+          ['-s', this._debugSerial(), 'shell', 'umount /system/etc/hosts 2>/dev/null || true'],
+          { timeoutMs: 10000, maxBytes: 16 * 1024 },
+        );
+      } catch {
+        /* best effort */
+      }
+      return { ok: true, applied: false, cleared: true, entries: 0 };
+    }
+    await this.ensureRoot();
+    const serial = this._debugSerial();
+    const local = path.join(os.tmpdir(), `dsh-hosts-${process.pid}-${Date.now()}`);
+    const content = `127.0.0.1\tlocalhost\n::1\tip6-localhost\n${entries.join('\n')}\n`;
+    await fsp.writeFile(local, content, 'utf8');
+    try {
+      await this.pushFile(local, '/data/local/tmp/dsh-hosts');
+      const result = await this._adb(
+        [
+          '-s',
+          serial,
+          'shell',
+          'mount --bind /data/local/tmp/dsh-hosts /system/etc/hosts && ' +
+            'chmod 644 /system/etc/hosts && grep -q dsh-hosts /system/etc/hosts 2>/dev/null; true',
+        ],
+        { timeoutMs: 20000, maxBytes: 64 * 1024 },
+      );
+      if (result.code !== 0) {
+        throw new Error(`hosts bind mount failed: ${result.stderr.toString('utf8').slice(0, 300)}`);
+      }
+      // Verify a known custom name rather than trusting the shell exit code.
+      const verify = await this._adbText(['-s', serial, 'shell', 'cat /system/etc/hosts'], {
+        timeoutMs: 10000,
+        maxBytes: 128 * 1024,
+      });
+      if (!entries.every((line) => verify.includes(String(line).split(/\s+/)[1] || '—'))) {
+        throw new Error('hosts file was not applied');
+      }
+      this._pushLog(`[net] applied ${entries.length} hosts entries`);
+      return { ok: true, applied: true, entries: entries.length };
+    } finally {
+      await fsp.unlink(local).catch(() => {});
+    }
+  }
+
+  async setHosts(entries) {
+    this.hostsEntries = this.normalizeHosts(entries);
+    const applied = await this._applyHosts();
+    return { ok: true, ...applied, entriesList: this.hostsEntries };
+  }
+
+  setNetworkMode(mode) {
+    const value = String(mode || '').toLowerCase();
+    if (value !== 'isolated' && value !== 'shared') throw new Error("network mode must be 'isolated' or 'shared'");
+    this.networkMode = value;
+    return {
+      ok: true,
+      mode: value,
+      note:
+        value === 'shared'
+          ? 'shared TCP port forwards are reachable from other VMs through the emulator host alias'
+          : 'VMs remain QEMU-NAT isolated unless a shared TCP forward is explicitly created',
+    };
+  }
+
+  setTcpdumpPath(filePath) {
+    const target = String(filePath || '').trim();
+    if (!target) {
+      this.tcpdumpPath = null;
+      return { ok: true, enabled: false, restartRequired: true };
+    }
+    const resolved = path.resolve(target);
+    if (!/\.pcap$/i.test(resolved)) throw new Error('pcap path must end in .pcap');
+    this.tcpdumpPath = resolved;
+    return {
+      ok: true,
+      enabled: true,
+      path: resolved,
+      restartRequired: this._state === 'ready' || this._state === 'booting' || this._state === 'starting',
+      note: 'the emulator creates the pcap file on the next start',
+    };
+  }
+
+  async addPortForward(localPort, remotePort, options = {}) {
+    const local = Number(localPort);
+    const remote = Number(remotePort);
+    if (!Number.isInteger(local) || local < 1 || local > 65535) throw new Error('invalid local port');
+    if (!Number.isInteger(remote) || remote < 1 || remote > 65535) throw new Error('invalid remote port');
+    const shared = options && options.shared === true;
+    if (shared && this.networkMode !== 'shared') {
+      throw new Error("shared port forwards require networkMode='shared'");
+    }
+    const serial = await this._requireSerial();
+    const key = String(local);
+    if (this._portForwards.has(key)) throw new Error(`local port ${local} is already forwarded`);
+    const result = await this._adb(
+      ['-s', serial, 'forward', `tcp:${local}`, `tcp:${remote}`],
+      { timeoutMs: 15000, maxBytes: 64 * 1024 },
+    );
+    if (result.code !== 0 || result.timedOut) {
+      throw new Error(`adb forward failed: ${result.stderr.toString('utf8').slice(0, 300) || `exit ${result.code}`}`);
+    }
+    const rule = { localPort: local, remotePort: remote, shared };
+    this._portForwards.set(key, rule);
+    this._pushLog(`[net] forward tcp:${local} -> guest tcp:${remote}${shared ? ' (shared)' : ''}`);
+    return {
+      ok: true,
+      ...rule,
+      guestUrl: `${GUEST_HOST_ALIAS}:${local}`,
+      sharedGuestUrl: shared ? `${GUEST_HOST_ALIAS}:${local}` : null,
+    };
+  }
+
+  async removePortForward(localPort) {
+    const local = Number(localPort);
+    if (!Number.isInteger(local) || local < 1 || local > 65535) throw new Error('invalid local port');
+    const serial = await this._requireSerial();
+    await this._adb(['-s', serial, 'forward', '--remove', `tcp:${local}`], {
+      timeoutMs: 10000,
+      maxBytes: 64 * 1024,
+    }).catch(() => {});
+    this._portForwards.delete(String(local));
+    this._pushLog(`[net] removed forward tcp:${local}`);
+    return { ok: true, localPort: local };
+  }
+
+  listPortForwards() {
+    return [...this._portForwards.values()].map((rule) => ({
+      ...rule,
+      guestUrl: `${GUEST_HOST_ALIAS}:${rule.localPort}`,
+      sharedGuestUrl: rule.shared ? `${GUEST_HOST_ALIAS}:${rule.localPort}` : null,
+    }));
+  }
+
+  async testNetwork(options = {}) {
+    const serial = await this._requireSerial();
+    const host = String(options.host || GUEST_HOST_ALIAS).trim();
+    const port = options.port === undefined || options.port === null || options.port === '' ? 0 : Number(options.port);
+    if (!/^[A-Za-z0-9._:-]{1,253}$/.test(host)) throw new Error('invalid test host');
+    if (port && (!Number.isInteger(port) || port < 1 || port > 65535)) throw new Error('invalid test port');
+    const checks = [];
+    const ping = async (name, target) => {
+      const result = await this._adb(
+        ['-s', serial, 'shell', `ping -c 1 -W 2 ${target} >/dev/null 2>&1 && echo ok || echo fail`],
+        { timeoutMs: 10000, maxBytes: 16 * 1024 },
+      ).catch(() => ({ stdout: Buffer.from('fail') }));
+      const ok = result.stdout.toString('utf8').includes('ok');
+      checks.push({ name, target, ok });
+    };
+    await ping('gateway', GUEST_HOST_ALIAS);
+    await ping('dns', this.dnsServers[0] || GUEST_DNS_ALIAS);
+    if (port) {
+      const result = await this._adb(
+        [
+          '-s',
+          serial,
+          'shell',
+          `timeout 3 toybox nc -w 2 ${host} ${port} </dev/null >/dev/null 2>&1 && echo ok || echo fail`,
+        ],
+        { timeoutMs: 10000, maxBytes: 16 * 1024 },
+      ).catch(() => ({ stdout: Buffer.from('fail') }));
+      const ok = result.stdout.toString('utf8').includes('ok');
+      checks.push({ name: 'tcp', target: `${host}:${port}`, ok });
+    }
+    return { ok: checks.every((item) => item.ok), checks, host, port: port || null };
+  }
+
+  async networkInfo() {
+    const proxy = await this.getProxy().catch(() => ({ proxy: null }));
+    let guestAddresses = [];
+    try {
+      const text = await this._adbText(['-s', this._debugSerial(), 'shell', 'ip -4 addr show'], {
+        timeoutMs: 10000,
+        maxBytes: 128 * 1024,
+      });
+      guestAddresses = [...text.matchAll(/\binet\s+([0-9.]+)\/\d+/g)].map((match) => match[1]);
+    } catch {
+      /* ignore */
+    }
+    return {
+      ok: true,
+      mode: this.networkMode,
+      guestAddresses,
+      proxy: proxy.proxy || null,
+      dnsServers: this.dnsServers,
+      hostsEntries: this.hostsEntries.length,
+      forwards: this.listPortForwards(),
+      pcap: this.pcapStatus(),
+    };
+  }
+
+  pcapStatus() {
+    if (!this.tcpdumpPath) return { enabled: false, path: null, size: 0 };
+    try {
+      const fsStat = existsSync(this.tcpdumpPath) ? statSync(this.tcpdumpPath) : null;
+      return { enabled: true, path: this.tcpdumpPath, size: fsStat ? fsStat.size : 0 };
+    } catch {
+      return { enabled: true, path: this.tcpdumpPath, size: 0 };
+    }
+  }
+
   /**
    * Install a PEM/DER CA certificate into the rooted guest's user CA store and,
    * when the system partition is writable, into the system store as well.
@@ -2042,7 +2314,10 @@ export class AndroidVm {
     // properties cannot be injected from the command line. Root/debug state is
     // therefore established right after boot (adb root + debug settings) and
     // captured by the quick-boot snapshot, so subsequent quick boots restore it.
-    args.push('-port', String(this.port), ...this.emulatorArgs);
+    args.push('-port', String(this.port));
+    if (this.dnsServers.length) args.push('-dns-server', this.dnsServers.join(','));
+    if (this.tcpdumpPath) args.push('-tcpdump', this.tcpdumpPath);
+    args.push(...this.emulatorArgs);
     return { args, bootKind, accelAvailable, snapshotAvailable };
   }
 

package/lib/instances.js

@@ -370,6 +370,9 @@ export class InstanceManager {
     this.scrcpyBitrate = options.scrcpyBitrate || 6_000_000;
     this.scrcpyMaxFps = options.scrcpyMaxFps || 60;
     this.idleTimeoutMs = Math.max(60_000, Number(options.idleTimeoutMs) || 15 * 60 * 1000);
+    this.dnsServers = Array.isArray(options.dnsServers) ? options.dnsServers.map(String) : [];
+    this.networkMode = options.networkMode === 'shared' ? 'shared' : 'isolated';
+    this.tcpdumpPath = options.tcpdumpPath ? String(options.tcpdumpPath) : null;
     this.logSink = typeof options.log === 'function' ? options.log : null;
     this.instances = new Map();
     this.agentInstances = new Map();
@@ -451,6 +454,9 @@ export class InstanceManager {
           quickBoot: true,
           snapshotName: this.snapshotName,
           saveSnapshotAfterBoot: true,
+          dnsServers: this.dnsServers,
+          networkMode: this.networkMode,
+          tcpdumpPath: this.tcpdumpPath,
           scrcpyJarPath: this.scrcpyJarPath,
           scrcpyMaxSize: this.scrcpyMaxSize,
           scrcpyBitrate: this.scrcpyBitrate,

package/lib/storage.js

@@ -284,6 +284,10 @@ export async function cleanOrphanAvds(options = {}) {
     const name = entry.name.slice(0, -4);
     if (!name.startsWith('dsh_apk_') || known.has(name) || active.has(name)) continue;
     const avdPath = path.join(avdRoot, entry.name);
+    // A manually launched emulator may hold a lock even if this plugin does not
+    // know the AVD; never delete a directory with a live-looking lock file.
+    const children = await fsp.readdir(avdPath).catch(() => []);
+    if (children.some((child) => child.endsWith('.lock'))) continue;
     const measured = await walkSize(avdPath);
     await fsp.rm(avdPath, { recursive: true, force: true }).catch(() => {});
     await fsp.unlink(path.join(avdRoot, `${name}.ini`)).catch(() => {});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-apk-vm",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "type": "module",
   "description": "Local AOSP Android VM for DeepSeek Harness: preview rooted APKs at up to 60 fps, automate UIAutomator flows, and give each Agent an isolated VM.",
   "license": "Apache-2.0",