Foreword¶

The philosophy of DSH is “everything is a plugin”, where each plugin performs its own duty when deployed across machines. dsh-memex is responsible for cards, and dsh-cockpit-bridge is responsible for port forwarding; under normal circumstances, these two ends do not reference each other. The problem is: when dsh-memex runs on another machine, the “Open Card” button on its page points the browser to a localhost address, which does not belong to the machine where memex is located, resulting in the button failing to open.

The plugin introduced below is a deployment-side adapter layer created to fill this gap.

What is it¶

dsh-cockpit-memex-browse-shim is maintained by prgrmrwy. It is positioned as a “deployment local adapter for publishing from dsh-cockpit-bridge ports to the dsh-memex browse address registry.” It registers the bridge’s port forwarding into the memex general browse address extension, causing the “Open Card” button to use the forwarding address published by the bridge instead, so that the card browser opens at an address that can actually reach that device.

It is the only deployment-side coupling point: the source code and dependencies of both ends do not reference each other; wiring happens only after installing the shim, and decoupling happens only after removing the shim. The current version is 0.2.0, the source code is maintained under packages/cockpit-memex-browse-shim in the ohmydsh repository, and prgrmrwy/dsh-cockpit-memex-browse-shim on GitHub is the published mirror, released under the MIT license. The community directory classifies it under the “Workflow” category.

Core Functionality & Operation¶

1. Reads the cockpitBridge.forwards port forwarding service. Requires bridge >= 0.6.1 (production pinned to 0.6.4); old portForward / channel register / publish contracts are no longer supported.
2. Registers to the dshMemex.browseAddress registration point. No top-level inject; each service reads via a single ctx.get() using a full dotted name, so the loading order of both ends is irrelevant.
3. Per-port acquisition: calls acquire(devicePort, holder), where the holder carries a random binding identifier to avoid old bindings arriving late and affecting new bindings.
4. Ready wait: waits for starting/retrying/paused via onChange etc., up to 15 seconds; only delivers the current handle.address.url, does not cache the URL, and does not retry on its own. Keeps the holder open after opening to avoid the tunnel being recycled just as the tab opens.
5. Failure semantics are tight: only structured CockpitForwardsError with code === 'local-device' falls back to http://localhost:<port>; errors like unavailable that cannot prove the browser and device are on the same machine are thrown as-is along with network and business failures, allowing users to still use known device addresses directly.
6. Lifecycle: never found bridge’s memex-only deployment keeping default local behavior; after discovering bridge, uninstalling or replacing it cancels the wait and releases the old handle; during the period bridge is missing, retains a fail-closed resolver to prevent the browser from quietly falling back to localhost for remote addresses; unregisters the resolver when the remote end is uninstalled or the shim is disposed.

Applicable Scenarios¶

Suitable for scenarios where both dsh-cockpit-bridge and dsh-memex are installed simultaneously, and one wishes to open cards using a unified forwarding address across machines. When cards are no longer opened across machines via dsh-cockpit, or when either end natively provides this integration, it can be removed: delete the manifest entry -> dsh build -> restart; no migration needed on either end. When rolling back to an old shim, the bridge must also be rolled back to the version providing the old service; do not mix version 0.1.1 shim with bridge 0.6.x.

Installation & Enablement¶

To install it, it needs to be on the same machine as both ends: dsh-cockpit-bridge (GitHub Release tarball) and dsh-memex.

dsh plugin --profile web add https://github.com/prgrmrwy/dsh-cockpit/releases/download/dsh-cockpit-bridge-v0.6.4/dsh-cockpit-bridge-0.6.4.tgz
dsh plugin --profile web add dsh-cockpit-memex-browse-shim

Install the bridge tarball first, then the shim. Then restart DSH web to take effect. Uninstall using:

dsh plugin --profile web remove dsh-cockpit-memex-browse-shim

Verification & Notes¶

The author provides independent package tests/typecheck/build; integration regression uses memex’s real registry (returns localhost by default when not wired), not a fake registry that would mask misrouting, covering ready wait, concurrency, address changes, removal, failure classification, and service lifecycle.

Two reminders: the plugin runs with the current dsh process permissions; before installing, check the source code and license (this plugin is MIT, and depends on @deepseek-ai/cordis ^4.0.4 and Node >= 22.19); it is a thin adapter layer connecting two existing plugins, do not install it alone on a machine without bridge, otherwise the behavior is equivalent to not having it installed.

Links¶

• Directory page: https://www.skillhub.cn/plugins/prgrmrwy/dsh-cockpit-memex-browse-shim
• GitHub: https://github.com/prgrmrwy/dsh-cockpit-memex-browse-shim