Upgrading Posit Assistant for RStudio Pro

Workbench | Preview

WarningPreview feature

This feature is in preview. Preview features are unsupported and may face breaking changes in a future release. Any issues found in the feature will be addressed during the regular release schedule; they will not result in immediate patches or hotfixes.

We encourage customers to try these features and we welcome any feedback via Posit Support, but we recommend that the feature not be used in production until it is in general availability (i.e., officially released as a full feature). To provide feedback, please email your Posit Customer Success representative or and specify that you are trialing this feature.

Overview

Note

This page applies to RStudio Pro sessions only. The upgrade posit-assistant commands do not change Posit Assistant in Positron Pro sessions.

Posit Workbench bundles a copy of Posit Assistant for RStudio Pro sessions. The rstudio-server upgrade posit-assistant command installs other Posit Assistant versions beside it and chooses which one new sessions run, independently of Workbench package upgrades. This is useful for deploying a new Posit Assistant release, or for rolling back to an earlier one, without upgrading Workbench.

Installation layout

The bundled copy and the versions you install share the /usr/lib/rstudio-server/bin/posit-assistant/ directory:

  • /usr/lib/rstudio-server/bin/posit-assistant/
    • dist/ - Copy shipped with Workbench
    • package.json
    • protocol.json
    • versions/
      • 1.5.0/ - Installed via CLI
      • 1.5.0-2/ - A fresh reinstall of 1.5.0
    • selected.json - The version to run for each protocol

Each directory under versions/ holds one extracted Posit Assistant package. selected.json records the version selected for each Posit Assistant protocol, for example {"selected":{"11.0":"1.5.0"}}. The Workbench package owns only the bundled copy’s files, so package upgrades leave versions/ and selected.json in place.

Version selection

When an RStudio Pro session starts, it runs the newest compatible copy among:

  • the version selected in selected.json, if it names a valid version for the session’s protocol. Other versions under versions/ are not considered;
  • the copy bundled with Workbench;
  • the user’s own copy, when users can install their own.

A copy built for the session’s protocol wins over one that is not, and then the newer version wins. On a tie, the user’s copy wins, then the administrator-installed version, then the bundled copy.

As a result:

  • A selected version older than the bundled copy does not run. The upgrade command warns when this happens.
  • A user who installs a newer version than yours runs their own copy. To make your selection binding, set assistant-installation-enabled to 0.
  • Running RStudio Pro sessions keep the copy they started with. New sessions pick up a new selection without a Workbench restart.

Install the current version

To install the version Posit currently offers for your Workbench release:

sudo rstudio-server upgrade posit-assistant

The command shows the bundled version, the selected version, and the version Posit offers, and asks for confirmation. It downloads the package, verifies its SHA256 checksum, installs it under versions/, and selects it for new sessions.

If the install changes the version new sessions use, the command prints the select command that switches back: to the installed version sessions used before, or, if they used the bundled copy, to the bundled copy.

Install a specific version

To see every published version for your Workbench release, newest first:

rstudio-server upgrade posit-assistant list-available

To install one of them:

sudo rstudio-server upgrade posit-assistant --version <version>

The published versions for each protocol, with their download URLs and SHA256 checksums, are also listed in https://cdn.posit.co/posit-ai/release-history.json.

A version published for a newer protocol than your Workbench release can be installed ahead of a Workbench upgrade. The command selects it for that protocol and notes that the current release will not use it.

Install from a local package

In air-gapped or restricted networks, download the package on a machine with internet access. Take the url and sha256 of the version you want from https://cdn.posit.co/posit-ai/release-history.json, download the file from the url, and transfer it to the server. Then install it:

sudo rstudio-server upgrade posit-assistant \
  --file /path/to/assistant-rstudio-<version>.zip \
  --sha256 <sha256>

--sha256 is optional but recommended. The package must be the zip as published, not re-packed into a wrapping directory.

Select a version or roll back

To select a version that is already installed, without downloading anything:

sudo rstudio-server upgrade posit-assistant select <slot>

