Port Forwarding
OxideTerm supports local, remote, and dynamic SSH port forwarding, plus detection of remote listening ports. Start a rule from a connected host or save a standalone SSH tunnel in Session Manager.
Forwarding Types
Section titled “Forwarding Types”Local Forward (-L)
Section titled “Local Forward (-L)”Forward a port on your local machine to a remote host through the SSH tunnel.
Local Port ──SSH Tunnel──► Remote Host:PortUse cases:
- Access a remote web service (e.g., Jupyter Notebook on port 8888) from your local browser
- Connect to a remote database (MySQL, PostgreSQL) through a secure tunnel
- Access internal web UIs behind a firewall
Remote Forward (-R)
Section titled “Remote Forward (-R)”Forward a port on the remote server back to your local machine.
Remote Port ◄──SSH Tunnel── Local Host:PortUse cases:
- Expose a local development server to the remote environment
- Share a local service with colleagues on the remote network
- Webhook development — receive callbacks on a remote server and forward to your local app
Dynamic Forward (SOCKS5) (-D)
Section titled “Dynamic Forward (SOCKS5) (-D)”Create a SOCKS5 proxy through the SSH tunnel for flexible traffic routing.
Local SOCKS5 Port ──SSH Tunnel──► (any remote destination)Use cases:
- Route browser traffic through the remote server
- Access multiple internal services without individual port forwards
- Network debugging from the remote server’s perspective
Standalone SSH Tunnels
Section titled “Standalone SSH Tunnels”Use a standalone tunnel when you need a forwarded port without opening a terminal.
- Open New Connection → Advanced Connections → SSH Tunnel.
- Enter a name and optional group, then select the saved SSH host that will carry the tunnel.
- Choose Local, Remote, or Dynamic (SOCKS5). Set the bind address and port; local and remote forwards also need a destination host and port.
- Choose Save for later use, or Save and Start to connect now.
- Enable Connect on application startup only if this tunnel should connect whenever OxideTerm starts. Authentication may still require your input.
Manage saved tunnels from Session Manager and inspect running rules in Port Forwarding. A tunnel retains its own SSH connection usage, so closing an unrelated terminal does not stop it. Stop the tunnel explicitly when it is no longer needed. Exiting OxideTerm stops its tunnels; they do not run as an independent background service.
Tunnel profiles participate in cloud sync and encrypted .oxide import/export. Running connections are not synchronized. After moving a profile to another device, check the associated SSH host, authentication, and local bind port before starting it.
Smart Remote Port Detection
Section titled “Smart Remote Port Detection”OxideTerm automatically detects services listening on ports on the remote server. The Remote Listening Ports panel shows:
- Port number and bind address
- Process name (when available via
/procorss) - One-click forwarding — click Forward to create a local forward instantly, pre-populated with the correct port
This eliminates the need to remember port numbers or manually configure forwards.
Quick Forwards
Section titled “Quick Forwards”Pin frequently-used forwards as Quick Forwards for instant access. They appear as colored badges at the top of the Port Forwarding tab. One click to start, one click to stop.
Management
Section titled “Management”- View all active forwards with status, local/remote addresses, and real-time traffic stats (bytes in/out)
- Start / stop individual forwards
- Edit forwarding rules (port, bind address, remote host)
- Connection errors — inspect the rule status and reported error before retrying
- Idle connections — inactive forwarded data connections close after the default 300-second idle timeout; the forwarding listener can continue accepting new connections
Connection Ownership
Section titled “Connection Ownership”Forwarding uses the managed SSH connection and has its own listener and connection tasks. Closing a terminal releases that terminal’s use of SSH, not another active forward. Stopping a rule shuts down its forwarding tasks; explicitly disconnecting the owning SSH connection also interrupts its forwards.
Reconnect Behavior
Section titled “Reconnect Behavior”When a connection drops and reconnects, the reconnect orchestrator automatically restores all active and suspended port forwards:
- Snapshot — before disconnect, all active forward rules are captured (user-stopped forwards are excluded)
- SSH reconnect — new connection established with new
connectionId - Restore — each forward rule is re-created on the new session, skipping duplicates
- Status sync — UI updates to show restored forwards with fresh traffic counters
Forwards that were manually stopped by the user are not auto-restored — the orchestrator respects user intent.
State Gating
Section titled “State Gating”All forwarding operations require connection state active. The UI disables forwarding controls during link_down or reconnecting states, preventing operations on a dead SSH channel.