Allow ssh connection for setting up zed (#12063)

Co-Authored-By: Mikayla <mikayla@zed.dev>



Release Notes:

- Magic `ssh` login feature for remote development

---------

Co-authored-by: Mikayla <mikayla@zed.dev>
Co-authored-by: Nate Butler <iamnbutler@gmail.com>

docs/src/remote-development.md

@@ -6,7 +6,7 @@ Remote Development allows you to code at the speed of thought, even when your co
 
 ## Overview
 
-Remote development requires running two instances of Zed. A headless instance on the remote machine, and the editor interface on your local computer. All configuration is done on your local computer, except for starting the headless instance.
+Remote development requires running two instances of Zed. A headless instance on the remote machine, and the editor interface on your local computer. All configuration is done on your local computer.
 
 Currently the two instances connect via Zed's servers, but we intend to build peer to peer communication in the future.
 
@@ -14,18 +14,48 @@ Currently the two instances connect via Zed's servers, but we intend to build pe
 
 > NOTE: You must be in the alpha program to see this UI. The instructions will likely change as the feature gets closer to launch.
 
-1. Open the projects dialog with `cmd-option-o` and then click "Connect…".
+1. Download and install the latest [Zed Preview](https://zed.dev/releases/preview).
+1. Open the remote projects dialogue with `cmd-shift-p remote`
 2. Click "Add Server"
-3. Give it a name, and copy the instructions given.
-4. On the remote machine, install Zed
-   ```
-   curl https://zed.dev/install.sh | bash
-   ```
-5. On the remote machine, paste the instructions from step 3. You should see `connected!`.
-   > NOTE: If this command runs but doesn't output anything, try running `zed --foreground --dev-server-token YY.XXX`. It is possible that the zed background process is crashing on startup.
+3. Choose whether to setup via SSH, or to follow the manual setup.
+   > NOTE: With both options your laptop and the remote machine will communicate
+     via https://collab.zed.dev/, so you will need outbound internet access on the remote machine.
 6. On your laptop you can now open folders on the remote machine.
    > NOTE: Zed does not currently handle opening very large directories (e.g. `/` or `~` that may have >100,000 files) very well. We are working on improving this, but suggest in the meantime opening only specific projects, or subfolders of very large mono-repos.
 
+## Toubleshooting
+
+### UI is not showing up
+
+This can happen either if you were just added to the alpha, in which case you need to restart zed. Or, if you lost connection to the zed server, in which case you just need to click "Sign In" in the top right.
+
+### SSH connections
+
+If you chose to connect via SSH, the command you specify will be run in a zed terminal given you an opportunity to type any passwords/keyphrases etc. that you need.
+Once a connection is established zed will be downloaded and installed to `~/.local/bin/zed` on the remote machine, and run.
+
+If you don't see any output from the zed command, it is likely that zed is crashing
+on startup. You can troubleshoot this by switching to manual mode and passing the `--foreground` flag. Please [file a bug](https://github.com/zed-industries/zed) so we can debug it together.
+
+### SSH-like connections
+
+Zed intercepts `ssh` in a way that should make it possible to intercept connections made by most "ssh wrappers". For example you
+can specify:
+
+* `user@host` will assume you meant `ssh user@host`
+* `ssh -J jump target` to connect via a jump-host
+* `gh cs ssh -c example-codespace` to connect to a github codespace
+* `doctl compute ssh example-droplet` to connect to a digital ocean droplet
+* `gcloud compute ssh` for a google cloud instance
+
+### zed --dev-server-token isn't connecting
+
+There are a few likely causes of failure:
+
+* `zed --dev-server-token` runs but outputs nothing. This is probably because the zed background process is crashing on startup. Try running `zed --dev-server-token XX --foreground` to see any output, and [file a bug](https://github.com/zed-industries/zed) so we can debug it together.
+* `zed --dev-server-token` outputs something like "Connection refused" or "Unauthorized" and immediately exits. This is likely due to issues making outbound HTTP requests to https://collab.zed.dev from your host. You can try to debug this with `curl https://collab.zed.dev`, but we have seen cases where curl is whitelisted, but other binaries are not allowed network access.
+* `zed --dev-server-token` outputs "Zed is already running". If you are editing an existing server, it is possible that clicking "Connect" a second time will work, but if not you will have to manually log into the server and kill the zed process.
+
 ## Supported platforms
 
 The remote machine must be able to run Zed. The following platforms should work, though note that we have not exhaustively tested every linux distribution:
@@ -36,11 +66,11 @@ The remote machine must be able to run Zed. The following platforms should work,
 
 ## Known Limitations
 
-- The Terminal does not work remotely.
+- The Terminal does not work remotely unless you configure the machine to use SSH.
 - You cannot spawn Tasks remotely.
 - Extensions aren't yet supported in headless Zed.
 - You can not run `zed` in headless mode and in GUI mode at the same time on the same machine.
 
 ## Feedback
 
-- Please join the #remoting-feedback in the [Zed Discord](https://discord.gg/qSDQ8VWc7k).
+- Please join the #remoting-feedback channel in the [Zed Discord](https://discord.gg/qSDQ8VWc7k).