Configuring Remote Hosts

Index of All Documentation » Wing Pro Reference Manual » Remote Development »

Remote hosts are configured using Remote Hosts in the Project menu, to tell Wing about the remote host and how to connect to it. The following values may be specified in the three tabs of the remote host dialog:

Identifier (required) is the unique short name used to reference this remote host configuration. It is used in the URLs that reference resources on the remote host. If an existing remote host configuration's ID is changed, Wing will track that change in all the remote host references stored in the project. However, for shared remote host configurations, it's best not to change the identifier after it is used.

Host Name (required) is the remote host's name or IP address. The the host name may include the username, in the form username@hostname or username@ipaddress. This is needed if the user name on the remote host is different from the user on the local host. For containers hosted by Vagrant or similar tools, the host name must include username@ even if the remote and local user names are the same. This tells Wing that an SSH tunnel is necessary even if the host name or IP address is for the local host. If this field is changed in an existing remote host configuration, Wing will try to find remote resources on the new host name.

Python Executable is the Python to use for running Wing's remote agent and for debugging or executing remotely. This can be left blank if Python can be found on the PATH. In this case, Wing first looks for python3 and then falls back to using python. Otherwise, it can either be set to Activated Env to enter a command that activates a virtualenv or Anaconda environment on the remote host (so that python launches the correct Python), or it can be set to Command Line to specify the python to run. In the latter case, it should be the name of a Python that can be found on the PATH, the full path to the Python executable, or a path relative to the configured Base Directory (see below). When in doubt about the location of the Python you want to use, run it outside of Wing and execute import sys; print(sys.executable) to obtain the value to use. Note that if your activate script's full path contains a space you will need to use Command Line instead. If your Python cannot be run without certain environment variables, such as PYTHONHOME or PYTHONPATH, you will need to set up a custom startup script as described in Specifying Environment for the Remote Python.

Base Directory is the directory on the remote host from which all file references are made, so that Wing will show only the relative path from the configured base directory. By default, it is the remote user's home directory. If this value is a partial path, it is interpreted to be relative to remote user's home directory. When this value is changed on an existing configuration, Wing will try to find resources relative to the new base directory.

Forward X11 enables X11 display from the remote host to the host where Wing is running. On macOS and Windows this requires installing and configuring an X11 server, such as XQuartz on macOS or MobaXTerm on Windows. With OpenSSH this uses ForwardX11Trusted style forwarding. For finer control of authentication options, leave this option disabled in Wing and instead set options in your .ssh/config file. On Windows with PuTTY, this is done in the SSH > Auth > X11 section of host configuration in PuTTY. On Windows with VNC, you may instead need to set DISPLAY=:1 in the Environment in Project Properties.

SSH Port sets the port on which OpenSSH is running on the remote host. The default is port 22 or whatever port number is configured in .ssh/config if using OpenSSH. When using PuTTY, Wing ignores port numbers configured by a saved session and always uses port 22 as the default. This works around a bug in PuTTY's pscp.exe that prevents remote agent installation when there is no PuTTY saved session. As a result, any non-standard port number used by a host reached through PuTTY must also be set here in Wing's remote host configuration.

Private Key specifies how Wing accessed the private key to use when connecting to the remote host. The default is to use the SSH user agent (ssh-agent for OpenSSH or pageant for PuTTY). The key file format must match the SSH implementation being used (usually .rsa or .pem for OpenSSH and .ppk for PuTTY). With OpenSSH on Linux or macOS, the key file must be set to be readable only by the user running Wing, for example with chmod 600 mykey.pem. Private key files used with this property cannot be encrypted. Thus, from a security standpoint, using an SSH user agent instead is usually preferable.

File Encoding is the default text encoding to use when opening or creating files on the remote host, if the file does not explicitly set the encoding.

I/O Encoding is the text encoding to use for I/O to and from processes started on the remote host by the debugger or OS Commands tool.

