vscode-sshfs: mounting a remote host as a VS Code workspace folder over SSH

A file system provider, which is a different thing from remote editing

vscode-sshfs is an extension for Visual Studio Code providing a file system provider using SSH, and the README describes it as allowing mounting remote folders as local workspace folders, launching integrated remote terminals and running ssh-shell tasks.

The mechanism matters here, because it is not the same as VS Code's own remote development. The package.json declares the activation events as onFileSystem:ssh and onFileSystemAccess:ssh, which is the API a file system provider registers. The extension implements that provider, and VS Code then treats the remote path as a folder.

The README is explicit about the consequence. This works well with extensions using the vscode.workspace.fs API, added in VS Code 1.37.0, although not all extensions switched over, especially ones making use of binary files. That caveat is the sharpest limit in the whole project, and it is worth internalising before you move a workflow onto it. An editor extension that predates the file system API, or one that wants the raw bytes of a file, will not behave the same way over a remote provider as it does over a local folder.

The primary language is TypeScript, the licence is GPL-3.0, and the author is Kelvin Schoofs. The version is 1.27.0, the default branch is master, and the last push was on 2026-06-07, the same day as the v1.27.0 release. The release before that was v1.26.1 in April 2023, so the recent work is a long gap closed by a single substantial release.

Configurations live in settings.json and merge across scopes

The built-in config editor is the part of the extension that decides how everything else behaves, and the storage model is worth understanding.

The config editor stores configurations by default in your User Settings, in settings.json, under the sshfs.configs key. The stored object is a flat list of connection descriptors.

"sshfs.configs": [
    {
        "name": "hetzner",
        "putty": "Hetzner",
        "label": "Hetzner",
        "hop": "hetzner2",
        "root": "/root"
    }
],

The README explains what those fields are for, and the putty field is the interesting one. The config is configured to copy settings, for example username and host, from the PuTTY session, and because the author had loaded a private key into Pageant, PuTTY's agent, this allows a connection without providing a password or passphrase. The root field specifies that all file operations, as in ssh://hetzner/some/file.js, are relative to the /root directory on the server, and the hop field points at another configuration to route through.

The merging rules are documented precisely, and they are the sort of detail that saves an afternoon. Configurations are read from your global User Settings, the current workspace's settings, and any JSON files configured with sshfs.configpaths. Even when the workspace overrides this setting, the globally-configured paths will still be read. The workspace versions do have higher priority for merging or ignoring duplicates.

So it is a layered read with workspace precedence on conflicts, not a replacement. A setting that appears in both scopes does not cause the global one to disappear, it causes the workspace one to win, and a file in an sshfs.configpaths location is read alongside the others rather than instead of them.

ssh:// URIs, and how the root field maps to a path

The remote workspace folder feature mounts a remote directory as a regular local workspace folder, using the same configuration as the config editor, and the URI scheme is the standard one.

The extension supports any ssh:// URI. The README gives a worked example of opening ssh://hetzner/ng-ui as a folder, which resolves to /root/ng-ui on the remote server, and notes that by default the button or command opens ssh://hetzner/, which would then mount /root, because that is what the Root config field is set to. You can set it to whatever, including ~/path.

The right-click integration is a small touch that shows how the pieces fit. Right-clicking a remote directory gives the option to instantly open a remote terminal in that directory, which means the terminal inherits the path context of whatever you clicked rather than starting at the home directory.

Terminals are started from a simple button or from the command palette, and by default the extension uses $SHELL to launch your default user shell. A config option exists to change this, with examples given as ksh - or exec .special-profile; $SHELL. That matters for the many remote setups where a plain login shell does not give you the environment your tooling expects, and it is why the option is expressed as a full command line rather than a shell name.

Connection reuse is the other behaviour that shows up in practice. If a connection is already opened for a configuration, there is no need to reauthenticate, and as long as the configuration has not changed, existing connections, both for workspace folders and terminals, will be reused. The Miscellaneous section adds the other half of that picture: active connections are reused to minimize prompts, and a connection gets closed if there is no terminal or file system using it for over five seconds.

