Port forwarding

Use port forwarding to reach a service on a server from a local TCP port.

Service requirements

Port forwarding connects a local TCP port to a service on a server, such as a database or web application. The service must be reachable on the server’s 127.0.0.1; a service listening only on ::1 cannot be reached. Follow Open a tunnel to connect.

What a tunnel needs

  • The server’s Tunnel setting must be enabled by an administrator. See server settings.
  • An active work session must include the target server and Port forwarding (tunnel).
  • Sign in with alpacon login without -t. Service tokens and personal API tokens cannot open tunnels.
  • The server must support tunnels. If enabling the setting reports an agent requirement, ask an administrator to upgrade Alpamon. See the CLI reference for platform requirements.

When a tunnel ends

Press Ctrl+C to close a standalone tunnel. If you started a local command with the tunnel, it closes when that command exits.

A tunnel also ends when its work session completes, expires, or is revoked. A standalone CLI tunnel prints Error: tunnel connection lost: session closed by remote and exits 1. Start another approved session before reconnecting.

With -- COMMAND, a remote close prints Warning: Tunnel closed: session closed by remote and interrupts the local command. Check the local command’s result before retrying.

What is recorded

Tunnel traffic is forwarded but not captured. In live activity, Tunnels have no recording explains this limit. The session history records who opened the tunnel and when it closed, with the account, port, and client type.

Look for Opened port forwarding and Closed port forwarding in live activity. Use troubleshooting if opening or keeping a tunnel fails.

Last updated: