Configuring Remote Hosts

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

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

Identifier -- (Required) This is the unique permanent name used to reference this remote host configuration. It is used in the URLs that reference resources on the remote host. If a remote host configuration's ID is changed, Wing will track that change in all the remote host references stored in the project.

Host Name -- (Required) This is the remote host's DNS name or IP address. The the hostname should include the username, in the form username@hostname or username@ipaddress if the user name on the remote host is different from the user on 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.

WINGHOME -- (Required) This is the full path to the installation location of Wing's remote agent on the remote host. If missing, Wing will offer to create this directory and install the necessary files. If you have a copy of Wing Pro installed on the remote host already, this can be set to its installation directory and no remote agent installation will be needed.

Python Executable -- This 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 path relative to the configured base directory to a Python executable, or the full path to the Python executable. 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 -- This 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 -- Enable this to forward 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 (or on Windows, this is done in the SSH > Auth > X11 section of host configuration in the PuTTY tool, which you can launch with putty.exe). On Windows with VNC, you may instead need to set DISPLAY=:1 in the Environment in Project Properties.

SSH Port -- This 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 --- This is 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).

Use SSH Tunnel for username@localhost -- This controls whether the remote agent will connect using a reverse SSH tunnel even if the Host Name specifies a user name and localhost,, or other name or IP address for the local host. This must be enabled for containers like Vagrant and disabled if connecting to another user on the local host or when using Windows Subsystem for Linux. This option only affects the case where a user name is specified. An SSH tunnel is never used when connecting to the same user on localhost and always used when connecting to a different host.

Remote Agent Port -- This 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 -- This is the first TCP/IP ports 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.

After a remote host is configured, Wing will try to connect to that host and run its remote agent, and will offer to install the remote agent if it is not found. To install the remote agent, press the Install Remote Agent button. If this does not work, you may need to install the remote agent manually as described in Manually Installing the Remote Agent.

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 User 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 User 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 access from the Project > Remote Hosts menu item.

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.