Add docs for Remote-SSH feature (#30)

* Add docs for Remote-SSH feature

* thanks vale

* this really isn't how I want to spend my day

* Fix sizing, centering

* Consistency with other pages

---------

Co-authored-by: Julia Silge <[email protected]>

_extensions/posit-dev/posit-docs/theme.scss

@@ -397,3 +397,6 @@ ol.groovyAlpha li > p:before {
   line-height: 16px;
   vertical-align: middle;
 }
+
+// Workaround for https://github.com/quarto-dev/quarto-cli/issues/9178
+$mermaid-fg-color--lightest:#FFFFFF;

_quarto.yml

@@ -68,6 +68,7 @@ website:
         - data-explorer.qmd
         - connections-pane.qmd
         - run-interactive-apps.qmd
+        - remote-ssh.qmd
         - updating.qmd
 
     - title: "Help"

remote-ssh.qmd

@@ -0,0 +1,92 @@
+---
+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 amd64 hosts aren't currently supported.
+
+Other features that aren't currently supported include:
+
+- Connecting to Windows Subsystem for Linux (WSL) backends
+- 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 (<kbd>Cmd/Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd>) and type "Remote Menu". Run the _Remote SSH: Show Remote Menu_ command.
+
+![The Remote SSH menu](./images/remote-ssh-menu.png){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.
+
+![Remote SSH Status Indicator](./images/remote-ssh-status.png){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.
+
+![Port Forwarding for Local Web Content](./images/remote-ssh-port-forwarding.png)
+
+## 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](./images/remote-ssh-server-template.png){width=650}
+
+Note that the client and server must be using **exactly** the same Positron version.