mkloubert / vscode-remote-workspace

Multi protocol support for handling remote files like local ones in Visual Studio Code.

vscode-remote-workspace

Multi protocol support of new Visual Studio Code FileSystem API, especially for handling remote files like local ones.

Table of contents

1. Install
2. How to use
   • About parameters
     • Import parameters
     • Placeholders
       • Code
       • Environment variables
       • Static
   • Azure
     • Parameters
     • Remarks
   • Dropbox
     • Parameters
   • FTP
     • Parameters
   • FTPs
     • Parameters
   • S3 Buckets
     • credential_type
     • Parameters
   • SFTP
     • Parameters
       • mode
       • Using ssh-agent
   • Slack
     • Parameters
     • Remarks
   • WebDAV
     • Parameters
       • authType
3. Commands
4. Logs
5. Support and contribute
   • Contributors
6. Related projects
   • node-simple-socket
   • vscode-helpers

Install [↑]

Launch VS Code Quick Open (Ctrl + P), paste the following command, and press enter:

ext install vscode-remote-workspace

Or search for things like vscode-remote-workspace in your editor.

How to use [↑]

Create (or update) a .code-workspace file and open it by using File >> Open Workspace... in the GUI:

{
    "folders": [{
        "uri": "sftp://my-user:[e-mail]?debug=1",
        "name": "My SFTP folder"
    }]
}

If you've never created a .code-workspace file, you might start with a new folder in your home directory, for instance you could name it "VSCodeWorkspace" or "MyApp". Copy the example configuration (shown above) into a new file, and make sure you edit the URI to be specific to your desired protocol and path. Save the file, ensuring the file name ends with .code-workspace. Then, in the VS Code GUI, open that file using File >> Open Workspace...; after a few moments you'll be connected to the URI you specified.

About parameters [↑]

A parameter is a key-value-pair, which has to be setup in the URI and NOT in the settings section of a .code-workspace file.

If you want to set the debug parameter to 1 for a SFTP connection, e.g.:

{
    "folders": [{
        "uri": "sftp://myUser:[e-mail]?debug=1",
        "name": "My SFTP folder"
    }]
}

Import parameters [↑]

Any URI / protocol supports a general parameter, called params, which can load / import parameters from an external file, that contains a JSON object.

For example, you can create a file, lets say sftp_server1_uri_params.json, inside your home directory with the following content:

{
    "debug": 1,
    "mode": 664,
    "key": "id_rsa",
    "phrase": "My Key Passphrase",
    "noPhraseFile": 1
}

In the URI, inside your .code-workspace file, you have to define the params parameter and set it to the path / name of that JSON file:

{
    "folders": [{
        "uri": "sftp://myUser:[e-mail]?params=sftp_server1_uri_params.json",
        "name": "My SFTP folder"
    }]
}

Relative paths will be mapped to the user's home directory.

Explicit URI parameters, which are also defined in such an external file, will be overwritten by the values of the file.

Placeholders [↑]

An URI parameter can store placeholders, which are replaced by the values of an external file.

For example, you can create a file, like my_values.json, inside your home directory with the following content:

{
    "importEnvVars": true,
    "exclude": [
        "fooParam"
    ],
    "values": {
        "ENC": {
            "code": " ('UTF' + '8').toLowerCase() ",
            "type": "code"
        },
        "FOO": "bar",
        "SSL": {
            "value": 1
        }
    }
}

You can now place them into the values of parameters, by using the format ${VAR_NAME}:

{
    "folders": [{
        "uri": "webdav://myUser:[e-mail]/?values=my_values.json&ssl=${SSL}&encoding=${ENC}&binEncoding=${ENC}&fooParam=${FOO}",
        "name": "My WebDAV folder"
    }]
}

If importEnvVars is set to (true), all environment variables of the current process will be imported automatically. The default value is (false).

Parameters, where placeholders DO NOT work:

• params
• values

Code [↑]

{
    "values": {
        "FOO": {
            "code": " $h.normalizeString('b' + 'AR') ",
            "type": "code"
        }
    }
}

Code execution allows you to access the following constants, which contain modules, functions and special values:

Name	Description
_	lodash module
$fs	fs-extra module
$h	vscode-helpers module
$l	Logger object (s. Logs)
$m	Moment.js module, with timezone support
$os	os module
$p	path module
$r	Extened require() function, which also allows to use the modules of that extension.
$v	An object with variables, like $v['cache'], which stores an object for caching values for later executions.

Keep in mind: Code is always executed synchronous and NOT via things like promises!

Environment variables [↑]

{
    "values": {
        "FOO": {
            "name": "SSH_AUTH_SOCK",
            "type": "env"
        }
    }
}

Static [↑]

{
    "values": {
        "foo1": "bar1",
        "Foo2": {
            "value": 2
        }
    }
}