<slot> is a directory name under versions/, as shown by list. As described in version selection, a selection older than the bundled copy does not run.

Return to the bundled version

To stop selecting an installed version, so that new sessions run the copy bundled with Workbench:

sudo rstudio-server upgrade posit-assistant select --bundled

This removes the selection for the bundled copy’s protocol from selected.json and leaves the selections for other protocols, such as a version installed ahead of a Workbench upgrade, in place. A user’s own copy that is as new or newer still runs instead of the bundled copy. The installed versions stay under versions/ until you remove them with cleanup.

List and clean up versions

To list the bundled copy, the installed versions, and the selection:

rstudio-server upgrade posit-assistant list

To remove installed versions that new sessions do not use:

sudo rstudio-server upgrade posit-assistant cleanup

cleanup keeps every selected version and never touches the bundled copy. It lists the versions it will remove and asks for confirmation. Use --keep <slot> to keep one more version, --dry-run to see the list without removing anything, and --yes to skip the prompt.

Warning

Running sessions keep the version they started with. Remove a version only once no running session uses it.

Reinstalling a version

Installing a version that is already installed reuses the existing directory and selects it. To install a fresh copy instead, for example if the existing directory was modified, add --force:

sudo rstudio-server upgrade posit-assistant --version <version> --force

The fresh copy is installed as <version>-2 (or the next free number) and selected. The earlier copy stays until you remove it with cleanup.

Run one command at a time

Warning

Do not run upgrade posit-assistant commands that change the installation (installing, select, or cleanup) at the same time against the same directory. The commands do not lock the directory, so two concurrent runs can lose one of the selections or install over each other. Run them one after another.

Load-balanced deployments

Each node reads its own /usr/lib/rstudio-server/bin/posit-assistant/ directory. Run the same commands on every node in the cluster so that sessions see the same version whichever node runs them.

Slurm deployments

Sessions launched on Slurm compute nodes read the compute node’s own installation directory. Install and select the same version on the Workbench node and on every compute node that runs sessions. Compute nodes install only the Workbench session components, so invoke the upgrade CLI directly there:

sudo /usr/lib/rstudio-server/bin/upgrade-cli posit-assistant --version <version>

Shared storage

versions/ can be a mount point or a symlink, for example to serve the same versions to several nodes from NFS. Each version directory inside it must be a real directory: sessions skip a version directory that is a symlink.

Each node keeps its own selected.json. Install the version on one node, which writes it into the shared versions/, then select it on each of the other nodes without downloading it again:

sudo rstudio-server upgrade posit-assistant select <slot>

On Slurm compute nodes, which do not have the rstudio-server command, invoke the upgrade CLI directly:

sudo /usr/lib/rstudio-server/bin/upgrade-cli posit-assistant select <slot>

select does not write to versions/, so it also works where the other nodes mount it read-only.

Kubernetes deployments

The upgrade command is not supported in Kubernetes deployments. Session pods receive their Workbench session components, including the bundled Posit Assistant, from the session init container, so versions installed on the Workbench host are not visible to them.

Troubleshooting

Permission errors

The command must run as root or as the Workbench service account (server-user), which must be able to write to /usr/lib/rstudio-server/bin/posit-assistant/. list and list-available only read, and do not need sudo.

Sessions run as ordinary users, so versions/, each version directory under it, and the files in them must be readable by all users. Installing or selecting a version warns when the installation directory, versions/, that version’s directory, or a file sessions read in it is not.

A malformed selected.json

If selected.json is not of the form {"selected":{...}}, sessions ignore it and run the bundled copy (or a user’s own copy, if it is as new or newer). The commands that change the selection refuse to overwrite it. Fix or delete the file, then retry.

Download failures

  • Verify that the server can reach cdn.posit.co.
  • If your environment requires an outbound proxy, set HTTPS_PROXY (and NO_PROXY as needed) for the command. sudo might drop these variables; pass them with sudo --preserve-env=HTTPS_PROXY,NO_PROXY.
  • Use --file to install from a package downloaded elsewhere.
Back to top