Portway

lxsmlv

Cross-platform desktop manager for SSH tunnels and Kubernetes port-forwards. Go 1.25 + Wails v2 + Svelte 5.

Portway

Cross-platform desktop tool (macOS / Windows / Linux) for managing SSH tunnels and Kubernetes port-forwards to remote infrastructure — with one click from the system tray.

🛠️ Status: personal project · Stack: Go 1.25 + Wails v2 + Svelte 5

What it does

If you work against a remote / corporate dev environment through a jump-host VPN + Kubernetes review stands, you probably have a ~/bin pile of shell scripts that:

open dozens of SSH tunnels to loopback aliases (127.0.0.2, 127.0.0.3, …),
wrangle kubectl port-forward supervisors so they don't die on sleep/wake,
patch .env files in your projects when you switch namespaces,
rewrite /etc/hosts and kick dnsmasq so the right domains resolve.

Portway is a polished desktop replacement for that pile. Everything runs from a single tray-bar app with persistent state, auto-recovery, and native OS integration.

Features

SSH tunnels — dozens of forwards opened in a few seconds via jump-host, with automatic IP resolution over SSH.
Kubernetes port-forward supervisor — managed kubectl port-forward processes with automatic restart on failure, sleep-aware.
DNS handling —
- macOS / Linux: generates a dnsmasq config so *.example.com resolves to loopback aliases;
- Windows: updates %SystemRoot%\System32\drivers\etc\hosts.
.env auto-patching — when switching Kubernetes namespaces, recursively finds .env* files in your project tree and rewrites the connection variables (REDIS_HOST, KAFKA_HOST, MS_CFG_NAMESPACE, etc.).
Sleep / wake awareness — native OS signals (NSWorkspace on macOS, D-Bus on Linux, WM_POWERBROADCAST on Windows) so tunnels survive laptop suspend for up to ~12 hours and recover automatically.
Two modes —
- Full: jump-host VPN + SSH tunnels;
- Lite: VPN already runs on this machine, only DNS / /etc/hosts management needed.
System tray — app runs in the background, status per tunnel at a glance.

Tech stack

Area	Technology
Desktop shell	Wails v2 (Go ↔ JS bridge)
Backend	Go 1.25 (single binary per platform)
Frontend	Svelte 5 + Vite 6 + TypeScript 5.7
Native integration	macOS: PF (Packet Filter), `dnsmasq`, NSWorkspace Linux: PF / `iptables`, D-Bus Windows: `hosts` file, `WM_POWERBROADCAST`
CI/CD	GitHub Actions (planned)
License	MIT

Repository layout

.
├── app.go                 # Wails-bound methods (Go ↔ JS API surface)
├── main*.go               # Platform entry points (darwin / linux / windows)
├── setup_{darwin,linux,windows}.go  # Per-platform install / privilege bootstrap
├── sleep_{linux,windows}.go         # Native sleep/wake hooks
├── tray_*.go              # System tray per platform
├── cmd/
│   └── jumphost-setup/    # Small CLI to configure an SSH jump-host
├── internal/
│   ├── config/            # JSON config (~/.portway/config.json), defaults, schema
│   ├── tunnel/            # SSH tunnel supervisor, IP resolution, PF anchor wiring
│   ├── portforward/       # kubectl port-forward supervisor + .env patcher
│   ├── logger/            # Structured logs
│   └── platform/          # OS-specific helpers (privilege elevation, etc.)
├── frontend/              # Svelte 5 UI (Vite 6)
└── build/                 # App icons, Wails build metadata, platform assets

Running locally

Prerequisites:

Go 1.25+
Node 20+
Wails CLI: go install github.com/wailsapp/wails/v2/cmd/wails@latest

# Dev mode with hot reload (Go + frontend)
wails dev

# Tests (Go side)
go test ./internal/...

# Production build (macOS example)
./build.sh darwin

Configuration

On first launch Portway creates ~/.portway/config.json with a minimal example configuration. Edit it through the Settings screen or by hand. The defaults ship with placeholder services (service-a.example.com, git.example.com, k8s-api.example.com) — swap them for your real targets.

Key sections:

Section	Purpose
`ssh`	Jump-host (`host`, `remoteUser`, `keyPath`)
`tunnels[]`	SSH local-forwards (`localIP:localPort` → `remoteHost:remotePort`)
`k8s`	`kubectl` context + list of port-forward services
`paths.searchDir`	Root folder scanned for `.env*` files
`pf.anchorName`	macOS PF anchor name (default `portway_pf`)

Why this project exists

A few reasons:

Shell scripts are great — until they're not. Once you're juggling 20+ tunnels, two Kubernetes contexts, and a dnsmasq config across macOS / Windows / Linux teammates, a GUI with persistent state beats bash + cron.
Go + Wails is the smallest thing that can ship a native desktop app. Single binary, tiny runtime, real OS integration — no Electron, no browser. Perfect for internal / DevEx tooling.
Sleep/wake robustness is underrated. A lot of "my tunnels died" reports are actually laptop suspend. Portway handles this natively so teammates stop filing it as a bug.

License

MIT — use, fork, adapt freely.

Top categories