This guide explains how to install, configure, and troubleshoot VS Code Server on a remote Linux machine using Visual Studio Code Remote-SSH.

It covers:

• VS Code Server architecture and directory structure
• Prerequisites for Windows and Linux
• Automatic online installation
• Automatic installation when only Windows has internet access
• Fully offline manual installation
• Modern and legacy server installation layouts
• Offline extension installation
• Configuration and troubleshooting

The examples use Windows as the local computer and Ubuntu Linux as the remote machine, but most procedures also apply to other supported Linux distributions.

Recommendation: If your Windows computer has internet access but your remote Linux machine does not, use VS Code's built-in local download and transfer feature. Manual installation should generally be reserved for cases where automatic installation fails or neither machine has internet access.

When you connect to a Linux machine using VS Code Remote-SSH, VS Code uses a client-server architecture.

+-------------------------------------+
|       Local Computer (Windows)      |
|                                     |
|  VS Code Desktop                    |
|  Editor UI                          |
|  Remote-SSH Extension               |
+------------------+------------------+
                   |
                   |
              SSH Connection
                   |
                   |
+------------------+------------------+
|       Remote Computer (Linux)       |
|                                     |
|  VS Code Server                     |
|  Remote Extensions                  |
|  Terminal                           |
|  Compiler and Debugger              |
|  Source Code and Project Files      |
+-------------------------------------+

The local VS Code application provides the graphical interface.

The remote Linux machine runs VS Code Server, remote extensions, and development tools.

Some extensions run locally, while others run remotely.

The server is normally installed under:

~/.vscode-server/

VS Code automatically manages the server installation when connecting through Remote-SSH.

You normally do not need to start the server manually.

The installation layout depends on the VS Code version and Remote-SSH configuration.

Recent versions commonly use the following structure when the Exec Server installation flow is enabled:

~/.vscode-server/
│
├── code-<commit>
│
├── cli/
│   └── servers/
│       └── Stable-<commit>/
│           └── server/
│               ├── bin/
│               │   └── code-server
│               ├── node
│               ├── extensions/
│               └── ...
│
├── extensions/
├── data/
└── ...

The important locations are:

The exact contents may differ between releases.

Older versions and certain non-Exec Server configurations use:

~/.vscode-server/
│
├── bin/
│   └── <commit>/
│       ├── bin/
│       ├── node
│       ├── server.sh
│       └── ...
│
├── extensions/
└── data/

Important: Do not assume that extracting a server archive into bin/<commit> is correct for every VS Code version.

You must determine which installation layout your Remote-SSH extension expects.

Before installing VS Code Server, verify the following requirements.

• Visual Studio Code is installed.
• The Remote-SSH extension is installed.
• An SSH client is available.
• You know the remote Linux machine's IP address and username.

• An SSH server is installed and running.
• The SSH port is reachable from the local computer.
• The Linux user has write access to its home directory.
• The CPU architecture and system libraries are supported by the VS Code Server version.

For current Linux requirements, consult:

https://code.visualstudio.com/docs/remote/linux

Run the following commands on the remote Linux machine:

sudo apt update
sudo apt install openssh-server

Start SSH and enable it at boot:

sudo systemctl enable --now ssh

Check its status:

sudo systemctl status ssh

If UFW is enabled, allow SSH:

sudo ufw allow OpenSSH

Only permit SSH access from trusted networks.

Find the Linux machine's IP address:

hostname -I

Example output:

192.168.1.100

If the remote machine is completely offline and OpenSSH is not installed, obtain the required Ubuntu packages and dependencies from a compatible package repository or installation medium.

Open PowerShell:

ssh user@192.168.1.100

Replace:

• user with your Linux username.
• 192.168.1.100 with your Linux machine's IP address.

If the SSH connection succeeds, you can proceed.

If the ssh command is not recognized, install the Windows OpenSSH Client optional feature.

On the remote Linux machine:

uname -m

Typical results:

Check the GNU C Library version:

ldd --version

A matching CPU architecture is not sufficient by itself. The Linux distribution must also provide the system libraries required by your VS Code Server version.

VS Code Server must match the build of your local VS Code application.

On Windows, open PowerShell:

code --version

Example output:

1.96.4
<40-character-commit-id>
x64

The second line is the commit ID.

You can also find it in VS Code:

Help -> About -> Commit

Save the commit ID.

For the Linux commands in this guide, define:

COMMIT="YOUR_40_CHARACTER_COMMIT_ID"

Replace the placeholder with the actual commit.

Do not use a random GitHub commit or a commit from a different VS Code version.

Use this method when both the local computer and the remote Linux machine have internet access.

