Utilizing the Workbench Job Launcher

The Workbench Jobs pane

Navigate to the Posit Workbench Extension tab in the left sidebar to view the Workbench Jobs pane, which provides controls for starting new jobs as well as a list for viewing the status of existing jobs.

VS Code Workbench extension highlighting the Workbench Jobs pane

Start a Workbench Job

Click on the ‘+’ icon in the top right of the Workbench Jobs pane to open the Launcher options for a new job. This dialog is similar to the one in RStudio Pro. To enable the launch button, the job name must be specified, and the script extension must either be .r or .py.

Workbench extension launcher dialog in its default configuration

If you have been previously working on an R or Python script file, the launcher will automatically start with this script specified as the Script parameter. If you have opened a directory in VS Code, the Working Directory parameter will also be set; otherwise, it will default to your home directory. You can click on the Script and Working Directory fields to browse the file system and change them from their default values.

Depending on your last actions in VS Code, or if there is no active script file, the launcher dialog will appear without the Script and Working Directory set by default. Use the browse functionality to specify the desired paths in this case, and the dialog will present more script options once you have selected a script with a supported extension.

Version and Arguments

The Version and Arguments parameters are preconfigured based on the type of script selected. (System Default) is a safe option for running jobs in clusters like Kubernetes, which may not include the R Versions presented in the drop-down. The version information is pulled from the local server, and not from the Kubernetes image, so it is possible there could be a version mismatch. A reminder is displayed if you select a non-local cluster and specify a version other than (System Default).

(System Default) calls R or Python3 directly, and assumes that they are specified on the PATH variable. Local Version information is read from the r-versions and py-versions files, which are typically located at /var/lib/rstudio-server/r-versions and /var/lib/rstudio-server/py-versions respectively. The path to the r-versions file can be adjusted in rserver.conf.

The user can also specify a custom path by selecting the Other… option and browsing for it, or by typing a custom path directly into the text field.

Select custom version path, and showing reminder about version on cluster

If you want more control over the arguments, you can choose to modify them. When a script is first selected, the arguments are displayed as they would be passed. In order to make changes, you must click Modify next to the argument preview.

Modify arguments of the script before launch

You can type argument flags or values into the existing fields to make changes, remove individual arguments by clicking the ‘X’ buttons next to each one, add new arguments by clicking + Add argument, or reset them to their provided defaults by clicking Reset. Any changes, deletions, or additions made to these fields are previewed in the preview line above.

Viewing and Managing Jobs

Once a job has been submitted, it will appear in the Workbench Jobs pane and update automatically. This list mirrors the list displayed on the homepage.

View and manage the job statuses and stream their output to VS Code

The drop-down arrow next to each job shows additional details about the job, and in the event of a failure, what the non-zero exit code was.

The “Notepad” icon on the right, adjacent to the ‘X’ icon, opens that job’s output stream and views it in the VS Code Output pane. The Output pane should be automatically opened, but if not, then you can display it with View > Output.

The ‘X’ icon on the far right allows you to stop a running job. Additional confirmation is required for this operation.