-
Notifications
You must be signed in to change notification settings - Fork 4
/
Copy pathremote-ssh.qmd
120 lines (71 loc) · 7.19 KB
/
remote-ssh.qmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
---
title: "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.
```{mermaid}
%%| fig-align: center
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) backends[^1]
- Dev Container workflows (note however that you can start a container yourself and connect to it)
[^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](https://github.com/kv9898/open-remote-wsl) extension adapted for Positron, available on the [Open VSX Registry](https://open-vsx.org/extension/kv9898/open-remote-wsl). The community-maintained WSL extension behaves very similarly to the remote SSH functionality described in this article.
<!-- vale Posit.Contractions = NO -->
This WSL extension is not maintained by the Positron team or Posit.
<!-- vale Posit.Contractions = YES -->
## Creating a connection
To create a connection, open the Command Palette (<kbd>Cmd/Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd>) and type "Remote Menu". Run the _Remote SSH: Show Remote Menu_ command.
{width=700}
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.
{width=350}
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.
## 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_.
{width=638}
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:
{width=650}
Note that the client and server must be using **exactly** the same Positron version.