This is the simplest installation method.

Open VS Code on Windows.

Press:

Ctrl + Shift + X

Search for:

Remote - SSH

Install the Microsoft extension.

Extension identifier:

ms-vscode-remote.remote-ssh

Open the Command Palette:

Ctrl + Shift + P

Select:

Remote-SSH: Open SSH Configuration File...

Choose your Windows SSH configuration file.

Usually:

C:\Users\<WindowsUser>\.ssh\config

Add:

Host my-linux
    HostName 192.168.1.100
    User user
    Port 22

Replace the IP address and username.

Test the configuration from PowerShell:

ssh my-linux

Open the Command Palette:

Remote-SSH: Connect to Host...

Select:

my-linux

If prompted, select Linux as the remote operating system.

VS Code will:

1. Establish an SSH connection.
2. Determine the required VS Code Server version.
3. Check whether the matching server is already installed.
4. Download the server if necessary.
5. Extract and install the server.
6. Start the server.
7. Open a remote VS Code window.

After connecting, select:

File -> Open Folder

For example:

/home/user/projects/my_project

Open a terminal in VS Code:

Terminal -> New Terminal

Verify that the terminal is running on Linux:

hostname
pwd
uname -a

Your build tools and commands will now execute on the remote machine when launched through the remote environment.

This is the recommended method for a remote Linux machine without internet access when your Windows computer can download files.

You do not need to manually download and extract the server archive.

VS Code Remote-SSH can download the server on Windows and transfer it to Linux through SSH.

On Windows, open the Command Palette:

Ctrl + Shift + P

Select:

Preferences: Open User Settings (JSON)

Add:

{
    "remote.SSH.localServerDownload": "always"
}

If your settings file already contains other properties, add this setting to the existing JSON object rather than replacing the file.

The process becomes:

+--------------------------------------+
| Windows Computer                     |
|                                      |
| Internet available                   |
|                                      |
| Downloads VS Code Server package     |
+-------------------+------------------+
                    |
                    |
               SSH Transfer
                    |
                    |
+-------------------+------------------+
| Remote Linux Machine                 |
|                                      |
| No internet required for the         |
| VS Code Server download              |
|                                      |
| Receives and installs server files   |
+--------------------------------------+

Open the Command Palette:

Remote-SSH: Connect to Host...

Select your Linux host.

VS Code should download the required server package locally, transfer it to Linux, and install it.

After connecting, open a remote terminal:

ls -la ~/.vscode-server/

For a modern installation:

ls -la ~/.vscode-server/cli/servers/

You should see an installation corresponding to your local VS Code commit.

Important: The localServerDownload setting controls where VS Code downloads the server. It does not make Windows itself capable of downloading files without internet access.

Some extensions may also require separate downloads.

Use this method when:

• The remote Linux machine has no internet access.
• Automatic local download and transfer fails.
• Both Windows and Linux are offline.
• You need to transfer the installation packages using USB, SCP, or another approved method.

You will need an internet-connected computer to obtain the installation packages initially.

This guide uses the official Microsoft VS Code Stable release.

Before installing manually, determine whether your Remote-SSH extension uses the modern Exec Server flow or the legacy flow.

Common installation structure:

~/.vscode-server/
├── code-<commit>
└── cli/
    └── servers/
        └── Stable-<commit>/
            └── server/

Installation structure:

~/.vscode-server/
└── bin/
    └── <commit>/

The installation layout depends on your VS Code and Remote-SSH versions.

On Windows, open VS Code User Settings (JSON).

For the modern installation flow:

{
    "remote.SSH.useExecServer": true
}

For the legacy installation flow, where supported:

{
    "remote.SSH.useExecServer": false
}

The legacy option is a compatibility setting, not a universal solution.

To determine which flow is actually being used, open:

View -> Output -> Remote - SSH

Look for information such as:

remote.SSH.useExecServer = true

Also inspect the expected installation directory and download URL.

The Remote-SSH log is the most useful source for determining the installation layout expected by your specific version.

On Windows:

code --version

Copy the second line.

For subsequent Linux commands:

COMMIT="YOUR_40_CHARACTER_COMMIT_ID"

On Linux:

uname -m

Choose the matching server package:

The ARM 32-bit package must also be available for your particular VS Code release.

The remaining examples assume an x86-64 Linux machine.

On an internet-connected Linux machine or WSL terminal:

COMMIT="YOUR_40_CHARACTER_COMMIT_ID"

curl -fL \
  "https://update.code.visualstudio.com/commit:${COMMIT}/server-linux-x64/stable" \
  -o vscode-server-linux-x64.tar.gz

