Use OuterSSH with an existing browser

The outerssh command-line tool connects to an SSH server and opens local HTTP or SOCKS proxies for your browser. It runs on macOS, Linux, and Windows and uses the same C library as Outer Loop.

You can also forward a single TCP port and use your browser without changing its proxy settings.

Get the tool

Build the OuterSSHCLI target from the Outer Loop source repository. See the build instructions for macOS, Linux, and Windows.

The OpenSSH ssh executable must also be on your PATH. outerssh uses it to resolve SSH configuration; OuterSSH itself owns the SSH connection and forwarding.

Start an HTTP proxy

outerssh --http-proxy 8080 --rewrite-http user@server

Replace user@server with your server or an alias from your SSH configuration. Wait for the ready message, which reports the listening port after authentication succeeds. Leave the command running while you browse.

Configure your browser to use an HTTP proxy at 127.0.0.1:8080, including for HTTPS destinations through CONNECT. Then open a remote application, for example:

http://3000.localhost.outerssh.invalid/

That URL reaches 127.0.0.1:3000 on the SSH server, not on your computer. The encoded host is understood by OuterSSH and does not require DNS. You can also browse ordinary hostnames through the proxy; those connections originate from the SSH server.

--rewrite-http enables both request-authority and HTML rewriting: the HTTP compatibility transformations used by Outer Loop. Rewriting is off by default. HTTPS remains an opaque TLS tunnel, and browser certificate validation still applies.

Example: a separate Chrome instance on macOS

"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
  --user-data-dir=/tmp/outerssh-http-chrome \
  --proxy-server="http://127.0.0.1:8080" \
  --proxy-bypass-list="<-loopback>"

The separate profile keeps this session apart from your normal browsing. The bypass override sends literal loopback destinations through the proxy too, so http://localhost:3000/ refers to the remote server. With Chrome or Chromium on Linux or Windows, use the installed browser executable and a suitable separate profile directory with the same flags. Other browsers expose proxy configuration through their own settings.

Close this dedicated browser instance when you stop the proxy. Chromium documents the proxy flags and loopback bypass behavior.

Forward just one application

For a service listening on port 3000 on the SSH server:

outerssh -L 8080:localhost:3000 user@server

Open http://localhost:8080/ in your usual browser, without configuring a proxy. This is a raw TCP forward: it does not rewrite HTTP, and proxy credentials do not apply to it. An app that generates absolute links to its remote localhost port may need the HTTP proxy approach instead.

Repeat -L for multiple services, or combine it with proxy listeners. All share the SSH session pool:

outerssh -L 8080:localhost:3000 -D 1080 --http-proxy 8081 user@server

Use SOCKS instead

outerssh -D 1080 user@server

Configure the client for SOCKS5 at 127.0.0.1:1080 and send destination hostnames to the proxy instead of resolving them locally. SOCKS carries raw bytes; it does not rewrite HTTP even if an HTTP listener is also running.

For a quick command-line check:

curl --proxy socks5h://127.0.0.1:1080 --noproxy '' http://localhost:3000/

The h in socks5h delegates hostname resolution to the proxy. Chrome does not support SOCKS5 username/password authentication; use HTTP for authenticated Chrome proxy sessions. See Chromium’s SOCKS5 limitations.

SSH authentication and proxy credentials

The tool reads OpenSSH configuration through ssh -G, including aliases, usernames, ports, identity settings, and agent configuration. You can override common fields:

outerssh --http-proxy 8080 -i ~/.ssh/id_ed25519 user@server
outerssh --http-proxy 8080 --ask-passphrase user@server
outerssh --http-proxy 8080 --password user@server
outerssh --http-proxy 8080 -p 2222 user@server

SSH passwords and key passphrases are prompted for in the terminal. Host keys are checked against the selected known-hosts file: unknown keys require confirmation, and changed keys are rejected. --known-hosts path selects a file; --batch rejects cases that require a prompt.

Both listeners bind only to IPv4 loopback and require no proxy authentication by default. To require a separate proxy username/password:

outerssh --http-proxy 8080 --rewrite-http --proxy-user browser user@server

Enter the proxy password when the tool prompts, then supply those credentials in the browser’s proxy authentication prompt. They are separate from your SSH credentials. --proxy-password-env VARIABLE reads the proxy password from a named environment variable for automation. When both HTTP and SOCKS are enabled, they use the same proxy credentials.

Current boundaries

The CLI provides TCP forwarding. It does not package the remote socket-bridge binaries required for Unix-socket authorization and privileged access. For the integrated Unix-socket experience, use Outer Loop or build a client that supplies those resources and recovery callbacks.

An ordinary browser also does not gain Outer Loop’s http+unix:// or outerloop:// navigation handlers, friendly address bar, session-context script, or dynamic loopback compatibility script merely by using this proxy. Encoded loopback TCP URLs work directly; custom product schemes do not.

ProxyJump, ProxyCommand, remote command execution, and UDP forwarding are not supported by this CLI. HTTP rewriting has the same limits as the library frontend, including no inspection of encrypted HTTPS content.

Stop and troubleshoot

Ctrl-C stops the tool and closes its listeners, forwarding connections, and SSH session. Ctrl-Break also works on Windows; SIGTERM is supported on Unix. Startup failures exit nonzero. Individual connection failures are reported on stderr without stopping the proxy.

Use --http-proxy 0 or -D 0 to choose an available port, then configure the browser with the port printed in the ready message. If a remote page cannot be reached, check the destination service and port, browser proxy/bypass settings, and the diagnostic on stderr.

Run outerssh --help for the option list. The CLI source guide has additional configuration details and test instructions.