Configuration

Workbench

VS Code configuration

Configuration of VS Code sessions is handled via the config file /etc/rstudio/vscode.conf. The following table lists the various configuration options that are available to be specified in the vscode.conf configuration file:

/etc/rstudio/vscode.conf

Config Option Description Default Value
enabled Enables launching of VS Code sessions. 0 (disabled)
exe Path to the PWB Code Server executable. Default value points to the binary bundled with Workbench, and shouldn’t normally need to be changed. /usr/lib/rstudio-server/bin/pwb-code-server/bin/code-server
args Arguments to be passed to the code server launch command. You can supply an --extensions-dir= to point to previously installed extensions via this parameter. If no --host argument is supplied, a default of --host=0.0.0.0 will be assumed. --host=0.0.0.0
default-session-container-image The default container image to use when launching a containerized VS Code session.
session-container-images Comma-delimited list of images that may be used for running VS Code sessions.
vscode-session-path Path to the VS Code Session launcher executable/script. It is recommended that you do not change this unless you know what you’re doing, and you need to point to a different script. /usr/lib/rstudio-server/bin/vscode-session-run
session-no-profile Enables/disables running of bash profile scripts when starting VS Code sessions. 0 (run profile scripts)
user-data-dir Path for the user data directory for VS Code sessions. ~/.vscode-server
allow-file-downloads Enables/disables downloading files or saving files from a VS Code session to a local machine 1 (downloads allowed)
allow-file-uploads Enables/disables uploading files from a local machine into a VS Code session 1 (uploads allowed)
session-clusters Deprecated in favor of launcher-sessions-clusters. Comma-delimited list of available Job Launcher clusters for launching VS Code sessions. launcher-sessions-clusters in rserver.conf
default-session-cluster Deprecated in favor of launcher-default-cluster. The default Job Launcher cluster to use when launching a VS Code session. launcher-default-cluster in rserver.conf
session-timeout-kill-hours Specifies the amount of hours to wait before forcefully killing a running session after it has been idle. 0 (disabled)

For example, your vscode.conf file might look like the following:

# /etc/rstudio/vscode.conf
exe=/usr/lib/rstudio-server/bin/pwb-code-server/bin/code-server
enabled=1
default-session-cluster=Kubernetes
default-session-container-image=rstudio:vscode-session

SSL configuration

Many VS Code features, including displaying web views, require enabling HTTPS using a trusted certificate. When HTTPS is not enabled or the user’s browser does not trust the certificate used, sessions display a warning dialog informing users that they are using an insecure context and that some functionality will not work as expected. See the SSL configuration documentation for instructions on enabling SSL.

Idle session timeout

You can configure Workbench to terminate VS Code sessions that have been idle after a specified time by setting session-timeout-kill-hours in vscode.conf. The default is 0 (disabled), meaning that VS Code sessions remain active until the user manually stops them. The minimum recommended setting is two hours, but longer timeouts give users a better experience. Decimal values are accepted, meaning a value of 4.5 would set the timeout to 4 hours and 30 minutes.

VS Code sessions don’t suspend like RStudio Pro sessions, so there is the potential for users to lose work if:

  • session-timeout-kill-hours is too short (minimum recommended setting is two hours)
  • Autosave is disabled in the user’s VS Code settings
  • Hot exit is disabled in the user’s VS Code settings

For a user’s autosave and hot exiting settings, the Workbench extension in the VS Code session automatically warns users if these settings are configured in a manner that could lead to data loss.

To track idle sessions that Workbench terminates, an INFO level log is generated for each terminated session. For example:

INFO Terminating VS Code session positUser:d5de83c9ab5a75c1d12b3. Last activity seen at 2024-12-03T19:46:49Z ( 6.000000 hours ago).

VS Code user settings

VS Code sessions write user settings to ~/.vscode-server/. To modify this, add the user-data-dir path argument to the VS Code options, like so:

# /etc/rstudio/vscode.conf
exe=/usr/lib/rstudio-server/bin/pwb-code-server/bin/code-server
args=--host=0.0.0.0
user-data-dir=<desired/user/path>

A ~ can be used to represent the user’s home directory for the desired user-data-dir path.

Whenever a VS Code session is launched, Workbench automatically merges the user settings template file at /etc/rstudio/vscode-user-settings.json with the user’s settings file. This file should be a valid JSON file that contains desired VS Code user settings. Any matching settings that already exist in the user settings file are not overridden, allowing users the freedom to customize their environment. You should use the vscode-user-settings.json file to provide them with a simple baseline configuration.

A simple template is automatically created for you. It instructs VS Code to use the bash shell by default and to disable automatic extension updates. The generated /etc/rstudio/vscode-user-settings.json file looks like the following:

/etc/rstudio/vscode-user-settings.json

{
      "terminal.integrated.defaultProfile.linux": "bash",
      "extensions.autoUpdate": false,
      "extensions.autoCheckUpdates": false
}

Launcher configuration

When creating containerized VS Code sessions via the Job Launcher, you need to specify mount points as appropriate to mount the users’ home drives and any other desired paths. For sessions to run properly within containers, it is required to mount the home directories into the containers.

To configure mount entries that should only be mounted for VS Code sessions, enter vs code as the workbench mount type in the Workbench field.

For more information, see Launcher mounts documentation.

Note

Only a user’s home folder is visible within VS Code sessions. To access other folders, create symbolic links to them within the home folder.

Container configuration

When running VS Code sessions in containers, such as by using the Kubernetes Job Launcher plugin, you will need to ensure that the image(s) used to launch VS Code sessions have the Posit Workbench session binaries available at runtime.

For containers within Kubernetes, we recommend using the rstudio/workbench-session Docker image as a base for any VS Code session images you create. This image is available on Docker Hub.

When using the rstudio/workbench-session image on Kubernetes, the session init container should be enabled to ensure that Workbench session components are copied to the session container at runtime:

/etc/rstudio/rserver.conf
launcher-sessions-auto-update=1

See the Session init container section for more information.

When using a container-based job system other than Kubeneretes, we recommend using the rstudio/r-session-complete Docker image. This image includes the Workbench session components in the image directly. This image is available on Docker Hub.

Back to top