Skip to content
scaryrawrPublic

About

vibes for richer ssh experience

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

14 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

devssh

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 / $BROWSER in 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-open shim — 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.

Requirements

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).
  • sshd with AllowStreamLocalForwarding yes if you want browser and notification socket forwarding (the default on most distros).
  • Passwordless sudo is only required if you opt in to the system-wide xdg-open symlink (see --install-xdg-open).

Missing remote tools degrade individual features gracefully — the SSH session itself doesn't depend on any of them.

Installation

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@latest

Usage

devssh [flags] [host] [-- ssh-flags-or-remote-command...]
  • If [host] is omitted, devssh parses ~/.ssh/config and shows a picker of concrete Host aliases (wildcards skipped).
  • Anything after -- is passed straight to the interactive ssh invocation — useful for ad-hoc -L/-R forwards 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 -- htop

Library Usage

The 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.

Flags

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

Configuration

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 }
      ]
    }
  }
}
  • reversePortForward entries are merged in this order: built-in defaults → top-level config → per-host overrides. Later entries override earlier ones by local endpoint.
  • port is the legacy shorthand for forwarding local TCP port N to remote TCP port N. Use localPort with remotePort to expose a local service on a different remote port, or localPort with remoteSocket to expose it as a remote Unix socket. $GUID in remoteSocket is replaced with a per-forward UUID when devssh starts.
  • devssh installs the xdg-open shim into ~/.local/bin/xdg-open by default. Ensure ~/.local/bin is on the remote PATH.
  • installXdgOpen defaults to false; when enabled, devssh also installs the shim into /usr/local/bin/xdg-open. Per-host overrides take precedence.

How It Works

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.

Testing

go test -v ./...
go test -v -race ./...
go test -short -v ./...

See docs/testing.md for the full overview.

Acknowledgments

Forked from gh-ado-codespaces, which in turn built on ado-ssh-auth.

About

vibes for richer ssh experience

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages

⌂ 换网址