Linjiangxian0203/dsh-remote-tunnel
30Last commit Aug 16, 2026
dsh-remote-tunnel DSH plugin
dsh-remote-tunnel is a DSH plugin that manages the full lifecycle of SSH tunnels to a remote dsh web server. It allocates a dedicated remote port, registers it in a server-side registry, supervises the remote dsh process via systemd, and maintains a resilient local tunnel that auto-reconnects after network drops. Designed for single users and teams sharing one server, it provides commands for setup, health checks, status monitoring, and cleanup.
How to install the dsh-remote-tunnel DSH plugin
dsh plugin --profile remote add dsh-remote-tunnelCopying does not run this command. Review the repository and version before installing the dsh-remote-tunnel DSH plugin.
dsh-remote-tunnel DSH plugin data source
dsh-remote-tunnel DSH plugin snapshot date: Aug 16, 2026
discovered
What the dsh-remote-tunnel DSH plugin can do
- Atomic remote port allocation with flock locking and double-check (registry + real bind), safe under concurrency
- Systemd supervision (system or user unit) with auto-restart and reboot survival; no root required for user units
- Resilient SSH tunnel with backoff respawn (infinite by default) and heartbeat to keep the registry fresh
- Local port auto-shift on conflict, showing the occupying process (netstat + tasklist on Windows)
- Registry audit command that compares the TSV registry with real port occupancy
Where the dsh-remote-tunnel DSH plugin fits
- Access the dsh web interface running on a remote Linux server from a local browser via a secure tunnel
- Share a single remote server among multiple users, each getting an isolated port and independent workspace
- Automate the setup of a remote dsh development environment with a single command chain
Who the dsh-remote-tunnel DSH plugin is for
- DSH users who need to work with files and sessions on a remote server
- Team leads or administrators managing a shared dsh server for multiple developers
dsh-remote-tunnel DSH plugin limitations
- Remote server must have Node ≥ 22.19, dsh, systemd, and key-based SSH login
- Only supports Linux as the remote OS (due to systemd dependency); local machine can be Windows/macOS/Linux
- Windows OpenSSH versions before 8.1 have a known issue with ClearAllForwardings that may break tunnel forwarding (requires updated build)
- The plugin is in early development; some features like heartbeat and registry fallback may require manual configuration
dsh-remote-tunnel DSH plugin: from the repository README
Quoted from the Linjiangxian0203/dsh-remote-tunnel README, the upstream source of the dsh-remote-tunnel DSH plugin. Copyright remains with the original authors.
**Remote Host Tunnel Manager**: automates the "local browser → dsh web on a remote Linux server" link — remote port allocation with a registry, systemd supervision, resilient SSH tunneling, local URL output, and full lifecycle management. Built for single users and for teams sharing one server. - Sessions and files live **on the server** (the remote dsh web's workspace = server directories); the local machine only keeps a tunnel - Each user automatically gets a **dedicated remote port**, double-checked on the server (real occupancy + registry) before allocation — safe under concurrency - Every allocation is **recorded in a registry on the server** (`/etc/dsh-ports.tsv`, or a per-user fallback depending on permissions) — `audit` compares the registry against real occupancy at any time - The tunnel **auto-reconnects** after network drops (backoff respawn), and heartbeats keep the registry fresh - Occupied local ports shift automatically, with the occupying process reported ## If you're just a user (not developing) ```powershell # 1. Install (published npm package) dsh plugin --profile remote add dsh-remote-tunnel # 2. Confirm your server is visible (Host aliases from ~/.ssh/confi
Read the full READMERepository license: MIT
dsh-remote-tunnel DSH plugin questions
How do I install dsh-remote-tunnel?
Run `dsh plugin --profile remote add dsh-remote-tunnel` in your terminal. This installs the published npm package into your DSH CLI profile named 'remote'. Make sure you have DSH installed and Node ≥ 22.19 on your local machine.
How do I add a remote host?
Hosts from your `~/.ssh/config` are auto-discovered. If you need to add one manually, use `dsh --profile remote hosts add <alias> --host <IP> --user <username> --workspace <path>`. For example: `dsh --profile remote hosts add lab --host 192.0.2.10 --user alice --workspace /home/alice/project`.
What should I do if the tunnel fails to start?
First run `dsh --profile remote check <host>` to diagnose missing dependencies (keys, Node, dsh, systemd, registry permissions). Common issues: SSH key not set up, remote Node version too old, or systemd not available. The check command gives step-by-step guidance.
How do I handle port conflicts on the local machine?
The plugin automatically shifts the local port when it's occupied. It will show you which process is holding the port. You can also specify a custom local port with `--local-port <port>` when running `up`. The local port range defaults to 3081-3140 and can be configured in `config.yaml`.
Can multiple users share the same remote server?
Yes. Each user runs `up` independently and gets a different remote port. The server-side registry (`/etc/dsh-ports.tsv` or a per-user fallback) tracks allocations. The `audit` command shows who holds which port. For shared registry, the admin must set up the TSV file with appropriate permissions (see the 'Sharing one server' section in the README).