Alternatively, open the following URL in a browser, replacing the commit:

https://update.code.visualstudio.com/commit:<COMMIT>/server-linux-x64/stable

For ARM64, replace:

server-linux-x64

with:

server-linux-arm64

Verify the downloaded archive:

file vscode-server-linux-x64.tar.gz

List its contents:

tar -tzf vscode-server-linux-x64.tar.gz | head

If the archive cannot be listed, the download may have failed or returned an error page.

This section covers the modern installation layout.

Important: The exact CLI packaging and installation checks can change between Remote-SSH releases. The procedure below describes a commonly used layout. Confirm the expected package and paths in your Remote-SSH log.

Recent Exec Server installations may require a separate VS Code CLI executable.

For an x64 Linux target, a commonly used CLI package endpoint is:

https://update.code.visualstudio.com/commit:<COMMIT>/cli-alpine-x64/stable

Download it:

curl -fL \
  "https://update.code.visualstudio.com/commit:${COMMIT}/cli-alpine-x64/stable" \
  -o vscode-cli-alpine-x64.tar.gz

For ARM64, use the corresponding cli-alpine-arm64 package where available.

The alpine identifier refers to the CLI package variant. It does not mean that the remote operating system must be Alpine Linux.

Verify the archive:

tar -tzf vscode-cli-alpine-x64.tar.gz | head

If your Remote-SSH log specifies a different package, use the package expected by that version.

From an internet-connected Linux computer or WSL:

scp vscode-server-linux-x64.tar.gz \
    vscode-cli-alpine-x64.tar.gz \
    [email protected]:~/

Alternatively, from Windows PowerShell:

scp .\vscode-server-linux-x64.tar.gz `
    .\vscode-cli-alpine-x64.tar.gz `
    user@192.168.1.100:~/

If there is no network connection between the machines, transfer the files using USB or another approved method.

ssh [email protected]

Set the commit ID:

COMMIT="YOUR_40_CHARACTER_COMMIT_ID"

SERVER_DIR="$HOME/.vscode-server/cli/servers/Stable-${COMMIT}/server"

mkdir -p "$SERVER_DIR"

The resulting directory is:

/home/user/.vscode-server/cli/servers/Stable-<commit>/server/

tar -xzf "$HOME/vscode-server-linux-x64.tar.gz" \
    -C "$SERVER_DIR" \
    --strip-components=1

The --strip-components=1 option removes the first directory component from each archive entry.

This command assumes that the downloaded archive contains a single top-level directory.

Inspect the archive first if its structure differs.

Verify the server executable:

ls -l "$SERVER_DIR/bin/code-server"

Also check:

ls -l "$SERVER_DIR/node"

If these files do not exist, inspect the archive structure and your Remote-SSH log.

Do not create empty replacement files.

Inspect the CLI archive:

tar -tzf "$HOME/vscode-cli-alpine-x64.tar.gz" | head -20

For the commonly used CLI archive containing a top-level executable named code, create a temporary directory:

CLI_TMP="$(mktemp -d)"

Extract the CLI:

tar -xzf "$HOME/vscode-cli-alpine-x64.tar.gz" \
    -C "$CLI_TMP"

Verify:

ls -l "$CLI_TMP/code"

Install it:

install -m 755 "$CLI_TMP/code" \
    "$HOME/.vscode-server/code-${COMMIT}"

Remove the temporary directory:

rm -rf "$CLI_TMP"

The resulting structure should resemble:

~/.vscode-server/
│
├── code-<commit>
│
└── cli/
    └── servers/
        └── Stable-<commit>/
            └── server/
                ├── bin/
                │   └── code-server
                ├── node
                └── ...

Some Remote-SSH versions use additional installation markers or different CLI handling.

The presence of these files alone does not guarantee that every Remote-SSH release will recognize the installation.

Check the CLI executable:

test -x "$HOME/.vscode-server/code-${COMMIT}" \
    && echo "CLI executable found"

Check the server executable:

test -x "$SERVER_DIR/bin/code-server" \
    && echo "Server executable found"

Check the file types:

file "$HOME/.vscode-server/code-${COMMIT}"

file "$SERVER_DIR/bin/code-server"

For an x64 Linux target, the executable must be compatible with Linux x86-64.

These checks confirm that the files exist and are executable. They do not verify all runtime dependencies or Remote-SSH installation checks.

On Windows, open VS Code User Settings (JSON).

For the modern flow:

{
    "remote.SSH.useExecServer": true
}

Then select:

Remote-SSH: Connect to Host...

Choose the Linux machine.

If VS Code recognizes the installation, it should reuse the existing files.

