Back to docs index

Port Forwarding

Termial supports SSH port forwarding (tunneling), allowing you to securely access services through an SSH connection.

Types of Port Forwards

Local Forward (-L)

Forward a port from your local machine to a remote destination through the SSH server.

Use case: Access a database or web service running on the remote network.

Your Computer:8080 → SSH Server → Remote Database:3306

Remote Forward (-R)

Forward a port from the remote server to your local machine.

Use case: Let the remote server access a service on your computer.

Remote Server:8080 → SSH Tunnel → Your Computer:3000

Dynamic Forward (-D)

Create a SOCKS5 proxy that routes all traffic through the SSH connection.

Use case: Browse the web as if you were on the remote network.

Creating a Port Forward

Saved Port Forwards

Create persistent port forward configurations:

  1. Go to the Port Forwards section
  2. Click New Port Forward
  3. Configure the settings:
    • Name: A friendly name for this tunnel
    • Connection: Select which SSH connection to use
    • Forward Type: Local, Remote, or Dynamic
    • Ports: Configure the ports based on type

Local Forward Settings

  • Local Port: Port on your computer to listen on
  • Remote Host: Destination host (from SSH server's perspective)
  • Remote Port: Destination port

Remote Forward Settings

  • Remote Bind Port: Port on the remote server to listen on
  • Local Host: Destination on your computer (usually localhost)
  • Local Port: Port on your computer

Dynamic Forward Settings

  • SOCKS Port: Local port for the SOCKS5 proxy
  1. Click Save

Quick Tunnels

Create temporary tunnels tied to a terminal session:

  1. Connect to an SSH server
  2. Click Quick Port Forward in the connection menu
  3. Configure the tunnel
  4. Click Start

Quick tunnels close when the terminal session ends.

Managing Port Forwards

Starting a Tunnel

  1. Find your saved port forward
  2. Click Start Tunnel
  3. The tunnel connects through the associated SSH connection
  4. Status shows as active

Stopping a Tunnel

  1. Find the active tunnel
  2. Click Stop Tunnel
  3. The tunnel disconnects

Viewing Active Tunnels

Active tunnels are shown with their status:

  • Connection state
  • Local/remote ports
  • Data transferred

Examples

Access Remote MySQL Database

Connect to a MySQL database on a server's internal network:

  1. Create a new port forward
  2. Type: Local (-L)
  3. Local Port: 3306
  4. Remote Host: database.internal
  5. Remote Port: 3306

Now connect to localhost:3306 to reach the remote database.

Access Remote Web Service

Access a web service only available on the remote network:

  1. Type: Local (-L)
  2. Local Port: 8080
  3. Remote Host: internal-app.local
  4. Remote Port: 80

Open http://localhost:8080 in your browser.

SOCKS Proxy for Web Browsing

Browse as if you're on the remote network:

  1. Type: Dynamic (-D)
  2. SOCKS Port: 1080

Configure your browser to use SOCKS5 proxy at localhost:1080.

Expose Local Dev Server

Let remote server access your local development server:

  1. Type: Remote (-R)
  2. Remote Bind Port: 8080
  3. Local Host: localhost
  4. Local Port: 3000

Remote users can access server:8080 to reach your local port 3000.

Troubleshooting

Port Already in Use

If you get "address already in use":

  • Another application is using that port
  • Choose a different local port
  • Find and stop the conflicting application

Connection Refused

If the tunnel connects but the service doesn't work:

  • Verify the destination host and port are correct
  • Check if the service is running on the remote end
  • Ensure firewall allows the connection

Tunnel Keeps Disconnecting

  • Check your SSH connection stability
  • Enable keep-alive in the SSH connection settings
  • Verify network connectivity

Tips

  • Use specific local ports to avoid conflicts
  • Name your tunnels descriptively
  • Save frequently used tunnels for quick access
  • Close tunnels when not in use to free resources