A pure-SSH developer-experience wrapper. devssh opens a multiplexed
OpenSSH session to any host and layers on top:
- 🔌 Automatic port forwarding — when applications on the remote start listening, the local side forwards their ports automatically.
- 🌐 Browser opening —
xdg-open/$BROWSERin the remote opens links in your local browser. - 🔔 Desktop notifications — long-running remote commands can ping your local notification center when they finish.
- 🔁 Reverse forwards for local AI services — Ollama (
11434), LM Studio (1234), and Chrome DevTools (9222) on your machine are reverse-forwarded into the remote when they're running. - 🪟
xdg-openshim — an intelligent open-anything wrapper for remote sessions (chafa, glow, bat, tmux split, …).
It's a fork of gh-ado-codespaces with the GitHub
CLI and Azure DevOps auth machinery stripped out. Pure ssh, anywhere.
Local:
- OpenSSH client with multiplexing support (
ControlMaster=auto+-O check). - Linux, macOS, or Windows (with OpenSSH).
Remote (best supported):
- Linux with
bash,jq,ss,curl,base64,chmod(most of these are present by default on Ubuntu / Debian / Fedora images). sshdwithAllowStreamLocalForwarding yesif you want browser and notification socket forwarding (the default on most distros).- Passwordless
sudois only required if you opt in to the system-widexdg-opensymlink (see--install-xdg-open).
Missing remote tools degrade individual features gracefully — the SSH session itself doesn't depend on any of them.
Pre-built binaries are published on the releases page.
Drop the binary somewhere on your PATH.
From source:
go install github.com/scaryrawr/devssh/cmd/devssh@latestdevssh [flags] [host] [-- ssh-flags-or-remote-command...]
- If
[host]is omitted,devsshparses~/.ssh/configand shows a picker of concreteHostaliases (wildcards skipped). - Anything after
--is passed straight to the interactivesshinvocation — useful for ad-hoc-L/-Rforwards or running a remote command.
# Pick a host interactively from ~/.ssh/config
devssh
# Connect to a specific host
devssh my-dev-box
# Add an extra local forward for this session only
devssh my-dev-box -- -L 3000:localhost:3000
# Run a remote command (skip the interactive shell)
devssh my-dev-box -- htopThe module root is also an importable Go package:
package main
import (
"context"
"os"
devssh "github.com/scaryrawr/devssh"
)
func main() {
ctx := context.Background()
// This can be any OpenSSH Host alias, including one generated by another
// tool such as DevPod after it updates ~/.ssh/config.
opts := devssh.DefaultOptions("devpod-my-workspace")
opts.Stdin = os.Stdin
opts.Stdout = os.Stdout
opts.Stderr = os.Stderr
if err := devssh.Run(ctx, opts); err != nil {
panic(err)
}
}When the generated host entry lives outside the default OpenSSH config path,
pass the config file through Options.SSHOptions so the same alias is used for
the ControlMaster and follow-up ssh operations:
opts := devssh.DefaultOptions("devpod-my-workspace")
opts.SSHOptions = []string{"-F", "/path/to/generated/ssh_config"}Run owns the full devssh lifecycle: it starts the OpenSSH ControlMaster,
runs remote preflight, starts local browser/notification services, adds remote
forwards, uploads helper scripts, starts the remote port monitor, runs the final
interactive ssh command, and cleans up on exit. Use NewSession instead when a
caller needs to start the lifecycle and run additional commands through
Session.Mux() before calling Session.Interactive.
| Flag | Description |
|---|---|
--logs |
List recent log sessions and exit |
--install-xdg-open |
Also symlink ~/xdg-open.sh into /usr/local/bin on the remote (needs passwordless sudo) |
--no-xdg-open |
Skip uploading and installing the xdg-open shim |
--no-port-monitor |
Disable the remote port monitor |
--no-browser |
Disable the local browser-opener service |
--no-notifications |
Disable the local notification service |
-v, --verbose |
Print extra diagnostics to stderr |
Optional configuration file, defaulting to:
$OS_CONFIG_DIR/devssh/config.json
($OS_CONFIG_DIR is ~/.config on Linux, ~/Library/Application Support
on macOS, %AppData% on Windows.) Override the path with the
DEVSSH_CONFIG environment variable.
{
"reversePortForward": [
{ "port": 8081, "description": "Same port on both sides", "enabled": true },
{ "localPort": 3000, "remotePort": 13000, "description": "Alternate remote port", "enabled": true },
{ "localPort": 8080, "remoteSocket": "/tmp/my-service-$GUID.sock", "description": "Remote socket", "enabled": true }
],
"installXdgOpen": false,
"hosts": {
"my-dev-box": {
"installXdgOpen": true,
"reversePortForward": [
{ "port": 9090, "description": "Host-only service", "enabled": true }
]
}
}
}reversePortForwardentries are merged in this order: built-in defaults → top-level config → per-host overrides. Later entries override earlier ones by local endpoint.portis the legacy shorthand for forwarding local TCP portNto remote TCP portN. UselocalPortwithremotePortto expose a local service on a different remote port, orlocalPortwithremoteSocketto expose it as a remote Unix socket.$GUIDinremoteSocketis replaced with a per-forward UUID when devssh starts.- devssh installs the
xdg-openshim into~/.local/bin/xdg-openby default. Ensure~/.local/binis on the remotePATH. installXdgOpendefaults tofalse; when enabled, devssh also installs the shim into/usr/local/bin/xdg-open. Per-host overrides take precedence.
| Feature | Doc |
|---|---|
| Port forwarding (both directions) | docs/port-forwarding.md |
| Browser opening | docs/browser-opening.md |
| Desktop notifications | docs/notifications.md |
xdg-open shim |
xdg-open.sh |
Under the hood, devssh starts a dedicated SSH ControlMaster against the
target host (ssh -M -N -f -S <socket> host) and routes every subsequent
operation — helper-script upload, the port monitor, dynamic -O forward /
-O cancel calls, the interactive shell — through that single
multiplexed connection. On exit, it tears the master down with
ssh -O exit.
go test -v ./...
go test -v -race ./...
go test -short -v ./...See docs/testing.md for the full overview.
Forked from gh-ado-codespaces, which in turn built on
ado-ssh-auth.