Remote Development over SSH

Open a folder on another machine over SSH and work as if it were local. Files, editing, search, terminals, Git, language servers and run configurations all run on the host. Lumide stays on your machine.

Connect#

1. Click Connect to SSH Host… on the Welcome screen, or run Remote: Connect to SSH Host… from the Command Palette.
2. Pick a host. The dialog lists hosts you connected to before and those in ~/.ssh/config, narrowing them as you type. You can also type user@host or user@host:port.
3. Enter the folder to open: an absolute path, or ~ for your home folder. Folders you opened on that host before are listed below it.
4. Click Connect.

The workspace opens in a new window. Its status bar shows SSH: host while connected. Remote workspaces appear in Recent Projects, so you can open them again from there, with the user and port you connected with. Entries saved by earlier versions kept no port and connect to the default one; connect once more with the port, and Recent Projects keeps that one.

Lumide uses your system ssh. Your ~/.ssh/config, keys, agent, jump hosts and known hosts all work as usual. When ssh needs a password, a key passphrase, a second factor, or approval for a new host key, Lumide asks in a dialog.

Connections to a host share one ssh connection, whose socket lives in a folder only you can open: $XDG_RUNTIME_DIR/lumide-ssh on Linux, ~/.sofluffy/ssh otherwise. If that folder is a link or belongs to someone else, Lumide refuses to connect and says so.

Several folders#

An SSH window can hold several folders on the host. Run Add Folder to Workspace… and pick a folder there: type a path, or ~ for your home folder, and open folders to browse. The folders come back when you open the first one again, also from Recent Projects, which lists them. See Multi-Root Workspaces.

What runs where#

The first connection to a host installs a small server in ~/.lumide-server/. Lumide downloads the server for your version once, then uploads it over SSH, so the host needs no internet access. The upload may take up to 30 minutes on a slow link. Hosts can run Linux (x64 or arm64) or macOS.

Dropped connections#

If the network drops, the status bar shows Reconnecting, and Lumide reconnects on its own. Unsaved edits, open terminals and running processes survive the drop. If Lumide quits with unsaved remote files, Hot Exit restores them the next time you open the workspace.

After a drop, the host keeps your session for up to 3 hours. Once you close the last window on a folder, its server stops within 10 minutes, along with its terminals.

Forward a port#

To open a dev server running on the host in your local browser:

1. Run Remote: Forward a Port….
2. Enter the port, such as 3000. To use a different local port, enter 8080:3000. That makes host port 3000 available at localhost:8080.

Run Remote: Stop Forwarding a Port… to stop forwarding. Closing the window stops all of its forwards.

Forwards survive a dropped connection: once Lumide reconnects, it forwards each port again, and tells you about any port it cannot get back, such as one another program took meanwhile.

Troubleshooting#

• Remote: Show Log shows the server's log in the Output pane.
• Connecting from Windows is not supported yet.
• Sharing is not available in an SSH window: sharing serves files from your own machine, not the host's.
• Don't need SSH? Turn off the built-in Remote SSH plugin in the Plugins pane's Installed tab. Connect to SSH Host… disappears from the Welcome screen and the Command Palette, and opening an SSH folder from Recent Projects says to turn the plugin back on. Windows already connected keep working.

Related#

• Workspaces
• Multi-Root Workspaces
• Sharing a Workspace
• Hot Exit & Session Recovery