Introduction¶

Agents running on the cloud cannot list directories, read git logs, or run a build command on your own machine without a local environment. The traditional approach is to write a persistent service yourself, then figure out how to handle authentication, timeouts, output truncation, and reconnection logic; the engineering effort is significant. Using ssh directly also requires maintaining keys and port mappings for each machine one by one.

dsh-pc-bridge compresses all of this into a DSH plugin: it opens a small HTTP bridge on your computer that only listens on the loopback interface. The other party (e.g., a QQ bot on the cloud) can ping this computer and execute shell commands on demand; optionally, it can maintain an ssh reverse tunnel, allowing the remote side to access the computer’s bridge via its own machine’s loopback. The plugin is maintained by QIC-9821, categorized as “Networking Tools,” licensed under MIT, and has no third-party runtime dependencies in the repository.

The facts presented below are from the GitHub README and package.json. Star count is based on the skillhub.cn directory page, currently 0.

What is this plugin¶

In short: it turns “whether this machine can be called by the remote side” into two tool calls (pc_ping / pc_exec) and a curl interface, rather than exposing a computer directly to the public internet.

• Host Bridge: A node:http service providing POST /exec and GET|POST /ping, requiring the x-pc-secret header for each request.
• Tools: The Agent side can call pc_ping (liveness check) and pc_exec (execute command), defaulting to http://127.0.0.1:18790.
• Tunnel Manager: When tunnelEnabled: true, it guards ssh -N -R ...; if disconnected, it retries with a 5/10/30/60 second backoff. If the remote sshd leaves a port occupied, it runs fuser -k before retrying.
• CLI: The repository includes pcctl; pcctl ping and pcctl exec -- "hostname" can call the bridge directly in the terminal without depending on Harness.

Installation and Enablement¶

The README provides three installation methods; choose one.

# npm (recommended)
dsh plugin add dsh-pc-bridge

# Install directly from GitHub tag
dsh plugin add github:QIC-9821/dsh-pc-bridge#v0.1.0

# Local directory (for development)
dsh plugin add /absolute/path/to/dsh-pc-bridge

You can also install the current directory as a bundle in the plugin manager. Requirements: Node.js ≥ 22, no third-party runtime dependencies; the version in package.json is 0.1.1.

After installation, find “PC Execution Bridge” in the Harness settings and configure it using the keys below.

- id: dsh-pc-bridge
  name: 'dsh-pc-bridge'
  config:
    role: both
    listenHost: 127.0.0.1
    listenPort: 18790
    tunnelEnabled: true
    sshHost: 203.0.113.10
    sshUser: dsh
    sshKeyPath: C:/Users/me/.ssh/id_ed25519

The role has three values: host (only open bridge), client (only register tools/tunnel), both (open all); defaults to both.

Configuration Points¶

All default values come from the configuration table in the README. Let’s mention the two you shouldn’t change first: listenHost defaults to 127.0.0.1, and the README explicitly states do not change it to 0.0.0.0.

The key has two sources: DSH_PC_BRIDGE_SECRET environment variable has the highest priority; otherwise, use secretFile; if the file does not exist, the host role automatically generates one. The key is not written into the configuration file; logs only record the source as env: or file:, not the value.

Typical Usage¶

The other party first uses curl to self-test if the bridge is reachable. After the tunnel is established, the bridge for this computer will appear on the other party’s loopback:

curl -s http://127.0.0.1:18790/ping -H "x-pc-secret: $DSH_PC_BRIDGE_SECRET"

The tool signature on the Agent side is:

• pc_ping: Returns {ok, host, user, shell, now} or a network error.
• pc_exec {"command":"...","timeoutSec":30}: Returns {ok, exitCode, stdout, stderr, durationMs, timedOut, truncated}.

If you don’t want to write Harness integration and just want to call it in the terminal, pcctl is equivalent to tools like curl:

PC_BRIDGE_SECRET=... pcctl ping
PC_BRIDGE_SECRET=... pcctl exec -- "hostname; echo OK"

The preparation steps for the other party (using a cloud server as an example) are:

1. Add the computer’s public key to the other party’s user ~/.ssh/authorized_keys.
2. The other party puts the shared key into the process environment, e.g., in systemd: Environment=DSH_PC_BRIDGE_SECRET=replace_with_same_string.
3. The other party executes the above curl self-test; after the tunnel is connected, the bridge for this computer will appear on the other party’s loopback.
4. The other party can also use pcctl directly.

The demo path in the README is this link: the QQ bot on the cloud asks “Is this machine here?” and replies with hostname, user, shell type, and server time; to get things, run commands on the computer, such as listing directories or reading git commit logs.

Suitable Scenarios and Notes¶

Suitable for: having a computer that is online long-term and needs to be called by a cloud Agent to execute local commands, and you are willing to maintain a trust relationship with the other party. The bridge itself only has a loopback interface, and the tunnel also binds both ends to 127.0.0.1, not opening ports to the public internet.

The calling side can choose role as needed: if you only want the Agent to send commands and don’t want to open a port on this machine, configure client.

Points that need to be clear:

• The bridge provides arbitrary command execution capability. The README explicitly requires only giving the key to a trusted other party, and opening the tunnel only when the other party is trusted.
• This plugin runs with the permissions of the current dsh process; what commands can be executed depends on the user who started Harness. Please read the source code and license (MIT) once before installing to confirm there is no unexpected behavior.
• Commands are executed via Git Bash, Node is not in the PATH, and the available commands are based on the local Git Bash; defaultTimeoutMs defaults to 30 seconds, long tasks must explicitly pass timeoutSec.
• Request body limit is 64 KiB, command limit is 8 KiB. Output is truncated according to maxOutputBytes and marked truncated; timeouts will kill the process tree.

Conclusion¶

The value of dsh-pc-bridge does not lie in inventing a new remote execution solution, but in bundling four things—loopback listening, shared key authentication, timeout/truncation constraints, and SSH reverse tunnel backoff reconnection—into a tool that can be called directly by an Agent, saving the work of writing a persistent service yourself.

Directory page: https://www.skillhub.cn/plugins/QIC-9821/dsh-pc-bridge
Repository: https://github.com/QIC-9821/dsh-pc-bridge