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 and is a supported version of Python. Otherwise, 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). 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. For virtualenv, just use the full path to virtualenv's Python executable. This sets up the necessary environment before running your code. When in doubt, run the Python you want to use outside of Wing and inspect sys.executable after typing import sys. This is the value you want to use for the Python Executable in the remote host configuration.

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 OS X and Windows this requires installing and configuring an X11 server, such as XQuartz on OS X 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 or PuTTY's saved sessions.

Private Key specifies the private key file 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 for OpenSSH and .ppk for PuTTY).

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.

Use SSH Tunnel for username@localhost controls whether the remote agent will connect to Wing over a reverse SSH tunnel even if connecting to another user on the local host. This should be disabled if the user is another account on the local host or when connecting to Linux running under Windows Subsystem for Linux (WSL) and must be enabled when connecting to isolated containers like Vagrant.

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).

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.

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 support@wingware.com 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.