Azure [↑]

URL Format: azure://[account:key@][container][/path/to/file/or/folder][?param1=value1&param2=value2]

{
    "folders": [{
        "uri": "azure://my-account:my-storage-key@my-container/",
        "name": "My Azure folder"
    }]
}

For accessing local storage emulator, use something like that:

{
    "folders": [{
        "uri": "azure://mycontainer/",
        "name": "My local Azure folder"
    }]
}

Parameters [↑]

Name	Description	Example
auth	A path to a file, that contains the part left to @ (the credentials). Relative paths will be mapped to the user's home directory.	auth=my_azure_account
host	The custom host address.	host=azure.example.com
params	The name of an external file, which contains other parameters for the URI. s. Import parameters	params=azure_uri_params.json
values	The name of an external file, which contains placeholders	values=my_values.json

Remarks [↑]

If you create a new folder, a file called .vscode-remote-workspace with 0 size is created there, to keep sure to detect that new folder later. Before you delete that file, you should store another file there, otherwise the directory will disappear.

Dropbox [↑]

URL Format: dropbox://token[/path/to/file/or/folder][?param1=value1&param2=value2]

{
    "folders": [{
        "uri": "dropbox://<API-TOKEN>/",
        "name": "My Dropbox folder"
    }]
}

Parameters [↑]

Name	Description	Example
auth	A path to a file, that contains the part left to @ (the API token). Relative paths will be mapped to the user's home directory.	auth=dropbox_token
params	The name of an external file, which contains other parameters for the URI. s. Import parameters	params=dropbox_uri_params.json
values	The name of an external file, which contains placeholders	values=my_values.json

FTP [↑]

URL Format: ftp://[user:password@]host[:port][/path/to/a/folder][?param1=value1&param2=value2]

{
    "folders": [{
        "uri": "ftp://my-user:[e-mail]/",
        "name": "My FTP folder"
    }]
}

Parameters [↑]

Name	Description	Example
auth	A path to a file, that contains the part left to @ (the credentials). Relative paths will be mapped to the user's home directory.	auth=ftp_server1
follow	Follow symbolic links or not. Default: 1	follow=0
keepAlive	Defines a time interval, in seconds, that sends a NOOP command automatically to keep the connection alive.	keepAlive=15
noop	The custom FTP command to execute to check if connection is still alive. Default: NOOP	noop=SYST
params	The name of an external file, which contains other parameters for the URI. s. Import parameters	params=ftp_uri_params.json
queue	Use a queue for each action inside the connection. Default: 1	queue=0
queueSize	Maximum number of actions to execute at once inside a connection. Default: 1	queueSize=3
values	The name of an external file, which contains placeholders	values=my_values.json

FTPs [↑]

URL Format: ftps://[user:password@]host[:port][/path/to/a/folder][?param1=value1&param2=value2]

{
    "folders": [{
        "uri": "ftps://my-user:[e-mail]/",
        "name": "My (secure) FTP folder"
    }]
}

Parameters [↑]

Name	Description	Example
auth	A path to a file, that contains the part left to @ (the credentials). Relative paths will be mapped to the user's home directory.	auth=ftps_server1
follow	Follow symbolic links or not. Default: 1	follow=0
keepAlive	Defines a time interval, in seconds, that sends a NOOP command automatically to keep the connection alive. Default 10	keepAlive=45
legacy	Use ftp module instead of forked @icetee/ftp, if you have problems. Default: 0	legacy=1
params	The name of an external file, which contains other parameters for the URI. s. Import parameters	params=ftps_uri_params.json
queue	Use a queue for each action inside the connection. Default: 1	queue=0
queueSize	Maximum number of actions to execute at once inside a connection. Default: 1	queueSize=3
rejectUnauthorized	Reject unauthorized server certificates or not. Default: 0	rejectUnauthorized=1
secure	Use secure (1) or plain (0) FTP connection. Default: 1	secure=0
values	The name of an external file, which contains placeholders	values=my_values.json

S3 Buckets [↑]

URL Format: s3://[credential_type@]bucket[/path/to/file/or/folder][?param1=value1&param2=value2]

{
    "folders": [{
        "uri": "s3://my-bucket/?acl=public-read",
        "name": "My S3 Bucket"
    }]
}

credential_type [↑]

Default value: shared

Name	Description	Class in AWS SDK
environment	Represents credentials from the environment.	EnvironmentCredentials
file	Represents credentials from a JSON file on disk.	FileSystemCredentials
shared	Represents credentials loaded from shared credentials file.	SharedIniFileCredentials
values	The name of an external file, which contains placeholders	values=my_values.json

Parameters [↑]