That five second rule is the practical detail to know. It means the extension is not holding a multiplexed connection open indefinitely, which keeps the server side clean, and it also means a burst of activity that touches a remote file twice in quick succession reuses one connection while a later one reconnects.

Remote shell tasks, and the ssh2 configuration underneath

A new task type, ssh-shell, is added to run shell commands remotely, and the task terminal opens a full PTY terminal on the server. That is a different thing from the integrated terminal feature, since a task is something the editor's task runner owns and reports on, and the PTY means interactive programs behave as they would in a real terminal rather than with piped input.

The extension also allows a custom sftp subsystem command. By default it uses the sftp subsystem as indicated by the remote SSH server, which in reality usually results in /usr/lib/openssh/sftp-server being used. The SFTP Command setting allows specifying a different command instead of the default subsystem, and the SFTP Sudo setting makes the extension try to create a sudo shell, for the given user or whatever sudo defaults to, and run the SFTP Command, or /usr/lib/openssh/sftp-server by default. For most users, setting this to <Default> should allow operating on the remote file system as root, and the README warns that power users who change the SFTP Command to something like sudo /some-sftp-server might run into trouble with password prompts.

Internally the ssh2 package is used, and the raw config JSON objects, as seen in the config editor, are apart from some special fields a one-on-one mapping of the config options supported by that package. Power users can therefore edit settings.json to reach options the UI does not expose, with the algorithms.cipher field given as the example for specifying a list of ciphers to use.

That mapping is the extension's escape hatch and also its compatibility surface. Because the config is a pass-through to ssh2, anything ssh2 supports is available, and anything ssh2 changes is a change in your remote connections. The Terminal command option works the same way, overriding the command used to launch the remote shell, where by default the extension launches a remote shell over the SSH connection, runs cd if necessary, and then runs $SHELL.

Proxy support is in the same category. Several proxy types are supported, SSH hopping, HTTP and SOCKS 4/5, with SSH Hop referring to using another configuration to hop through, similar to OpenSSH's ProxyJump, which is the field shown in the hop config.

The limits, and what to check before you commit a workflow to it

Three constraints are visible in the documentation, and they are the ones to check first.

The first is the binary file caveat, already mentioned, and it is the one with the widest blast radius. An extension that has not moved to the vscode.workspace.fs API may not see the remote file the way it expects, and the README singles out extensions making use of binary files. A workflow that depends on an image preview, a diff view of a compiled artefact or a notebook reader is the kind that breaks.

The second is that the engine requirement has moved. The package.json declares the vscode engine as ^1.123.0, which is a recent Visual Studio Code, and the version history shows a three year gap between v1.26.1 in 2023 and v1.27.0 in 2026. The extension is not stale, but it was rewritten against a current editor, and a user on an older VS Code will not get this version.

The third is that this is one way of working rather than a full remote development environment. VS Code's own remote support gives you the editor UI running on the remote machine, with the extensions you install there running there too, and it has its own file system provider. vscode-sshfs takes a narrower path, where the editor runs locally and the files are remote. The advantage of that arrangement is that the local editor and its local extensions are the ones doing the work, and the disadvantage is the binary file caveat and the fact that latency is on every file operation.

The market for this shape of tool is real, and it is not a niche. Developers who work on a single server, who do not want a full container or a remote development session, and who want their own editor with a remote folder, are the audience. The README also points to a Roadmap project on GitHub and to a donation option, which tells you the shape of the ongoing work without having to guess at it.

Editorial conclusion

vscode-sshfs fits a developer who works against a remote server and wants one editor window with a real file system provider rather than a remote development session. It does not fit a team that needs binary file handling, since the README notes that not all extensions have switched to the workspace file system API, especially those making use of binary files, and it does not fit anyone who needs the guarantees of VS Code's own remote development support. Before installing it, check the extension's version against the engine requirement of ^1.123.0, and read the binary file caveat before you commit a workflow to it.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. README
4. Releases
5. SchoofsKelvin/vscode-sshfs on GitHub