Working directly on a remote server can be tedious. Constantly running scp or rsync commands to upload your changes interrupts your workflow and slows you down. If you’re making frequent edits to files that need to run on a remote server, you need a better solution. The SFTP extension for VSCode solves this problem by automatically syncing your local files to the remote server every time you save. You edit locally with all the speed and comfort of your local environment, and your changes are instantly available on the server.
This guide shows you how to configure the SFTP extension to keep your local workspace synchronized with a remote development server.
Prerequisites
- VSCode installed on your local machine
- SSH access to your remote server
- The SFTP extension installed in VSCode (search for "SFTP" by Natizyskunk in the extensions marketplace)
Step 1: Create Your SSH Key
First, you’ll need an SSH key pair to authenticate with your remote server. From your local machine, run:
ssh-keygen
When prompted for the file location, give it a descriptive name. For example, if you’re connecting to a development server, you might use /home/username/.ssh/devserver. When prompted for a passphrase, you can leave it blank for convenience, though adding one provides additional security.
The output should look similar to this:
Generating public/private rsa key pair.
Enter file in which to save the key (/home/username/.ssh/id_rsa): /home/username/.ssh/devserver
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /home/username/.ssh/devserver
Your public key has been saved in /home/username/.ssh/devserver.pub
Now copy the public key to your remote server:
ssh-copy-id -i /home/username/.ssh/devserver [email protected]
Test the connection to verify your key is working:
ssh -i /home/username/.ssh/devserver [email protected]
If successful, you’ll be logged into the remote server without being prompted for a password.
Step 2: Create the sftp.json Configuration File
The SFTP extension uses a configuration file called sftp.json to define how and where to sync your files. This file should be placed in the .vscode directory at the root of your local workspace.
If the .vscode directory doesn’t exist yet, create it:
mkdir .vscode
Then create the sftp.json file inside that directory with the following content:
{
"name": "Development Web Server",
"host": "webserver.example.com",
"protocol": "sftp",
"port": 22,
"username": "developer",
"remotePath": "/var/www/myproject",
"privateKeyPath": "/home/username/.ssh/devserver",
"uploadOnSave": true,
"ignore": [
".vscode",
".git",
"node_modules"
]
}
Let’s break down what each setting does:
name: A descriptive label for this connection. This is especially useful if you configure multiple remote servers.
host: The hostname or IP address of your remote server.
protocol: The transfer protocol to use. Set this to sftp for secure file transfer.
port: The SSH port on your remote server. Port 22 is the standard SSH port.
username: Your username on the remote server.
remotePath: The absolute path on the remote server where your files should be synced. This should point to your project directory.
privateKeyPath: The absolute path to the private key you created in Step 1. On Linux this will be in your home directory under .ssh. On Windows, use the Windows path format like C:/Users/YourName/.ssh/devserver.
uploadOnSave: When set to true, files are automatically uploaded to the remote server whenever you save them in VSCode.
ignore: An array of files and directories that should not be synced to the remote server. Common entries include .vscode, .git, and node_modules.
Step 3: Test the Configuration
To verify everything is working correctly, open a file in your workspace and make a small change. When you save the file, VSCode should automatically upload it to the remote server.
To see what’s happening behind the scenes, open the Output panel in VSCode by clicking View → Output, then select SFTP from the dropdown menu in the output panel. When you save a file, you should see log messages similar to this:
[03-09 14:32:15] [info] [file-save] /home/username/projects/myproject/index.php
[03-09 14:32:15] [info] local ➞ remote /home/username/projects/myproject/index.php
These messages confirm that the file was successfully transferred from your local machine to the remote server.
Troubleshooting Common Issues
If the SFTP extension isn’t working as expected, check the following:
Permission denied errors: Verify that your SSH key is properly installed on the remote server using the ssh-copy-id command from Step 1.
Connection timeout: Check that your host and port settings are correct and that your remote server is reachable. You can test connectivity with ssh -i /path/to/key username@host.
Files not uploading: Ensure uploadOnSave is set to true in your sftp.json file and that the file you’re editing isn’t listed in the ignore array.
Wrong directory on remote server: Double-check that your remotePath points to the correct directory on the remote server. The path must be absolute, not relative.
Additional Commands
The SFTP extension also provides commands you can run from the VSCode command palette (Ctrl+Shift+P or Cmd+Shift+P):
- SFTP: Upload: Manually upload the current file or folder
- SFTP: Download: Download files from the remote server to your local workspace
- SFTP: Sync Local -> Remote: Upload all files in your workspace to the remote server
- SFTP: Sync Remote -> Local: Download all files from the remote server to your local workspace
With the SFTP extension configured, you can now edit your code locally and have it automatically synced to your remote server on every save. This eliminates the need to manually transfer files and makes remote development feel as responsive as working on local files.