Positron Pro Configuration

Configuration of Positron Pro sessions is handled via the /etc/rstudio/positron.conf configuration file.

The following table lists the various configuration options that can be specified:

Config Option	Description	Default Value
enabled	Enables launching of Positron Pro sessions.	0 (disabled)
exe	Path to the Positron Server executable. Default value points to the binary bundled with Workbench, and shouldn’t normally need to be changed.	/usr/lib/rstudio-server/bin/positron-server/bin/positron-server
args	Arguments to be passed to the positron 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 Positron Pro session.
session-container-images	Comma-delimited list of images that may be used for running Positron Pro sessions.
positron-session-path	Path to the Positron Pro 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/positron-session-run
session-no-profile	Enables/disables running of bash profile scripts when starting Positron Pro sessions.	0 (run profile scripts)
user-data-dir	Path for the user data directory for Positron Pro sessions.	~/.positron-server
allow-file-downloads	Enables/disables downloading files or saving files from a Positron Pro session to a local machine	1 (downloads allowed)
allow-file-uploads	Enables/disables uploading files from a local machine into a Positron Pro session	1 (uploads allowed)
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 positron.conf file might look like the following:

# /etc/rstudio/positron.conf  
exe=/usr/lib/rstudio-server/bin/positron-server/bin/positron-server  
enabled=1  
default-session-cluster=Kubernetes

SSL configuration

Many Positron Pro 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 Positron Pro sessions that have been idle after a specified time by setting session-timeout-kill-hours in positron.conf. The default is 0 (disabled), meaning that Positron Pro 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.

Positron Pro 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 Positron Pro settings
Hot exit is disabled in the user’s Positron Pro settings

For a user’s autosave and hot exiting settings, the Workbench extension in the Positron Pro 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 Positron Pro session positUser:d5de83c9ab5a75c1d12b3. Last activity seen at 2024-12-03T19:46:49Z ( 6.000000 hours ago).

Positron Pro user settings

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

# /etc/rstudio/positron.conf
exe=/usr/lib/rstudio-server/bin/positron-server/bin/positron-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 Positron Pro session is launched, Workbench automatically merges the user settings template file at /etc/rstudio/positron-user-settings.json with the user’s settings file. This file should be a valid JSON file that contains desired Positron Pro 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 positron-user-settings.json file to provide them with a simple baseline configuration.

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

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

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

Launcher configuration

When creating containerized Positron Pro 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 Positron Pro sessions, enter positron 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 Positron Pro sessions. To access other folders, create symbolic links to them within the home folder.

Container configuration

When running Positron Pro sessions in containers, such as by using the Kubernetes Job Launcher plugin, you will need to ensure that the image(s) used to launch Positron Pro 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 Positron Pro 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.