If it still attempts to download files, inspect:

View -> Output -> Remote - SSH

Determine which component or path is missing.

Do not create arbitrary completion markers or empty executable files to bypass installation checks.

Use this method only when your Remote-SSH version expects the legacy installation directory:

~/.vscode-server/bin/<commit>/

On Windows, configure the legacy flow if supported:

{
    "remote.SSH.useExecServer": false
}

On the remote Linux machine, define the commit:

COMMIT="YOUR_40_CHARACTER_COMMIT_ID"

Create the installation directory:

mkdir -p "$HOME/.vscode-server/bin/${COMMIT}"

Extract the server archive:

tar -xzf "$HOME/vscode-server-linux-x64.tar.gz" \
    -C "$HOME/.vscode-server/bin/${COMMIT}" \
    --strip-components=1

Verify the directory:

ls -l "$HOME/.vscode-server/bin/${COMMIT}"

For archives containing server.sh, check:

test -f "$HOME/.vscode-server/bin/${COMMIT}/server.sh" \
    && echo "Legacy server script found"

If server.sh does not exist, inspect the archive and Remote-SSH log.

Do not create an empty server.sh file.

Reconnect from VS Code.

If the installation is not recognized, inspect the Remote-SSH output before making further changes.

On Windows, open:

Preferences: Open User Settings (JSON)

For normal use when Windows has internet but Linux does not:

{
    "remote.SSH.localServerDownload": "always",
    "remote.SSH.showLoginTerminal": true
}

Settings reference:

The localServerDownload setting does not prevent every possible download attempt. It controls where VS Code obtains server packages.

If the Linux home directory has limited disk space, you can configure a custom installation location.

Example:

{
    "remote.SSH.serverInstallPath": {
        "my-linux": "/opt/vscode-server/user"
    }
}

The host name must match the alias in your SSH configuration.

An administrator can prepare the directory:

sudo mkdir -p /opt/vscode-server/user

Set ownership:

sudo chown user:user /opt/vscode-server/user

Replace user with the actual Linux username.

Inspect the Remote-SSH log to confirm the exact subdirectories used under the custom installation path.

Installing VS Code Server does not automatically install all the extensions required for development.

For example, you may also need:

• C/C++ extension
• Python extension
• CMake Tools
• Other project-specific extensions

Extensions can be installed offline using VSIX packages.

On an internet-connected computer, open:

https://marketplace.visualstudio.com/vscode

Download the appropriate .vsix package.

For example, a platform-specific C/C++ extension package may have a filename resembling:

ms-vscode.cpptools-<version>@linux-x64.vsix

The exact filename depends on the extension version and platform.

Make sure the extension is compatible with:

• Your VS Code version
• Your remote Linux architecture
• Your remote operating system

From Windows PowerShell:

scp .\extension.vsix user@192.168.1.100:~/

Connect to the remote Linux machine using Remote-SSH.

Open the Command Palette:

Extensions: Install from VSIX...

Select the transferred package.

Make sure you install the extension in the intended remote environment.

For a compatible modern server installation, you may be able to use the remote server CLI:

COMMIT="YOUR_40_CHARACTER_COMMIT_ID"

"$HOME/.vscode-server/cli/servers/Stable-${COMMIT}/server/bin/code-server" \
    --install-extension "$HOME/extension.vsix"

The command must match the CLI available in your server version.

Some extensions require additional runtime packages or download dependencies during installation.

For a completely isolated environment, obtain those dependencies separately.

Possible causes:

• Commit ID mismatch
• Incorrect installation directory
• Missing CLI executable
• Incorrect server architecture
• Incomplete installation
• Different installation flow than expected

Check the local VS Code commit:

code --version

Inspect the remote installation:

ls -la ~/.vscode-server/

For modern installations:

ls -la ~/.vscode-server/cli/servers/

For legacy installations:

ls -la ~/.vscode-server/bin/

Open the Remote-SSH log:

View -> Output -> Remote - SSH

Find the expected installation path and compare it with the actual files.

First inspect ownership and permissions:

ls -ld ~/.vscode-server

ls -la ~/.vscode-server

Check ownership:

stat -c '%U:%G %a %n' ~/.vscode-server

If the directory was accidentally created by root and is intended to belong entirely to your current user, an administrator can correct its ownership:

sudo chown -R "$USER:$(id -gn)" "$HOME/.vscode-server"

Only use this command when the entire directory should belong to your account.

If a specific executable lacks its execute bit, correct that executable individually.

Do not use this as a general fix:

chmod -R 755 ~/.vscode-server

