Remote Hosts

Index of All Documentation » Wing Pro Reference Manual » Project Manager »

Wing Pro can work with Python code that is stored on a remote host or device in the same way that you work with code stored locally. This includes editing, debugging, testing, search, version control, Python Shell, OS Commands, and project management.

Remote development is supported to OS X and Linux (Intel or ARM). A detailed list of supported remote host types is on the Supported Platforms page. Wing Pro itself can be running on any of the supported OSes.

How it Works

Wing's remote development support works by installing a remote agent that it uses to carry out operations on the remote host. All communication to the remote host is over secure SSH tunnels, one to access the remote agent, and one for each debug process.


Notice that files are stored on the remote host, and everything you do is run on the remote host, including running tests, debugging, executing files and command lines, searching, and issuing version control operations.

The remote agent replaces the need for setting up file sharing to the remote host, manually establishing SSH tunnels, defining file location maps, and other manual configuration required for remote debugging in previous versions of Wing.

If you have used wingdbstub for manually configured remote debugging in the past, you can continue to use that approach. Or you can switch to using a remote host configuration, which supports both launching your remote debug process directly from Wing (see below) or continuing to use wingdbstub through the remote agent if you need to launch your code from outside of the IDE.

If you prefer to store the master copy of your code on your local system, you can do this as well by setting up file sharing to the remote host using Samba, NFS, or other file sharing method. However, you will still use the remote agent to access the files on the remote system, rather than opening them directly from local disk in the IDE.

Setting up SSH

To work with a remote host, you first need to set up secure SSH remote access outside of Wing Pro. You should configure this so you can connect to the host without having to enter a password each time you connect. Instead, you want authentication to occur using an SSH key, and by entering your password once to load the key into an SSH user agent.

On Linux and OS X this is done with the standard OpenSSH tool suite that comes with the OS. On Windows this can be done with PuTTY or by using OpenSSH provided by Cygwin or Git Bash. If you do not already have this set up, or you cannot log into the remote host without entering a password every time you connect, please refer to SSH Setup Details before going any further.

Accessing SSH From Wing

Once you have SSH working outside of Wing, and can connect to the remote host without entering a password for each connection, start Wing in an environment where it will be able to access your SSH keys via the SSH user agent. How this is done varies according to OS and which SSH implementation you are using:

Windows with PuTTY -- Start pageant.exe from the command line. Then right-click on the icon that appears in lower right of your screen and select Add Key to add your key. You may need to redo this each time you log in. The private key file can also be passed to pageant.exe on the command line.

Windows with Cygwin or Git Bash -- Start Cygwin and type ssh-agent bash on the command line. Type ssh-add to add your key. Then type set | grep SSH_, copy the SSH_AGENT_PID and SSH_AUTH_SOCK lines, and paste them into the Environment in Wing's Project Properties. You will need to redo this each time you quit Cygwin since the contents of the environment variables will change. One way to avoid having to set these environments is to create your SSH key without an encryption password. For details see Connecting without SSH User Agent below.

OS X -- Add your key to Keychain Access and optionally set usage restrictions for the key with Get Info from the File menu.

Linux -- Add your key with ssh-add on the command line. You need to rerun ssh-add each time you log in. If for some reason your Linux does not run ssh-agent on its own, see the instructions for Windows with Cygwin above.

Wing uses the following command line tools to implement secure access to remote hosts: ssh and scp (with OpenSSH) or plink.exe and pscp.exe (with PuTTY).

Wing tries to find these tools on the PATH on the machine where Wing IDE is running, and on Windows it also searches for PuTTY and Cygin-provided ssh (in that order) in common installation locations if it cannot find it on the PATH.

If Wing cannot find ssh or plink.exe you will need to add its directory to your PATH or set the Network > SSH Executable preference in Wing to the full path of the command. If this is set, Wing also tries to find scp (or pscp.exe on Windows with PuTTY) in the same directory as the specified executable.

Connecting without SSH User Agent

Although we recommend against it from the standpoint of maintaining proper security, it is possible to use SSH without an SSH user agent. This is done by creating an SSH key without an encryption password.

With OpenSSH, the key can either be saved as the default ~/.ssh/id_rsa or, preferably from a security standpoint, you can create a key used just for a specific host by pointing ssh at it in the ~/.ssh/config file as in the following example:

Host somehost
    User someuser
    IdentityFile ~/.ssh/someuser@somehost/id_rsa_no_pw

With PuTTY on Windows, configuration is instead done with putty.exe where you create a saved session and set the private key file for authentication in the Connection > SSH > Auth configuration area. Then save the session and plink.exe will use that unencrypted private key without prompting for a password.

Configuring Remote Hosts

Remote hosts are configured using the Remote Hosts item in the Project menu. 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 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.

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

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.

Project Configuration

There are two ways to work with remote hosts: (1) a locally stored project file can reference remote resources, and (2) a project file stored on a remote host and opened remotely can transparently access resources on that remote host.

Local Project Files

For projects stored locally that need to access resources on another host, the Python Executable property in Project Properties is set to Remote to indicate that a project's Python resides on a remote host. The remote host configuration that is selected is typically an unshared configuration, so that it is stored in the project and will be accessible if the project is moved to another machine. Note, however, that remote host configurations may be specific to an individual machine's network environment, and may need to be edited on other hosts.

