Session Management

This page covers the basics of using the Posit Workbench home page to work in a multi-session environment.

The home page

After logging in, the Posit Workbench home page contains two sections (tabs) for project, session, and job management:

• Projects tab contains a table of projects and their sessions.
• Jobs tab contains a table of Workbench Jobs and Audited Workbench Jobs.
• User menu dropdown to open user-level settings or sign-out.

Projects

The Workbench home page

To help track your running sessions, the home page allows users to:

• Launch new standalone sessions or in projects.
• Group sessions by project for easy organization.
• View the session state of all running sessions:
  • active, idle, suspended, pending, or shut down
• Sort the table by column (for example, by last used).
• Toggle the visibility of columns.
• Gracefully or forcefully exit a running session.

Workbench Jobs

You can also monitor the status of running and completed Workbench Jobs on the Workbench home page.

The Workbench Jobs Tab

What are sessions?

Unlike many web applications, Workbench sessions continue to run on the server even after you close your browser window.

This means that you can kick off a long-running job in one session and switch to another to continue working.

Session states

Sessions may be in one of the following states:

Active:

• The session is running with recent user interaction or processing.

Idle:

• The session is running with no recent user interaction or processing.

Suspended: Only applicable to RStudio Pro sessions¹

• The session is not currently running as it has been suspended.
• Session information is saved for future restoration.
• The session is restored when selected from the home page with all active work preserved.

Pending:

• The session is in the process of being made available to the user.

Shutting Down:

• The session has been exited.
• Any unsaved work is lost.
• This is done through quitting or force quitting the session.

Session state behavior explained

When RStudio Pro, Positron Pro, or VS Code sessions have been idle (no processing or user interaction) for a specified period, they are killed (Positron Pro/VS Code) or suspended (RStudio Pro) to free up server resources.

Type	Timeout and Kill	Suspend
RStudio Pro	✅	✅
Positron Pro	✅	❌
VS Code	✅	❌
JupyterLab	❌	❌

Note

Currently, only sessions using RStudio Pro have the capability to be suspended and later restored.

Managing sessions

Starting new sessions

To start a new session, from the Projects section click + New Session.

Creating a new session in Workbench

When creating a new session, you can choose from the different editor options that have been configured by your administrator, including Positron Pro, RStudio Pro, VS Code, and JupyterLab.

Editor options

Additional settings may appear in the New Session dialog based on your Workbench deployment’s configuration.

Cluster Options

Cluster Options in the New Session dialog

Workbench can be configured to launch jobs into IT-managed computing resources. If enabled by your server administrator, you may be provided with options to limit your session’s resource usage or to select which resources you wish to use.

You may be able to select a Resource Profile. The profile you select automatically populates the other resource options. If your administrator has enabled Custom resource profiles, then you can manually set the resource options.

Depending on the Workbench configuration, the following resource options may be available:

• CPUs: The maximum number of CPUs that may be used by your session.
• Memory (GB): The maximum amount of memory (RAM) that will be made available to your session. You should select a memory limit of at least 4 GB when starting a VS Code or Positron Pro session.
• Queue: The Slurm queue (partition) to use for the job.
• Image: The container image to use for the job.

Additional options may also be available. Consult your server administrator for more information.

Opening existing sessions

Open an existing session by clicking the session name.

Opening an existing session in Workbench

Opening sessions in projects

You can open an existing project in a new session from the Projects tab by either:

• Clicking Create new session on a project row.

  

  Opening a new session in an empty project

• Selecting the row of an existing project and then clicking New Session.

  

  Opening a new session in a project with existing sessions

A New Project Session dialog displays to create a session. The project is already loaded for you using your preferred editor.

Opening a project in Workbench

One session per project

It is best practice to have only one active session per project. While it is possible to have multiple sessions for a single project, it is not recommended.

Automatic editor selection

When opening a project listed in the Projects table, Workbench attempts to match with the appropriate editor based on the project type. R Projects prompt with the RStudio IDE as the preferred editor and Positron or VS Code for others.

Quitting sessions

Closing a browser window does not quit a session. Therefore, it is a good practice to routinely go through and clean up the sessions you aren’t using. This frees compute resources back to the server to be available for other users.

Warning

When quitting a session, all unsaved work is lost. Be sure to save work to your version control system of choice, or locally, before quitting.

To quit a single session:

1. Select the row of the session that you wish to quit.
2. Click the Quit button.

Quitting sessions in Workbench

In some rare cases, it might be necessary to force quit sessions. Typically, this is done when a session is not responding to inputs and may be part of a larger troubleshooting effort.

To forcefully quit your session:

1. Click the Details button located to the right of the session you wish to force quit.
2. In the Session section, scroll down until the Force Quit button displays.
3. Click Force Quit.

Forcefully quitting sessions in Workbench

This forcefully stops your process and all of its descendant processes. Force quitting doesn’t allow them to attempt to gracefully quit on their own. Consider using this option only as a last resort.

Note

Automatic cleanup of forgotten, long-running jobs is an optional setting, disabled by default, that may be configured by your server administrator. It is used to automatically reclaim temporary disk space used by a long-running session without user input regardless of computation status and to stop its processes and children.

If you are encountering unexpected session behavior that you suspect is due to this setting, refer your Workbench administrator to the Session Timeout Kill section of the Admin Guide.

Column sorting

By default, the projects and sessions table is sorted by the last used date. You can customize the sort of any column by clicking the column header. An arrow pointing up or down indicates if the column is ascending or descending, respectively.

Column sorting controls in Workbench

Column visibility

The projects and sessions table can be customized to show or hide columns. To toggle column visibility, click the gear icon located in the first column of the table. The following columns are available:

• Path
• Last Used
• Created
• Runtime
• Status
• Owner
• Host
• Cluster
• Job ID
• Queue
• Image
• AWS Role
• Databricks Instance
• Snowflake Role

Column visibility controls in Workbench

User-level settings

User-level settings can be found by accessing the dropdown menu in the top-right of the screen.

General settings

• Enable session notifications
• Toggle auto-join session behavior
• Change themes
• Switch to legacy homepage
• Sign out

Managed Credentials

The Managed Credentials settings page provides additional authentication and provider-specific controls not found in the New Session dialog.

Troubleshooting

Find session diagnostics for active sessions

To find the diagnostics for an active session:

1. Navigate to the Workbench home page.

2. Locate the session that you wish to view diagnostics for and click Details.

   

   Getting session’s info

3. From the RStudio Pro Session window, select the Launcher Diagnostics tab.

   

   Getting session’s launcher diagnostics

4. Under the Running status icon, click Details.

   

   Getting session’s details

The session diagnostics page includes additional information such as resource usage and job output:

Example diagnostics

Footnotes

1. Currently, only sessions using RStudio Pro have the capability to be suspended and later restored. Other session types won’t switch to the Suspended state and there is no Suspend control option.