SSH Tunnel Switch

Rotate SSH SOCKS5 tunnels through a REST API or CLI. The built-in HTTP proxy forwards HTTP requests and HTTPS CONNECT traffic through the active tunnel, using SOCKS5 for remote DNS resolution.

The server runs independently and requires Python 3.12+ and OpenSSH. No OpenCode, Node.js, Bun or plugin is required.

Install and run

python3 -m venv .venv
.venv/bin/python -m pip install ssh-tunnel-switch
.venv/bin/tunnel-switch --version
.venv/bin/tunnel-switch init-config --output config.yaml

init-config is available from version 1.0.0. It creates a mode-0600 example and refuses to overwrite existing files. For 0.1.0, download the example configuration and protect it with chmod 600 config.yaml.

Edit the SSH host aliases in the YAML. Verify host keys and key/agent authentication using your normal SSH client before starting the service. SSH accounts must allow TCP forwarding. Existing ~/.ssh/config settings apply when YAML does not override them.

.venv/bin/tunnel-switch validate --config config.yaml
.venv/bin/tunnel-switch serve --config config.yaml

Startup generates and saves an API token if needed and prints it to the console. Keep the configuration and logs private. On an interactive terminal serve shows a live status panel while timestamped service and access logs are written to the log file (logging.file); when run under systemd the timestamped lines also reach the journal. By default the SOCKS5 listener is 127.0.0.1:1080, the HTTP proxy is 127.0.0.1:8118, and the REST API is 127.0.0.1:8765. The panel also carries an HTTP requests row with the requests the proxy sent over the current SSH connection and over the one before it, described under Use the proxy.

The service watches its YAML and applies configuration changes without restarting or dropping the tunnel (systemctl reload or POST /reload trigger it immediately). On an interactive terminal the status panel also responds to keys: Ctrl+R reloads the configuration, Ctrl+E connects, Ctrl+D disconnects, Alt+R restarts the current server, Ctrl+N rotates to the next, Alt+S (or Ctrl+S, which needs no Option-key setting) opens a picker over the configured servers — a pop-up over the dashboard whose window scrolls to fit the display when they do not all fit — so you can connect to a chosen one, and Ctrl+C still stops the service. The rotation cooldown still gates the API, Alt+R and Ctrl+E, but not the deliberate keys Ctrl+N and Alt+S/Ctrl+S. The panel title shows the running version, which is also reported by tunnel-switch --version, the serve startup banner and GET /status.

Use the proxy

curl --proxy http://127.0.0.1:8118 https://example.com/
.venv/bin/tunnel-switch status --config config.yaml
.venv/bin/tunnel-switch rotate --config config.yaml

Proxy-aware applications can use HTTP_PROXY and HTTPS_PROXY set to http://127.0.0.1:8118; set NO_PROXY=localhost,127.0.0.1,::1 for direct local control calls. SOCKS-aware clients can use socks5h://127.0.0.1:1080 directly. HTTPS remains encrypted end to end. Forwarding fails when SOCKS is unavailable and never falls back to a direct destination connection.

Every request the proxy carries is counted: a forwarded request and a CONNECT each count once, while a request the tunnel could not carry counts nowhere and the encrypted requests inside a CONNECT tunnel cannot be seen at all. The totals are shown in the status panel's HTTP requests row and reported by GET /status as requests.current for the current SSH connection and requests.last for the connection before it.

The bearer token protects the REST API only. HTTP and SOCKS proxy listeners are unauthenticated: retain loopback defaults or restrict access with a firewall. Protect remote REST access with TLS. See the security policy.

Guides

• Configuration, restart state and REST API
• Linux systemd deployment
• Troubleshooting
• Compatibility and tested platforms
• Development, review and releases
• Changelog

License

MIT.