[Feat]: Built-in SSH tunnel profiles (jumphost, -L/-D forwards, SOCKS)

Start by reviewing #406 and the existing SSH tunnel lifecycle it describes, then map how database drivers establish connections. The proposal spans tunnel profiles, credential storage, UI, driver routing, and reconnect behavior, so agree on a smaller phase and its boundaries before implementation. For the proposed v1, done means profiles support Keychain auth and multiple local forwards, status is visible, and the listed MySQL, Postgres, and Elasticsearch local-forward connections work.

Prerequisites

• I have written a descriptive issue title
• I have searched existing issues to ensure the feature has not already been requested

🚀 Feature Proposal

Built-in SSH tunnel profiles with jumphost, local forwards (-L), dynamic SOCKS (-D), and per-connection routing — so enterprise users don't need external scripts, LaunchAgents, or local HTTP/TCP proxies to reach databases behind a corporate jumphost.

Tabularis already supports basic SSH tunneling for some drivers (see #406), but real-world corporate setups need more: a shared jumphost profile, multiple forwards on one SSH session, SOCKS routing for private IPs, Keychain-backed credentials, auto-reconnect, and native support in HTTP-based drivers (Elasticsearch, Redis, etc.).

---

Problem

Many developers connect to databases and search engines only reachable through a corporate jumphost and internal hostnames that don't resolve on the public internet. Today this requires fragile, per-machine setup outside Tabularis:

Workaround today	Pain
Manual ssh -D 1080 -L 19200:internal-host:9200 jumphost in a terminal	Dies on reboot; extra tab to babysit
macOS LaunchAgents	Auth/Keychain issues; hard to debug
Local Python proxies (e.g. ES 7.x compatibility shim)	Another process to maintain
expect + Keychain for password auth	Security tradeoffs; brittle
SOCKS on localhost:1080	Tabularis ES/HTTP plugins often cannot use SOCKS

Example real-world setup (enterprise):

Jumphost:  [email protected]
SOCKS:     localhost:1080
ES tunnel: localhost:19200 → internal-es-host:9200
ES proxy:  localhost:19201 → patches ES 7.x _cat/indices for Tabularis
Redis:     localhost:16379 → 10.x.x.x:6379 via SOCKS

A developer should not need 4 scripts, 4 LaunchAgents, and 2 proxy processes to browse data in Tabularis.

---

Proposed Solution

1. Tunnel Profiles (reusable)

Introduce Tunnel Profiles separate from database connections:

Name: Corporate Jumphost
SSH Host: jumphost.example.com
SSH User: developer
Auth: Keychain (ed25519 key) | Password (Keychain) | SSH Agent
Keep-alive: 30s
Auto-start: When Tabularis launches | When any linked connection opens

Forwards:
  - Type: SOCKS5
    Local: 127.0.0.1:1080
  - Type: Local (-L)
    Local: 127.0.0.1:19200
    Remote: internal-es-host:9200

Connections reference a tunnel profile instead of duplicating SSH settings.

2. Connection-level tunnel modes

Mode	Description
None	Direct connect (public/VPN reachable)
Use tunnel profile	Link to shared profile
Inline tunnel	SSH settings only for this connection
Local port only	User runs SSH externally; Tabularis uses localhost:PORT (with status check)

Routing options per connection:

• Direct — connect to configured host:port
• Via local forward — localhost:{local_port} → tunnel forwards to {remote_host}:{remote_port}
• Via SOCKS — connect through profile's SOCKS proxy (for raw private IPs)

3. UI (Connection modal)

New section: Networking → SSH Tunnel

[ ] Enable SSH tunnel for this connection

Tunnel profile: [ Corporate Jumphost ▼ ]  [Manage profiles…]

Routing:
  (•) Local port forward
      Local:  [ 19200 ]  →  Remote: [ internal-es-host ] : [ 9200 ]
  ( ) SOCKS proxy
      SOCKS: 127.0.0.1:1080  →  Target: [ 10.x.x.x ] : [ 6379 ]

Status: ● Connected (up 2h 14m)  [Reconnect] [View log]

☑ Start tunnel when opening this connection
☑ Reconnect automatically if dropped

Global: Settings → Tunnels → list all profiles, ports in use, "Test SSH".

4. Driver integration

For elasticsearch, clickhouse (HTTP), Redis, and similar:

• Local forward mode: connection URL uses http://user:[email protected]:{local_port} automatically.
• SOCKS mode: driver uses SOCKS5 for outbound TCP (no external TCP/HTTP proxy).
• Optional: built-in ES 7.x compatibility shim for _cat/indices (dataset.size field added in ES 8.x).

5. Credential storage

• SSH private keys and passwords in OS Keychain (macOS Keychain, Windows Credential Manager, libsecret on Linux).
• Never store passwords in plain-text connections.json.
• Support SSH agent ($SSH_AUTH_SOCK) as auth method.

6. Process model

• Tabularis runs a Tunnel Manager service:
  • One SSH process per tunnel profile (multiplexed forwards via ControlMaster).
  • Reconnect with exponential backoff.
  • Log to app log directory per profile.
• On app quit: optionally keep tunnels running (user preference) or tear down.

---

User Stories

1. Single jumphost, multiple services — One SSH session exposes SOCKS and forwards ES to localhost; open MySQL, ES, and Redis without multiple terminals.
2. Per-connection tunnel — Attach a tunnel profile to "Prod ES" so Tabularis auto-forwards to internal-es-host:9200.
3. SOCKS for internal IPs — Redis at a private IP works through SOCKS without a local TCP proxy script.
4. Survive sleep/reboot — Tunnels reconnect when laptop wakes or Tabularis starts.
5. Visibility — Connection card shows "Tunnel: connected" or "Tunnel: permission denied" before running a query.

---

Acceptance Criteria

1. Create a tunnel profile with SSH host, user, and Keychain auth.
2. Add SOCKS and multiple -L forwards to one profile.
3. Starting Tabularis (or opening a linked connection) brings tunnels up without external scripts.
4. Elasticsearch connection through -L forward works without a local HTTP proxy.
5. Redis connection to a private IP works through SOCKS without a local TCP proxy.
6. UI shows tunnel status; failed auth surfaces clear errors.
7. Tunnels reconnect after sleep/network change (configurable).
8. Credentials are not written to plain-text config files.

---

Phased Rollout

Phase	Scope
v1	Tunnel profiles, -L forwards, Keychain auth, status UI, MySQL/Postgres/ES via local forward
v1.1	SOCKS5 routing for Redis and raw IPs
v1.2	ES 7.x compatibility layer in driver
v2	ProxyJump, shared team profiles

---

Related

• #406 — existing SSH tunnel lifecycle bug (port left in use after server reboot); this proposal extends tunnel support and should address reconnect/port lifecycle holistically.

---

OS Version

macOS (also relevant for Linux enterprise users behind VPN/jumphost)

Tabularis Version

0.13.x (current)

Motivation

I manage 50+ database connections (MySQL, MongoDB, Elasticsearch, Redis, ClickHouse) behind a corporate jumphost. Without built-in tunnel profiles I maintain shell scripts, LaunchAgents, expect password helpers, and Python proxies just to make Tabularis work. First-class tunnel support would cut laptop onboarding from ~1 hour to minutes and eliminate an entire class of "connection refused on localhost" support issues.

Example

Before (6 moving parts):\n\n\nLaunchAgent: ssh-tunnels (1080, 19200)\nLaunchAgent: es-compatibility-proxy (19201)\nLaunchAgent: redis-tcp-proxy (16379)\nexpect + Keychain password script\nTabularis ES: http://user:pass@localhost:19201\nTabularis Redis: 127.0.0.1:16379\n\n\nAfter (Tabularis only):\n\n- Tunnel profile: SOCKS 1080 + -L 19200:internal-es-host:9200\n- ES connection: routes via local forward 19200\n- Redis connection: routes via SOCKS to 10.x.x.x:6379\n- No LaunchAgents, no Python proxies.