Install Dir is the full path to the installation location of Wing's remote agent on the remote host. Wing will automatically install and update the remote agent as needed. Using the default for this setting is recommended, since that will automatically add and remove remote agent installations according to which versions of Wing you are using.

Manage SSH Tunnel controls whether Wing manages SSH tunnels to allow the remote agent and debugger to connect from the remote host to the IDE. The default of Auto-configured establishes SSH tunnels only if the remote host is not the same as the local host. This should be disabled for container systems that automatically forward network traffic, such as Windows Subsystem for Linux (WSL), and it must be enabled when connecting to isolated containers that appear to be the same as localhost, like Vagrant. Important: When this option is disabled, network traffic between the IDE and the remote system is entirely unencrypted, both for the remote agent and the debugger. This option should only be disabled when working on the local host or if the underlying network is otherwise encrypted (for example, by a VPN or a manually configured encrypted tunnel).

Remote Agent Port is the TCP/IP port to use for the remote agent on the remote end of the SSH tunnel. When this is not specified, Wing uses a random port number determined on the IDE side of the connection. This usually works but there is no guarantee that the port will also be available on the remote end. When set, this property should be an unused unprivileged ephemeral port number (usually between 1025 and 65535 on Windows, 32768 and 61000 on Linux, and 49152 and 65535 elsewhere). When a fixed port is specified, Wing still uses a random port on the local end of connections, unless Manage SSH Tunnel is also disabled. In that case, the same port number is used at both ends of the connection, and this must match port mappings established by configuration made outside of Wing. This option must be set to Use Random Port when using ControlMaster in the OpenSSH configuration. Using a fixed port in that case may fail because the control master can prevent reusing the port when the remote agent is restarted.

Remote Debug Port is the first TCP/IP port to use for the debugger on the remote end of the SSH tunnel. By default, as for Remote Agent Port, a random port is used. When a value is specified, Wing uses only ports starting with the given port, up to however many ports are needed for active debug sessions and Python Shells. When a port is specified, Wing still uses a random port on the local end of connections, unless Manage SSH Tunnel is also disabled. In that case, the same port number is used at both ends of the connection, and this must match port mappings established by configuration made outside of Wing. This option must be set to Use Random Port when using ControlMaster in the OpenSSH configuration because that will hold onto previously used SSH tunnel ports indefinitely until the remote host is restarted.

2FA Card Selector is used with OpenSSH integrations that prompt for selection of a 2FA card at startup. The text entered is written to the SSH process at startup. It is stored as plain text in the remote host configuration so should not be used for passwords. This value is only used with OpenSSH and not PuTTY.

Installing and Running the Remote Agent

After a remote host is configured, Wing will try to connect to that host and install the remote agent if it is not already present. If installation of the remote agent fails, you will be presented with diagnostic output to send to for help.

In rare cases you may need to install the remote agent manually as described in Manually Installing the Remote Agent. One such case can occur on Linux when uname reports a different bittedness than is being used by Python. For example, uname may report a 64-bit system but Python may be 32-bit.

Once installed, the remote agent is started or restarted as needed and will exit after a timeout period if it is unused. The remote agent allows Wing to search, inspect, read, and write files and directories, create or delete files, start debug or execution, run unit tests, invoke version control operations, run Python Shell, invoke commands in OS Commands, and perform other actions on the remote host to support the IDE's functionality. The necessary SSH tunnels for communication to the remote agent and to support debugging files remotely are also managed automatically.

You can find a log of the remote agent's activities in the file remote-agent.log within the Settings Directory on the remote host.

Shared Remote Hosts Configurations

Remote host configurations can either be stored in the project file or shared in the Settings Directory so they can be accessed from all projects. To make a remote host configuration shared, check the Shared box for that configuration in the remote host manager accessed from Remote Hosts in the Project menu.

In general, a shared remote host configuration should be used when the project file is stored on the remote host, and non-shared remote host configurations should be used when a project file is stored locally but accesses resources on a remote host.