1# Remote Development
  2
  3Remote Development allows you to code at the speed of thought, even when your codebase is not on your local machine. You use Zed locally so the UI is immediately responsive, but offload heavy computation to the development server so that you can work effectively.
  4
  5> **Note:** Remoting is still "alpha". We have several changes we would like to make before it is fully released.
  6
  7## Overview
  8
  9Remote 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.
 10
 11Currently the two instances connect via Zed's servers, but we intend to build peer to peer communication before the feature is fully released.
 12
 13## Setup
 14
 151. Download and install the latest [Zed Preview](https://zed.dev/releases/preview).
 161. Open the remote projects dialogue with `cmd-shift-p remote`.
 171. Click "New Server".
 181. Choose whether to setup via SSH, or to follow the manual setup.
 19   > **Note:** With both options your laptop and the remote machine will communicate
 20   > via https://collab.zed.dev/, so you will need outbound internet access on the remote machine.
 211. On your laptop you can now open folders on the remote machine.
 22   > **Note:** Zed does not currently handle opening very large directories (for example, `/` 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.
 23
 24## Troubleshooting
 25
 26### UI is not showing up
 27
 28You need to be on a relatively recent Zed (v0.145.0 or later).
 29
 30### SSH connections
 31
 32If 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.
 33Once a connection is established, Zed will be downloaded and installed to `~/.local/bin/zed` on the remote machine, and run.
 34
 35If you don't see any output from the Zed command, it is likely that Zed is crashing
 36on 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.
 37
 38### SSH-like connections
 39
 40Zed intercepts `ssh` in a way that should make it possible to intercept connections made by most "ssh wrappers". For example you
 41can specify:
 42
 43- `user@host` will assume you meant `ssh user@host`
 44- `ssh -J jump target` to connect via a jump-host
 45- `gh cs ssh -c example-codespace` to connect to a GitHub codespace
 46- `doctl compute ssh example-droplet` to connect to a DigitalOcean Droplet
 47- `gcloud compute ssh` for a Google Cloud instance
 48- `ssh -i path_to_key_file user@host` to connect to a host using a key file or certificate
 49
 50### zed --dev-server-token isn't connecting
 51
 52There are a few likely causes of failure:
 53
 54- `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.
 55- `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.
 56- `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.
 57
 58## Supported platforms
 59
 60The remote machine must be able to run Zed. The following platforms should work, though note that we have not exhaustively tested every Linux distribution:
 61
 62- macOS Catalina or later (Intel or Apple Silicon)
 63- Linux (x86_64 or arm64, we do not yet support 32-bit platforms). You must have `glibc` installed at version 2.29 (released in 2019) or greater and available globally.
 64- Windows is not yet supported.
 65
 66## Settings and extensions
 67
 68> **Note:** This may change as the alpha program continues.
 69
 70You can edit the settings file on the remote instance. To do so, add a new project to your server in the directory `~/.config/zed`. You can create a file called `settings.json` if it does not yet exist.
 71
 72Note that this is most useful for configuring language servers, as any UI related settings do not apply.
 73
 74If you'd like to install language-server extensions, you can add them to the list of `auto_installed_extensions`. Again you don't need to do this to get syntax highlighting (which is handled by the local zed).
 75
 76```
 77{
 78  "auto_install_extensions": {
 79    "java": true
 80  },
 81}
 82```
 83
 84## Known Limitations
 85
 86- You can't use the Terminal or Tasks if you choose "Manual Connection"
 87- You can't run `zed` in headless mode and in GUI mode at the same time on the same machine.
 88- You can't open files from the remote Terminal by typing the `zed` command.
 89
 90## Feedback
 91
 92Please join the #remoting-feedback channel in the [Zed Discord](https://discord.gg/qSDQ8VWc7k).
 93
 94# Direct SSH Connections
 95
 96The current alpha release of Zed always connects via our servers. This was to get experience building the feature on top of our existing collaboration support. We plan to move to direct SSH connections for any machine that can be SSH'd into.
 97
 98We are working on a direct SSH connection feature, which you can try out if you'd like.
 99
100> **Note:** Direct SSH support does not support most features yet! You cannot use project search, language servers, or basically do anything except edit files...
101
102To try this out you can either from the command line run:
103
104```
105zed ssh://user@host:port/path/to/project
106```
107
108Or you can (in your settings file) add:
109
110```
111"ssh_connections": []
112```
113
114And then from the command palette choose `projects: Open Remote` and configure an SSH connection from there.