Name	Description	Example
api	A string in YYYY-MM-DD format that represents the latest possible API version that can be used in this service. Specify latest to use the latest possible version.	api=latest
acl	The ACL for new or updated files to use. Default: private	acl=public-read
debug	Set to 1, to debug a connection, by writing all messages to log files. Default: 0	debug=1
endpoint	The endpoint URI to send requests to. The default endpoint is built from the configured region. The endpoint should be a string like https://{service}.{region}.amazonaws.com.	endpoint=https%3A%2F%2Ffoo.bar.amazonaws.com
file	If credential type is set to file, this defines the path to the .json file, which should be used. Relative paths will be mapped to the .aws sub folder inside the user's home directory.	file=aws.json
params	The name of an external file, which contains other parameters for the URI. s. Import parameters	params=s3_uri_params.json
profile	If credential type is set to shared, this defines the name of the section inside the .ini file, which should be used. Default: default	profile=mkloubert
values	The name of an external file, which contains placeholders	values=my_values.json
varPrefix	If credential type is set to environment, this defines the custom prefix for the environment variables (without _ suffix!), which contain the credentials. Default: AWS	varPrefix=MY_AWS_PREFIX

SFTP [↑]

URL Format: sftp://[user:password@]host[:port][/path/to/a/folder][?param1=value1&param2=value2]

{
    "folders": [{
        "uri": "sftp://my-user:[e-mail]/",
        "name": "My SFTP folder"
    }]
}

Parameters [↑]

Name	Description	Example
agent	Name or path to ssh-agent for ssh-agent-based user authentication.	agent=myAgent
agentForward	Set to 1, to use OpenSSH agent forwarding ([e-mail]) for the life of the connection. Default: 0	agentForward=1
allowedHashes	Comma-separated list of hashes to verify.	allowedHashes=md5,sha-1
auth	A path to a file, that contains the part left to @ (the credentials). Relative paths will be mapped to the user's home directory.	auth=ftp_server1
debug	Set to 1, to debug a connection, by writing all messages to log files. Default: 0	debug=1
dirMode	Defines a special chmod access permission value for the folders on server. This can be an octal number or the path to a JSON file, that contains a "mapper" object. If not defined, the value of mode parameter is used. s. mode for more information.	dirMode=755
follow	Follow symbolic links or not. Default: 1	follow=0
hash	The algorithm to use to verify the fingerprint of a host. Possible values are md5 and sha-1 Default: md5	hash=sha-1
keepAlive	Defines a time interval, in seconds, that sends "keep alive packages" automatically.	keepAlive=15
keepMode	Tries to detect the current chmod access permission value of an existing file on server and tries to apply it when saving. Default: 1	keepMode=0
key	The path to the key file or the Base64 string with its content. Relative paths will be mapped to the sub folder .ssh inside the user's home directory.	key=id_rsa
mode	Defines the chmod access permission value for the files / folders on server. This can be an octal number or the path to a JSON file, that contains a "mapper" object. s. mode for more information.	mode=644
noop	By default, a list operation is done for the root directory of the server, to check if a connection is alive. You can change this by executing a fast command on the server, which does not produce much response, e.g.	noop=uname
noPhraseFile	1 indicates, that phrase parameter will NEVER handled as file path. Default: 0	noPhraseFile=1
params	The name of an external file, which contains other parameters for the URI. s. Import parameters	params=sftp_uri_params.json
phrase	The passphrase (or path to a file with it) for the key file, if needed. To prevent conflicts, you should additionally set noPhraseFile to 1, if that value is explicitly a passphrase value and NO path to an external file. Relative file paths will be mapped to the user's home directory.	phrase=myPassphrase
queue	Use a queue for each action inside the connection. Default: 1	queue=0
queueSize	Maximum number of actions to execute at once inside a connection. Default: 1	queueSize=3
timeout	How long (in milliseconds) to wait for the SSH handshake to complete. Default: 20000	timeout=60000
tryKeyboard	Try keyboard-interactive user authentication if primary user authentication method fails. Can be 0 or 1. Default: 0	tryKeyboard=1
values	The name of an external file, which contains placeholders	values=my_values.json

mode [↑]

For the parameters dirMode and mode, you can define an octal number, which will be applied to all files and folders, which are created or changed.

You also can define a path to a JSON file, which contains a mapper object:

{
    "644": [
        "**/*.php",
        "**/*.phtml"
    ],
    "777": "/*.txt"
}

Save the content to a file, like sftp_modes.json, inside your user directory, e.g., and save your mapping in the format as described by the upper JSON snippet.

To use the mappings, setup the mode parameter with the path of that file (in that example to sftp_modes.json). Relative paths will be mapped to the user's home directory.

Glob patterns are handled by minimatch.

Using ssh-agent [↑]

If you use ssh-agent for ssh login, you will likely need to use an environment variable to get the path for the agent parameter. To do this, you'll need to create a values json file to pull the appropriate variable. For instance, in MacOS X, the default ssh-agent path is in $SSH_AUTH_SOCK:

