Remote SSH

Positron has experimental support for Remote SSH sessions. This feature allows the Positron IDE’s front end (user interface) to run on one machine, while the back end (files, projects, Python and R sessions, etc.) runs on another machine. The two machines communicate using an ordinary secure shell (SSH) connection.

flowchart LR
subgraph "Local Machine"
p[Positron UI]
end
subgraph "Remote Machine"
p -- SSH --> r[Positron Backend]
r --> py[Python Session]
r --> ark[R Session]
end

System requirements

Remote SSH sessions can be initiated from any operating system supported by Positron itself, including macOS, Linux, and Windows. However, the system you are connecting to must be running Linux using a recent distribution, such as Ubuntu 22+ or RedHat 9+, on an x86-compatible processor. Older Linux distributions and arm64 hosts aren’t currently supported.

Other features that aren’t currently supported include:

  • Connecting to Windows Subsystem for Linux (WSL) backends1
  • Dev Container workflows (note however that you can start a container yourself and connect to it)

Creating a connection

To create a connection, open the Command Palette (Cmd/Ctrl+Shift+P) and type “Remote Menu”. Run the Remote SSH: Show Remote Menu command.

The Remote SSH menu

From there, run the Connect to Host command. You will be prompted to enter the hostname and your credentials.

If you want to avoid having to type the hostname every time, add the connection information to your user SSH config (e.g. ~/.ssh/config on Unix-alikes). Then you can use the Remote Explorer view to connect to the system again in the future. Use the View: Show Remote Explorer command to open it.

Remote sessions

You can identify remote SSH sessions via a small indicator in the bottom left of Positron’s window.

Remote SSH Status Indicator

There are some notable differences between these sessions and “regular” Positron desktop sessions.

Files

Inside a remote host, the Explorer tab will show you files from the remote host instead of your local system.

Settings

When connected to a remote host, you will see two different Settings; one is settings for your local machine and the other is settings that apply to the remote machine.

Extensions

Most extensions run on Positron’s back end. This means that the first time you connect to a remote host, you won’t have any extensions installed. You’ll need to reinstall any extensions on the remote host that you want to use on that host.

Like the Explorer view, the Extensions view will help you see which extensions are installed locally and which are installed on the remote host.

Terminals, R, and Python

All Terminals as well as your R and Python sessions will run on the remote host.

Port forwarding

When you run web applications (e.g. Shiny applications) in Positron, Positron automatically maps the port on the remote host to a port on your local machine.

For example, note that this Shiny application running on :6868 automatically gets a forwarded port 6868 on the local host. The Ports tab shows which ports are currently forwarded from the remote to the local host. Positron tries to use the same port on both hosts when it’s available.

Port Forwarding for Local Web Content

Long-running sessions

By default, Positron will forcefully end your R and Python sessions when you close Positron. If you want to leave your sessions running even after you close Positron – for example, to leave data loaded in memory or let long-running computations continue – you can tell Positron’s kernel supervisor to keep the sessions running. You can find this setting in Settings > Extensions > Kernel Supervisor > Shutdown Timeout.

Shutdown Timeout Settings

Note that this setting only takes effect after restarting Positron!

Resuming sessions

The long-running sessions are associated with the workspace in which you use them. When you reopen a workspace that contains active sessions, Positron will automatically reconnect to the sessions if it finds any that are still running.

Shutdown timeout details

Because the supervisor runs your R and Python sessions without any UI attached, it can’t tell when you’re done with them. In order to prevent sessions from running indefinitely and consuming resources on your remote host, the supervisor will shut them down after a certain period of inactivity. This period is controlled by Shutdown Timeout setting.

The shutdown timeout will never interrupt a kernel that’s busy running code; it doesn’t start counting down until the kernel is idle and it’s not connected to any Positron windows.

If you just want to allow your kernels to finish any running computations when you exit Positron, use the when idle setting.

There’s also an option to allow the kernels to run forever; if you use this option, your R and Python kernels will never exit unless you manually kill the processes or shut them down from Positron. We don’t generally recommend using this option unless you are familiar with process management on your remote host, since it can lead to resource exhaustion.

How it works & troubleshooting

When Positron connects to a new host for the first time, it does the following:

  1. Establishes an SSH connection to the host.
  2. Forms the name and download URL of the correct Positron Server binary, e.g. positron-reh-linux-x64-2025.01.0-39.tar.gz
  3. On the remote host, downloads this binary into ~/.positron-server and unpacks it.
  4. Starts the headless Positron Server inside the remote host.
  5. Connects to the server from the front end.

The two most common problems are:

  • Encountering a 404 when downloading the Positron Server binary. This happens when you attempt to use Remote SSH against a host type that’s not supported, for example, connecting to a macOS host.
  • Encountering an error when starting the Positron Server binary. This happens when you attempt to use Remote SSH against a version of Linux that’s not supported by Positron.

If you need to use a different URL to download Positron Server (for example to use a local copy due to network constraints, or to force the use of a particular version even if it’s not autodetected), you can edit this setting:

Remote SSH: Server Download Url Template Setting

Note that the client and server must be using exactly the same Positron version.

Footnotes

  1. Although Positron doesn’t officially support connecting to Windows Subsystem for Linux (WSL) backends at this time, there is a community-maintained fork of the Open Remote - WSL extension adapted for Positron, available on the Open VSX Registry. The community-maintained WSL extension behaves very similarly to the remote SSH functionality described in this article. This WSL extension is not maintained by the Positron team or Posit. ↩︎