SSH Reverse Tunnel Agent
The SSH reverse tunnel agent should not be confused with creating remote access to an SSH server via ngrok. If you want to use ngrok to create access to your own SSH server for remote access, please refer to the using ngrok with ssh documentation.
You should only ngrok via SSH if you really can't use an Agent or Agent SDK. The SSH reverse tunnel agent has many functional limitations compared to the ngrok agent.
Random HTTP Endpoint
ssh -R 443:localhost:80 firstname.lastname@example.org http
ssh -R example.ngrok.app:443:localhost:80 email@example.com http
ssh -R 443:localhost:80 firstname.lastname@example.org http \
--basic-auth "username1:password1" \
ssh -R 443:localhost:80 email@example.com http --oauth=google
Forward to non-local service
ssh -R 0:192.168.1.2:80 firstname.lastname@example.org http
Random TCP Endpoint
ssh -R 0:localhost:22 email@example.com tcp
Fixed TCP Endpoint
ssh -R 1.tcp.eu.ngrok.io:12345:localhost:3389 connect.eu.ngrok-agent.com tcp
ssh -R app.example.com:443:localhost:443 firstname.lastname@example.org tls
Explicit Region Selection
Normally you will connect to ngrok's closest point of present via Global Server Load Balancing, but you can also explicitly choose a region.
ssh -R 443:localhost:80 email@example.com http
Instead of an ngrok authtoken, when you use ngrok via the SSH reverse tunnel agent, it uses a public key for authentication. You'll first need to upload yours to the SSH Public Keys page on your ngrok dashboard.
Copy your default SSH public key with:
- Mac OS
cat ~/.ssh/id_rsa.pub | pbcopy
ngrok does its best to honor the syntax of
ssh -R. You may wish to consult
man ssh, and the section devoted to the
-R option for additional details.
ngrok uses additional command line options to implement features that are not
otherwise available via the
Let's break down the following command.
ssh -R \
http --basic-auth 'user:password'
ssh -R command has the following components:
ssh -R \
"<remote name>:<remote port>:<local name>:<local port>" \
In our example:
- Remote Name:
app.example.com. ngrok will listen on the domain 'app.example.com'. You may omit this value. If you do, ngrok chooses a random endpoint name.
- Remote Port:
443. ngrok will listen for HTTPS traffic on port 443. The only valid values for HTTP endpoints are 80 and 443. For TLS endpoints it must be 443. You may
0and ngrok will simply choose the appropriate port for you.
- Local Name:
127.0.0.1. This is the local hostname or IP address that traffic will be sent to. It's most commonly
- Local Port:
8080. This is the local port that traffic will be sent to.
v2. ngrok uses the user portion of the command to version the command options. You may omit this value. If you do, ngrok will use the latest version.
http. This the type of endpoint to create. ngrok accepts either
tcp. This value is required.
--basic-auth 'user:password'. Run the same command with the
--helpflag to get the list of supported flags or consult the Agent CLI reference.
ngrok uses the user portion of the SSH command to version the CLI syntax. The
latest version is
Differences from the Agent
When you use ngrok via SSH reverse tunnel, you will need to upload an SSH public key to authenticate with instead of using an ngrok authtoken like the agent.
Additionally, you'll find that using ngrok via SSH has many functional limitations compared to the experience with the agent. An incomplete list of differences from the ngrok agent includes:
- Your endpoints won't automatically reconnect if there is a network interruption
- There is no equivalent to the agent's traffic inspection interface
- You can't create endpoints for multiple services with the same command
- You can't forward to upstream https services
- You can't create multiple endpoints over the same connection
- You can't serve file system directories with the
- You can't terminate TLS at the agent when doing zero-knowledge TLS
- You can't run labeled tunnels for use with Edges.
The SSH reverse tunnel agent is available to all ngrok users at no additional charge. You only incur costs if resources you provision via its usage incur a cost.