How to use VSCode to remotely edit website files
Remote development in Visual Studio Code has become a standard workflow for managing client environments without physically accessing a server's terminal. However, getting the remote extension to initialize correctly often trips up developers who are unfamiliar with the specific SSH configuration requirements. A common stumbling block involves the .remote file; placing it in /home is not a universal solution because the location of that file depends entirely on your SSH key setup and how the VSCode Remote-SSH extension discovers the connection profile.
When attempting to connect to a web server for CSS tweaks or PHP development, the first step is ensuring the SSH host is properly configured. Simply placing a configuration file in /home often fails because the Remote-SSH extension does not scan that directory by default to look for user profiles. Instead, VSCode expects SSH agent forwarding and specific identity files to be present in the standard locations or explicitly defined within the .ssh/config file on your local machine.
To establish a functional remote connection, you must configure your local SSH client first. Open your ~/.ssh/config file and add an entry for your server. This is more robust than relying solely on extension-specific files because it leverages the core SSH library that VSCode wraps around.
Host production-server
HostName 192.168.1.50
User admin
Port 22
IdentityFile ~/.ssh/id_rsa_client_key
IdentitiesOnly yes
ServerAliveInterval 60
ServerAliveCountMax 3
The IdentitiesOnly flag is critical here. It prevents VSCode from attempting to use other keys in your agent or default locations, which often leads to "authentication failed" errors when the correct key isn't automatically selected. Without this flag, SSH might try multiple keys until one matches, potentially timing out if the server has strict access controls.
Once the local configuration is verified, you can proceed with the VSCode Remote-SSH setup. The extension does not require a .remote file in /home to function; instead, it looks for connection profiles defined in your SSH config or via the "Remote-SSH: Add New SSH Host" command. When you run this command and enter your server details, VSCode generates a ssh-server.config.json file in its settings folder. This JSON block defines the remote environment variables, such as remoteEnv, which allows you to inject specific PHP versions or database paths into the server session without modifying the server's files directly.
"remoteEnv": {
"APP_ENV": "production",
"DB_CONNECTION": "mysql"
}
This approach is particularly useful when switching between client environments. You avoid the clutter of managing separate .remote files for every project because the environment variables are scoped to the connection profile, not the working directory on the server.
If you find that the remote extension still fails to pick up your configuration, check the SSH agent status. Run ssh-add -l in your local terminal to ensure the private key corresponding to your server entry is loaded into the agent. If the key file path in your SSH config points to a location where the private key is not accessible (e.g., due to missing read permissions), the connection will fail regardless of the .remote file placement.
For PHP development specifically, ensure that the php.ini configuration on the remote server is compatible with your local tooling. VSCode's integrated terminal and debugger use the PHP interpreter found in the server's PATH. If you are editing files in /var/www/html, verify that the user running the Apache or Nginx service can read those files, as permission errors here will cause syntax highlighting and linting to break inside VSCode.
When dealing with client servers, security is paramount. Avoid hardcoding credentials in your local SSH config if possible; instead, use passphrases on your private keys and ensure that StrictHostKeyChecking is set appropriately to prevent man-in-the-middle attacks during initial connections.
