Session Hooks

This documentation is applicable to all session types (Jupyter, Positron Pro, RStudio Pro, and VS Code sessions).

Workbench

Session hooks provide you with the ability to inject custom behavior at different points in a sessions lifecycle. Define the custom behavior in a shell script and source this file at the appropriate time in a sessions lifecycle.

The following server settings control session hook behavior:

For more information, see these settings in the rserver.conf reference documentation.

The shell scripts themselves must be executable at session-hooks-path for both Workbench and the session. If provided, the shell script must run successfully for the session to start/stop.

Example configuration

Assuming that there are two shell scripts (start.sh and stop.sh) stored at /tmp/mysessionhooks, a valid rserver.conf configuration to enable these scripts globally is:

/etc/rstudio/rserver.conf
session-hooks-enabled=1
session-hooks-path=/tmp/mysessionhooks
session-hooks-start=start.sh
session-hooks-stop=stop.sh

Using the Workbench API, you can trigger more nuanced behavior, and trigger a session hook only for the session created via a particular API call (assuming the same two scripts at the same location this configuration would make them available):

/etc/rstudio/rserver.conf
session-hooks-enabled=1
session-hooks-path=/tmp/mysessionhooks

Then using the Workbench API a launch session call could trigger start.sh for the launched sessions:

{
  "method": "launch_session",
  "kwparams": {
    "workbench": "RStudio",
      "name": "My RStudio Session",
      "start_hooks": [
         {"exe": "start.sh"}
      ],
      ... other contents ...
  }
}

Combining the two approaches or using multiple scripts, works as you expect. Assuming we added a third script other-start.sh to /tmp/mysessionhooks, we could trigger start.sh and stop.sh all the time but only other-start.sh by API call:

/etc/rstudio/rserver.conf
session-hooks-enabled=1
session-hooks-path=/tmp/mysessionhooks
session-hooks-start=start.sh
session-hooks-stop=stop.sh
{
  "method": "launch_session",
  "kwparams": {
    "workbench": "RStudio",
      "name": "My RStudio Session",
      "start_hooks": [
         {"exe": "other-start.sh"}
      ],
      ... other contents ...
  }
}
Back to top