Recursively applying 755 can expose files to other local users and unnecessarily change permissions on data files.

Example:

Exec format error

This often indicates that the executable is incompatible with the operating system or CPU architecture.

Check the architecture:

uname -m

Inspect the executable:

file ~/.vscode-server/code-<commit>

Make sure you downloaded the correct Linux package.

For example:

server-linux-x64

is intended for Linux x86-64.

A Windows executable cannot run directly as a Linux server binary.

Also verify that the downloaded archive is valid and not an HTML error page.

Example:

GLIBC_2.xx not found

Check the installed GNU C Library version:

ldd --version

Compare the installed version against the requirements of your VS Code Server release.

Official Linux requirements:

https://code.visualstudio.com/docs/remote/linux

Possible solutions include:

• Updating to a supported Linux distribution
• Using a compatible VS Code release
• Updating the required runtime libraries through supported distribution packages

Do not replace system libraries manually without understanding the consequences.

First test SSH from Windows:

ssh my-linux

If SSH succeeds, inspect the VS Code log:

View -> Output -> Remote - SSH

Enable the login terminal:

{
    "remote.SSH.showLoginTerminal": true
}

Check:

• SSH authentication
• Remote shell startup errors
• Home directory permissions
• Server installation errors
• SSH port forwarding restrictions
• Available disk space

Do not delete the entire .vscode-server directory before identifying the actual problem.

Possible causes:

• Wrong VSIX platform
• Extension version incompatible with VS Code
• Missing extension dependencies
• Missing Linux runtime packages
• Extension attempts to download additional components

Check whether the VSIX package targets Linux.

For platform-specific extensions, a Windows package may not work on Linux.

Install the correct VSIX in the remote VS Code window.

If the extension requires additional components, obtain them separately.

The Remote-SSH log is particularly important for offline installations.

On Windows:

View -> Output -> Remote - SSH

Look for messages containing:

commitId
useExecServer
Downloading
Installing
serverInstallPath
Failed

The log may reveal:

• The expected commit ID
• The required architecture
• The server download URL
• The CLI download URL
• The expected installation directory
• Missing installation components
• Startup failures

When a manual installation is not recognized, use the log to identify the exact mismatch rather than guessing.

If the server installation is incomplete, use the VS Code Command Palette:

Remote-SSH: Kill VS Code Server on Host...

If available, you can also use:

Remote-SSH: Uninstall VS Code Server from Host...

Uninstalling the server may remove remote extensions and settings.

For manual troubleshooting, consider renaming only the affected version directory rather than deleting the entire .vscode-server directory.

This allows you to restore the previous installation if necessary.

After connecting successfully, open a terminal in the remote VS Code window.

Run:

echo "Host: $(hostname)"
echo "User: $(whoami)"
echo "Architecture: $(uname -m)"
echo "Home: $HOME"

Check the server processes:

ps -ef | grep '[v]scode-server'

Process names may differ depending on the installation version.

Find the server executable:

find "$HOME/.vscode-server" \
    -maxdepth 6 \
    -name code-server \
    -type f

For a C++ development environment, verify your tools:

g++ --version

cmake --version

git --version

Open a remote project and try building it.

If the project builds successfully in the remote terminal, your Linux development environment is accessible through VS Code.

For most restricted Linux systems, start with:

{
    "remote.SSH.localServerDownload": "always"
}

Then connect normally.

Manual installation is more sensitive to VS Code version changes and should be used only when necessary.

The following resources provide current installation instructions and compatibility information.

https://code.visualstudio.com/docs/remote/ssh

Official documentation for connecting to remote machines using SSH.

https://code.visualstudio.com/docs/remote/faq

Information about remote development, downloads, extensions, and offline environments.

https://code.visualstudio.com/docs/remote/troubleshooting

Troubleshooting procedures for SSH connections and server installation.

https://code.visualstudio.com/docs/remote/linux

Linux compatibility requirements and supported environments.

https://github.com/microsoft/vscode-remote-release/issues

Version-specific installation problems, bug reports, and discussions.

For a Windows computer connected to an offline Ubuntu server over SSH:

1. Install OpenSSH Server on Ubuntu.
2. Verify SSH connectivity from Windows.
3. Install the Remote-SSH extension in VS Code.
4. Set remote.SSH.localServerDownload to always.
5. Connect normally and allow VS Code to transfer and install the server.
6. If installation fails, inspect the Remote-SSH log.
7. Use manual installation only after identifying the required commit, architecture, installation layout, and CLI components.

Important: The VS Code Server installation layout and package requirements may change between releases. Always use the Remote-SSH log and official documentation to verify the requirements of your installed version.