Posit Workbench Code Server


PWB Code Server

Preview feature

This feature is in preview. Preview features are unsupported and may face breaking changes in a future release. Any issues found in the feature will be addressed during the regular release schedule; they will not result in immediate patches or hotfixes.

We encourage customers to try these features and we welcome any feedback via Posit Support, but we recommend that the feature not be used in production until it is in general availability (i.e., officially released as a full feature). To provide feedback, please email your Posit Customer Success representative or and specify that you are trialing this feature.

By default, VS Code sessions use an open-source project called code-server to run in Posit Workbench. Starting in Workbench version 2024.04, Posit provides Posit Workbench Code Server (PWB Code Server), which is built directly off a fork of Microsoft’s Visual Studio Code - Open Source repository.


Before configuring PWB Code Server, consider if and how you plan to migrate content between code servers.

Migrating code server arguments

The default setting in vscode.conf of args=--host= is the same for both code servers. If you haven’t modified this value, then this section can be skipped.

If you have configured custom value(s) in the args option, it is possible PWB Code Server does not support them. If this is the case, in most scenarios, users can still launch VS Code sessions, but a warning will be logged to the session’s Details page in the following format:

Ignoring option 'option-name': not supported for the server.

If you have configured a global extensions directory by including --extensions-dir= in args, PWB Code Server uses the same directory for extensions, and they do not need to be reinstalled. If you configure PWB Code Server to use a different directory, either copy the code-server directory to this new directory or follow the process described in Installing extensions.

Migrating user data

Both code servers store data in a dedicated directory within each user’s home directory. This data includes state, logs, user settings, and extensions the user has installed themselves.

If you have not specified a user-data-dir option in vscode.conf, PWB Code Server uses a different directory than code-server, and users need to reinstall any extensions they have installed themselves and reconfigure their environments. Using separate directories prevents either code server from reading, modifying, or removing data from the other code server. By default, PWB Code Server uses ~/.vscode-server. The default code server uses ~/.local/share/code-server.

If users can install their own extensions, and you do not migrate user extensions, the Posit Workbench extension and all extensions configured in vscode.extensions.conf are installed on the user’s first session launch.

To preserve user’s settings and extensions, you can instruct them to copy their current data directory to PWB Code Server’s data directory. This will duplicate the content but may be desirable while this feature is in preview and during your own testing of PWB Code Server. Alternatively, you can configure PWB Code Server to use the same directory by setting user-data-dir=~/.local/share/code-server.

When user-data-dir is set, PWB Code Server creates the user directory at this location. If you had set this value in your code-server configuration, consider setting a different directory for PWB Code Server.


Installing PWB Code Server

Backup your configuration files

The commands in this section can overwrite your vscode.conf and vscode-user-settings.json files. It is recommended to backup these files before continuing in case you need to revert the changes made.

To start using PWB Code Server run the following command. This will download the PWB Code Server tarball and extract it to PWB’s install directory. Optionally, it can also regenerate vscode.conf and vscode-user-settings.json for you:

$ sudo rstudio-server configure-vs-code --pwb-code-server

If you opted to not have the command above regenerate vscode.conf, now you’ll need to manually edit the exe option in vscode.conf to point to PWB Code Server:

# /etc/rstudio/vscode.conf

If you have generated a new vscode.conf file, review the contents now and make any desired changes considering the Migration content.

Finally, restart Workbench for the changes to take effect:

$ sudo rstudio-server restart

Installing extensions

If you have configured a new global extensions directory or are using user extension directories and did not migrate extensions, after configuring PWB Code Server in vscode.conf, follow the Posit Workbench Extension installation instructions.

The instructions for Pre-installing extensions apply as well, but when using a global extensions directory, be sure to use the binary under pwb-code-server to run the commands with the PWB Code Server binary directly. For example:

$ export PWB_CODE_SERVER=/usr/lib/rstudio-server/bin/pwb-code-server/bin/code-server
$ $PWB_CODE_SERVER --extensions-dir=/opt/code-server/extensions --install-extension <your-extension-here>

Reverting back to the default code-server

If you’d like to go back to using the default code-server, simply edit the vscode.conf exe parameter to its default value:

# /etc/rstudio/vscode.conf

Or, you can rerun configure-vs-code command without the --pwb-code-server option and select (y) to have vscode.conf reset to the default values with code-server set as the default. Any custom changes you’ve made to vscode.conf are overwritten.

$ sudo rstudio-server configure-vs-code
Back to top