gotun

English | 简体中文

Lightweight HTTP-over-SSH proxy written in Go, designed to be cross-platform and easy to deploy.

---

Overview

gotun is a command-line HTTP-over-SSH proxy. It establishes an SSH connection to a remote host and uses that host as the egress point for HTTP(S) traffic. Local HTTP requests are forwarded through the SSH tunnel and executed from the remote host.

Typical use cases:

• Accessing routers, servers, APIs and other resources in a private network
• Reaching networks that are only visible from a specific host (bastion/jump host, corporate network, isolated segments, etc.)
• Using the remote host as an outbound HTTP proxy

---

How it works

Before: no direct access to internal resources

Your machine                 Firewall/NAT                    Internal network
┌─────────┐                ┌─────────┐                     ┌─────────────┐
│         │   ❌ direct     │         │                     │  Router     │
│   PC    │ ─────────────▶ │  FW/NAT │                     │  NAS        │
│         │   blocked       │         │                     │  Servers    │
└─────────┘                └─────────┘                     └─────────────┘

After: access via SSH bastion with gotun

Your machine            SSH (tcp/22)                   Bastion                 Internal network
┌─────────┐          ┌─────────────┐                ┌─────────┐              ┌─────────────┐
│         │  HTTP    │  gotun HTTP │    SSH tunnel  │         │   internal   │  Router     │
│   PC    │ ◀──────▶ │   proxy     │◀──────────────▶│ Bastion │◀────────────▶│  NAS        │
│         │          └─────────────┘                │         │              │  Servers    │
└─────────┘                                         └─────────┘              └─────────────┘
   ↑
   └─ HTTP proxy set to 127.0.0.1:8080

Why use gotun?

| Traditional approach | With gotun | |---------------------------------------------|-------------------------------------------------| | Manual port forwards per service | One SSH tunnel for all HTTP(S) traffic | | Multiple ports exposed on the bastion | No extra open ports; uses existing SSH only | | Hard to manage multiple mappings | Single proxy endpoint | | Easy to accidentally expose internal hosts | All traffic stays inside an encrypted SSH tunnel |

---

Features

• No additional software required on the remote host (only SSH)
• All traffic is carried over an SSH tunnel
• Can reach any address that the remote host can reach (including internal addresses)
• Supports single and multi-hop SSH jump hosts
• Cross-platform: Windows, Linux, macOS
• Can be used as a system HTTP proxy (optional)
• TUN Mode: Supports standard TCP-based application proxying
• Rule-based traffic splitting via configuration file
• Shell completion support for Bash, Zsh, Fish, PowerShell
• Structured logging and verbose mode for debugging
• SOCKS5 proxy support

---

Installation

Install script

curl -fsSL https://raw.githubusercontent.com/Sesame2/gotun/main/scripts/install.sh | sh

The script installs gotun into ~/.local/bin or /usr/local/bin.
Make sure that directory is included in your PATH.

Homebrew (macOS / Linux)

brew install gotun

Download prebuilt binaries

Download the appropriate binary for your platform from the
Releases page.

Build from source

git clone https://github.com/Sesame2/gotun.git
cd gotun
make build

The binary will be placed under build/.

go install

With Go 1.17+:

go install github.com/Sesame2/gotun/cmd/gotun@latest

Note: when installing via go install, the --version output may not include an exact version number, as it depends on build-time metadata. For reproducible version information, prefer the install script, Homebrew, or release binaries.

Ensure $GOBIN or $GOPATH/bin is on your PATH.

---

Quick start

Basic usage

# Basic: connect to an SSH server and start an HTTP proxy
gotun user@example.com

# Use a non-default SSH port
gotun -p 2222 user@example.com

# Use a specific private key
gotun -i ~/.ssh/id_rsa user@example.com

# Change local proxy listen address/port
gotun --listen :8888 user@example.com

# Disable automatic system proxy configuration
gotun --sys-proxy=false user@example.com

# Enable SOCKS5 proxy (default listen on :1080)
gotun --socks5 :1080 user@example.com

Note: When using SOCKS5 with custom routing rules, it is recommended to enable "Proxy DNS when using SOCKS5" (Remote DNS) in your client. Otherwise, the client might resolve domains to IPs locally, causing domain-based routing rules to fail.