After Python Executable has been set, other properties that reference files (such as Initial Directory and Python Path) will be resolved on the remote host. The Browse buttons for those properties will browse the remote host, and paths will be stored as partial paths relative to the configured Base Directory or as full paths if located outside of the Base Directory. Paths on remote hosts are always expressed using forward slash / and will be converted as needed to the native separator on the remote host.

The selected remote host will also be used for adding files and directories to the project. When a URL for a remote file or directory is shown, it will be in the form ssh://hostid/path/to/ where hostid is one of the configured Remote Host IDs.

A locally stored project can include files and directories on multiple hosts, by adding several hosts and using Add Existing File and Add Existing Directory with each host.

Remote Project Files

Projects stored on a remote host are opened with Open Remote Project in the Project menu. This menu item is not shown unless you have alreayd created a shared remote host configuration. Projects stored like this are normal Wing projects and may also be opened locally, if Wing can also be run on the remote host itself. In this case, Python Executable is simply set to Default or Custom, as if the project were stored locally. Wing resolves all the resources in the project file in a way that allows it to access them on the host where the project is stored.

If any remote host configurations are added to a remotely stored project, in order to access other remote hosts, those configurations must work on the host where the IDE is running.

Creating Project Files

To set up a new project that accesses a remote host, use New Project in the Project menu and specify Connect to Remote Host (via SSH) as the project type. This will ask for the same fields described above for creation of a remote host configuration. If you have already created a configuration previously, use the Recent Hosts drop down to copy that configuration.

The New Project dialog will offer to save the project either locally or on the selected remote host. If it is stored locally, the entered remote host configuration will be stored in the project file. If it is stored remotely, the configuration will be set up as shared so it is always accessible on the local machine, even if the remote project is not open.

A regularly created local project can also be moved to a remote host with Save Project On Remote Host` in the Project menu. This menu item is visible only if there is at least one shared remote host configuration. Saving the project in this way moves only the project file itself, and assumes that resources referenced by the project will also be available on the remote host, with the same relative paths from the project file.

Working with Remote Hosts


Once you have set up a project with remote files, you can start debugging one of those files in the same way that local files are debugged. Wing will initiate the debug connection automatically through its SSH tunnels to the remote host. Filenames will be shown in the form hostid:filename but otherwise debugging works the same way as if it were on the local host.

To debug on several different remote hosts, use Launch Configurations in the Project menu to create debug configurations on each host. This is done in the same way as for Project Properties (by setting Python Executable under the Python tab to Remote). Then set up a Named Entry Point that pairs a file on that remote host with a launch configuration for the same remote host.

Whether you use the Project-wide settings or a launch configuration, the file you debug needs to be stored on the selected remote host. You cannot debug a file from one host on another host using this style of remote debug configuration.

Note that the Debugger > Listening preferences are not used when debugging remotely and starting the debug process from the IDE. Instead, Wing is establishing an SSH tunnel that makes both the debug process and IDE appear to be running on the same host.

The Debugger > Diagnostics preferences are also not used when debugging remotely using remote hosts. The following environment variables can be used instead to collect debugger diagnostics. These should only be used at the request of Wingware Technical Support and the resulting log file can be emailed along with your bug report to

WINGDB_LOGFILE -- This can be used to set up a diagnostics log file when trouble- shooting problems with the debugger. The environment variable should be set to the full path of the log file on the remote host.

WINGDB_LOGVERYVERBOSE -- Whether to print extremely verbose low-level logging. This is almost never needed and will drastically slow down debugging.

Debugging Externally Launched Code

If you need to start your debug processes from outside Wing, as for services running on a remote host, you can debug those processes by importing wingdbstub. When you install the remote agent, Wing writes a correctly configured copy of into the remote agent's installation directory. To use it, follow the instructions in Debugging Externally Launched Remote Code.

Python Shell

Once you have set Python Executable in Project Properties to a remote host, you can restart the Python Shell from its Options menu to launch a shell that is running on the remote host.

Testing Remotely

If remote files have been added to the Testing tool the unit tests can be run or debugged as if they are on the same host as the IDE.

Version Control

If remote files are checked into a version control system, Wing should identify this as it does for local files and include the appropriate tools in the Tools menu. Version control features work the same way for remote files as for local files. However, it may be necessary to configure version control for the remote host using the VCS tab in Project Properties.

Operations that access the version control repository (such as push and pull) may not work due to lack of access to the necessary ssh keys. There are two possible solutions for this:

  • If the remote VCS command tries to display a password collection dialog, you can turn on the Forward X11 option in your remote host configuration, so that the dialog will appear on the machine where Wing is running.
  • You can forward the local host's ssh agent credentials to the remote host by adding ForwardAgent yes to your .ssh/config on the machine where Wing is running. It's best to limit this to the hosts that require it and you should do it only if you understand the security implications.

OS Commands

The OS Commands tool also supports working remotely with the Hostname property under the Environment tab of Command Line style commands. For Python File and Named Entry Point style OS Commands, the host name is inferred from the location of the file being executed.

Section Contents