$ ssh-agent
SSH_AUTH_SOCK=/var/folders/w9/mq8x8g87880wn99v2pdx77vr0000gn/T//ssh-VCVBAx48ZEXj/agent.37705; export SSH_AUTH_SOCK;
...

Make a json file to get this value. For instance:

{
    "values": {
        "SSHSOCK": {
            "name": "SSH_AUTH_SOCK",
            "type": "env"
        }
    }
}

Finally, in your .code-workspace file, reference the values json file, and the agent. For instance, if your values json file is named remotessh.json in ~/VSCodeworkspace, your .code-workspace file might have

{
    "folders": [{
        "uri": "sftp://my-user:[e-mail]/?values=VSCodeworkspace/remotessh.json&agent=${SSHSOCK}",
        "name": "My SFTP folder"
    }]
}

Slack [↑]

URL Format: slack://token@channel[/][?param1=value1&param2=value2]

{
    "folders": [{
        "uri": "slack://<API-TOKEN>@<CHANNEL-ID>",
        "name": "My Slack channel"
    }]
}

Parameters [↑]

Name	Description	Example
auth	A path to a file, that contains the part left to @ (the API token). Relative paths will be mapped to the user's home directory.	auth=slack_token
params	The name of an external file, which contains other parameters for the URI. s. Import parameters	params=slack_uri_params.json
values	The name of an external file, which contains placeholders	values=my_values.json

Remarks [↑]

The protocol only supports read and list operations.

WebDAV [↑]

URL Format: webdav://[user:password@]host[:port][/path/to/file/or/folder][?param1=value1&param2=value2]

{
    "folders": [{
        "uri": "webdav://myUser:[e-mail]/?ssl=1",
        "name": "My WebDAV server"
    }]
}

Parameters [↑]

Name	Description	Example
auth	A path to a file, that contains the part left to @ (the credentials). Relative paths will be mapped to the user's home directory.	auth=webdav_server1
base	The base path, that is used as prefix for all requests.	base=nextcloud/remote.php/webdav/
binEncoding	The encoding for reading and writing binary files to use. Default: binary	binEncoding=utf8
encoding	The encoding for reading and writing text files to use. Default: binary	encoding=utf8
authType	Kind of authentication to use if at least a username and/or password is defined (s. authType. Default: basic	authType=digest
params	The name of an external file, which contains other parameters for the URI. s. Import parameters	params=webdav_uri_params.json
ssl	Use secure HTTP or not. Can be 0 or 1. Default: 0	ssl=1
values	The name of an external file, which contains placeholders	values=my_values.json

authType [↑]

Defines, what type of authentication should be used, if at least a username and/or password is defined. Possible values are:

Name	Alternatives	Description
basic	b	Basic access authentication
digest	d	Digest access authentication

Commands [↑]

Press F1 and enter one of the following commands:

Name	Description	ID
Remote Workspace: Execute 'git' Command ...	Executes git CLI tool on a remote workspace.	extension.remote.workspace.executeGit
Remote Workspace: Execute Remote Command ...	Executes a command on a remote workspace.	extension.remote.workspace.executeRemoteCommmand
Remote Workspace: Open URI ...	Adds / opens a new workspace folder with a supported URI.	extension.remote.workspace.openURI
Remote Workspace: Receive Remote URI ...	Receives a remote URI from another editor.	extension.remote.workspace.receiveWorkspaceURI
Remote Workspace: Reset Remote Command History ...	Resets all values of last executed remote commands.	extension.remote.workspace.resetRemoteCommandHistory
Remote Workspace: Share Remote URI ...	Shares a remote URI with another editor.	extension.remote.workspace.sendWorkspaceURI

If you want to define shortcuts for one or more command(s), have a look at the article Key Bindings for Visual Studio Code.

Logs [↑]

Log files are stored inside the .vscode-remote-workspace/.logs subfolder of the user's home directory, separated by day.

Support and contribute [↑]

If you like the extension, you can support the project by sending a donation via PayPal to me.

To contribute, you can open an issue and/or fork this repository.

To work with the code:

• clone this repository
• create and change to a new branch, like git checkout -b my_new_feature
• run npm install from your project folder
• open that project folder in Visual Studio Code
• now you can edit and debug there
• commit your changes to your new branch and sync it with your forked GitHub repo
• make a pull request

Contributors [↑]

• Angeart
• drpark
• Massimiliano Torromeo
• mlibbey
• Sandro
• TurekBot

Related projects [↑]

node-simple-socket [↑]

node-simple-socket is a simple socket class, which supports automatic RSA encryption and compression for two connected endpoints and runs in Node.js.

vscode-helpers [↑]

vscode-helpers is a NPM module, which you can use in your own VSCode extension and contains a lot of helpful classes and functions.