Browser configuration

By default, gotun listens on 127.0.0.1:8080 (unless changed by --listen).

In your browser’s proxy settings:

• HTTP proxy host: 127.0.0.1
• HTTP proxy port: 8080 (or the port you configured)

If system proxy support is enabled, some platforms can be configured automatically.

---

Command-line options

| Flag | Short | Description | Default | |------|-------|-------------|---------| | --http | | Local HTTP proxy listen address (alias for --listen) | :8080 | | --listen | -l | [Deprecated] Same as --http | :8080 | | --socks5 | | SOCKS5 proxy listen address | :1080 | | --port | -p | SSH server port | 22 | | --pass | | SSH password (insecure, interactive preferred) | | | --identity_file | -i | Private key file path | | | --jump | -J | Comma-separated jump hosts (user@host:port) | | | --http-upstream | | Force forward all HTTP requests to this upstream (host:port) | | | --target | | [Deprecated] Same as --http-upstream | | | --timeout | | Connection timeout | 10s | | --verbose | -v | Enable verbose logging | false | | --log | | Log file path | stdout | | --sys-proxy | | Auto-configure system proxy | true | | --rules | | Path to routing rules config file | |

---

Typical scenarios

1. Accessing internal services through a bastion

Assume jumpserver.company.com can reach 192.168.1.100 inside a private network:

gotun admin@jumpserver.company.com

Once running and proxy is configured, you can browse:

• http://192.168.1.100:8080
• Other HTTP(S) endpoints reachable from the jumpserver

2. Development and debugging

You need to reach a remote dev environment (APIs, DB, etc.) from your local machine:

# Verbose logging and custom listen port
gotun --listen :8888 -v developer@dev-server.com

If you do not want gotun to modify system proxy settings:

gotun --sys-proxy=false --listen :8888 -v developer@dev-server.com

Then configure your IDE or tooling to use 127.0.0.1:8888 as HTTP proxy.

3. Using a remote host as internet egress

gotun user@proxy-server.com

All (or selected) HTTP(S) traffic will exit from the remote server’s network.

---

Jump hosts

When the final target is only reachable via one or more intermediate hosts, you can configure jump hosts.

Workflow diagram

Your machine           SSH Tunnel            Jump Host             SSH Tunnel            Target Host
┌─────────┐         ┌───────────┐         ┌──────────┐         ┌───────────┐         ┌──────────┐
│         │   🔐    │           │    🔐   │          │    🔐   │           │   🌐   │          │
│   PC    │◀───────▶│ gotun tun │◀───────▶│ Bastion  │◀───────▶│ gotun tun │◀───────▶│  Target  │
│         │  HTTP   │ (encrypt) │         │          │         │ (encrypt) │        │          │
└─────────┘         └───────────┘         └──────────┘         └───────────┘         └──────────┘

Single jump host

gotun -J user1@jump.host.com user2@target.server.com

Traffic flow:

PC → SSH to jump.host.com → SSH to target.server.com → HTTP request

Multiple jump hosts

gotun -J user1@jump1.com,user2@jump2.com user3@target.com

gotun will establish nested SSH tunnels through each hop in order.

---

Authentication

SSH key authentication (recommended)

# Explicit key
gotun -i ~/.ssh/id_rsa user@example.com

# Rely on default keys in ~/.ssh
gotun user@example.com

Password authentication

# Interactive (recommended over CLI flags)
gotun user@example.com
# gotun will prompt for the password

# Non-interactive (not recommended)
gotun --pass 'yourpassword' user@example.com

Avoid passing passwords directly on the command line when possible.

---

System proxy integration

By default (--sys-proxy=true), gotun attempts to:

1. Capture the current system proxy settings
2. Set the system HTTP proxy to its local listening address (e.g. 127.0.0.1:8080)
3. Restore the original settings on exit

If you prefer to manage proxy settings yourself, run:

gotun --sys-proxy=false user@example.com

Platform notes:

• macOS: uses networksetup
• Windows: uses registry-based proxy configuration
• Linux: attempts to use desktop settings (e.g. GNOME) and/or environmen