Develop on a remote host with JetBrains Gateway and SSH

Desired outcome

You want the local IDE UI you know, with build, run and debug executed on a remote host. JetBrains Gateway gives a thin client on your machine and runs the IDE backend on the remote host over SSH. Edits are made locally in the UI but are written directly to the remote filesystem, and processes start on the remote machine.

The useful takeaway is to treat Gateway as an SSH-based remote backend, not a file sync. Do not copy the project locally for editing; open it by path on the remote host so indexing, SDKs and run configurations resolve remotely.

Prerequisites

• Local JetBrains IDE with Gateway support installed, e.g., IntelliJ IDEA Ultimate, PyCharm Professional, or the standalone JetBrains Gateway client. Gateway version and IDE edition determine which plugins work remotely.
• SSH access to the remote host. The user account needs shell access and read/write permission to the project directory.
• A compatible JDK or runtime installed on the remote host, matching the project requirements. The SDK is selected remotely after connection.
• Project accessible on the remote filesystem at a known absolute path, e.g., /home/devuser/projects/myapp.
• Private SSH key with correct permissions on the local machine, or password authentication allowed. Firewall access to port 22 or the custom SSH port must be open.

Focused procedure

Create an SSH connection in Gateway

Open JetBrains Gateway locally. From the welcome screen choose New Connection and select SSH.

Fill the connection profile with meaningful placeholders:

• Host: remote.example.com
• Port: 22
• User: devuser
• Authentication: Key pair, path to ~/.ssh/id_ed25519

Before saving, verify basic SSH reachability from a local terminal where you can run commands as your local user:

ssh -i ~/.ssh/id_ed25519 [contact removed]

Required permissions: read access to the private key, typically 600. Risk: keys with overly permissive modes are rejected by ssh, and password prompts can interrupt long Gateway sessions.

Save the profile and connect. On first use Gateway installs a backend distribution on the remote host under the user home. Wait for the backend installation to complete before opening a project.

Open the remote project and configure the remote SDK

Once connected, the IDE opens with a remote file system view. Open the project folder by absolute path on the remote host, e.g., /home/devuser/projects/myapp.

On first open the IDE indexes remotely. Let indexing finish before editing. When prompted, configure the remote SDK:

• File > Project Structure > SDKs
• Add JDK located on the remote host, e.g., /usr/lib/jvm/java-21-openjdk

Build tools such as Maven or Gradle are detected from the remote project. Do not point the IDE to a local wrapper; use the remote installation.

Run and debug remotely

Create a run configuration for a main class or test. Ensure the configuration uses the remote interpreter and the remote working directory.

Example settings to verify:

• Use classpath of module: myapp
• Working directory: /home/devuser/projects/myapp
• Environment variables set on the remote host

Start the run configuration. The process should start on the remote host and output appears in the local IDE Run console.

Expected checks

• Project tree loads from the remote path and shows files without a local copy.
• Code completion and navigation work over the connection. Latency is higher than local.
• Open a file, edit a line, save. Verify the change is present on the remote filesystem via SSH: ssh [contact removed] and cat the file path.
• Run a simple main class or test and confirm the process starts on the remote host and output appears in the IDE run console.
• IDE status bar shows Connected to remote host and the Gateway indicator is green with no backend errors.

Limitations and recovery options

Behavior and supported plugins vary by IDE edition and Gateway version. Some local-only features are not available remotely.

Large projects cause initial indexing and sync latency and higher network usage over unstable links.

Recovery options when connection fails:

• Reconnect from the Gateway welcome screen. The backend remains on the remote host for a period.
• Verify SSH keys and firewall access to the SSH port. Test with ssh from a local terminal.
• If the backend becomes unresponsive, recreate the connection profile after clearing Gateway cache on the remote host under ~/.cache/JetBrains/Gateway.
• Fallback to a local read-only clone for inspection while fixing remote access.

These steps assume current Gateway behavior. Verify with your specific IDE and Gateway versions before relying on a feature in production workflows.