Skip to main content
Remote development opens a project folder on another machine in a normal OpenIDEA window. The UI stays on your desktop; the IDE backend, openidea-server, runs on the remote host. Indexing, language servers, terminals, run configurations, debuggers, build tools and Git all run there, next to the code. OpenIDEA connects over SSH, or on Windows directly into a WSL distribution. For dev containers, see Containers.

​
Requirements

  • An SSH host running Linux (x86_64 or aarch64) or macOS (Apple silicon or Intel). Windows hosts are not supported.
  • A POSIX shell with uname, gzip, mkdir, chmod, mv and find on the host, and the SFTP subsystem enabled (used to install the server and by Browse in the connect dialog).
  • The first connection downloads the matching openidea-server release build to your desktop and uploads it to the host. Without internet access on the desktop, see Offline installation.

​
Add an SSH configuration

Remote development, run targets, data source tunnels, deployment servers and Start SSH Session… all connect through the app-wide SSH configurations.
1

Open the SSH settings

Choose Tools › SSH Configurations…, or open Settings › Tools › SSH Configurations.
2

Add a configuration

Click + (Add) and fill in Name, Host, Port: and User name.
3

Pick the authentication type

Choose one of the options under Authentication type (see below).
4

Test the connection

Click Test Connection. If the host key is not in ~/.ssh/known_hosts yet, OpenIDEA shows the key and offers Trust Host and Retry, which adds it there.
Saved passwords and passphrases go to the macOS Keychain, Windows Credential Manager or the Secret Service on Linux, never to a settings file. The +, − and copy buttons above the list add, remove and duplicate configurations.

​
~/.ssh/config support

OpenIDEA has its own SSH client and reads ~/.ssh/config itself. It understands Host, Match, Include, HostName, User, Port, IdentityFile, ProxyJump, ProxyCommand, StrictHostKeyChecking and UserKnownHostsFile. Jump hosts authenticate with the agent and identity files; the password or passphrase of the configuration is only used for the target host. Host keys are checked against known_hosts. An unknown key has to be trusted once; a changed key is refused unless host key checking is turned off for that host.

​
Open a remote project

1

Open the connect dialog

Choose File › Remote Development…, or click Remote Development on the Welcome screen.
2

Choose the host

Pick an entry under SSH configuration:. Configure… opens the SSH settings if you need to add one.
3

Choose the folder

Type a path under Project directory: (~ and ~/… are relative to the remote home), or click Browse to walk the remote folders.
4

Open

Click Open. If a project is already open, choose This Window or New Window.
While connecting, the dialog shows each stage: connecting to the host, checking the IDE backend on the host, downloading or installing it when needed, starting it, and opening the project. The first connection to a host takes longer because of the upload; later ones reuse the installed server. After the project opens you are asked whether to trust it, as for a local folder.
Run Test Connection in the SSH settings before the first connection. That is where you trust a new host key and enter the password or passphrase.

​
Working in a remote window

  • The window title ends with the host, and the status bar shows SSH: <host>. Clicking it opens the Remote Development dialog.
  • Remote projects appear in the recent projects list on the Welcome screen, so you can reopen them from there.
  • Language servers, debuggers and other tools that OpenIDEA installs go to the remote host, under ~/.openidea/data.
  • Your keymap, appearance, editor font and colour scheme stay on the desktop. Project and tool settings live on the host.
  • Your code plugins are synced to the server and run next to the project.
  • File › Disconnect from Remote Host closes the project and ends the connection.

​
Forward ports

A remote window has a Ports tool window. Enter a port under Remote port, e.g. 3000 and click Forward Port. localhost:<port> on the remote host is then reachable on your machine, on the same port when it is free or on another free one. Each row can be opened in the browser, copied, or stopped. Forwarded ports are remembered per host and folder, and forwarded again the next time you connect.

​
Reload the environment

The server takes its environment from your login shell on the host when it starts. After changing a shell profile, choose File › Reload Environment so new terminals, runs and tools get the new values. Processes that are already running keep the old environment. When variables changed, the notification offers Restart Language Servers. If the remote project has a .devcontainer/devcontainer.json or .devcontainer.json, its remoteEnv is applied too, and its postStartCommand runs once each time the server starts.

​
Start an SSH terminal

Tools › Start SSH Session… (or SSH Session… in the Terminal tool window’s new-tab menu) picks an SSH configuration and opens a terminal tab that runs ssh for it. This uses the OpenSSH client on your machine, so ssh must be on your PATH. It does not open a remote project.

​
Connect to WSL (Windows)

On Windows, when at least one WSL distribution is installed, the connect dialog shows Connect through: with SSH and WSL. Choose WSL, pick the WSL distribution: and enter the Project directory: inside the distribution. OpenIDEA installs and starts openidea-server inside the distribution with wsl.exe; no SSH server is needed. The status bar then shows WSL: <distribution>. Opening a folder under \\wsl.localhost\<distribution>\ also opens it through the distribution. Browse is not available for WSL.

​
Other uses of SSH configurations

  • Run targets (Settings › Build, Execution, Deployment › Run Targets) run a configuration on an SSH host. See Run configurations.
  • Data sources can connect through an SSH tunnel. See Database.
  • Tools › Deployment uploads, downloads and syncs project files with a server over SFTP.

​
Limits

  • One project per remote window: a remote project can’t be attached to another window’s projects.
  • The SSH host must run Linux or macOS on x86_64 or aarch64.