← Back to DevBytes
Developer Tutorial July 12, 2026 16 min read

IntelliJ IDEA Remote Development: Complete Guide

What Is IntelliJ IDEA Remote Development?

IntelliJ IDEA Remote Development is a feature that allows you to run the full IntelliJ IDEA IDE on a remote server while interacting with it through a lightweight client on your local machine. Instead of running the IDE locally and remotely accessing files via SSHFS or similar mounts, the entire IDE backend — including indexing, code analysis, compilation, and debugging — executes on the remote host where your source code resides.

JetBrains ships this capability through two primary components:

This model fundamentally differs from VNC-style remote desktop solutions. Only the UI rendering happens locally; all semantic IDE operations run remotely. The result is a near-native editing experience with the full power of IntelliJ IDEA, even when working against codebases on distant servers, cloud VMs, or Docker containers.

Why Remote Development Matters

🚀 Deploy your AI agent in 10 minutes

Managed Hermes hosting. Zero DevOps. 100M tokens/mo included.

Try it free →

Remote Development solves several critical pain points in modern software engineering:

How Remote Development Works — Architecture Overview

The architecture consists of three logical tiers:

The communication protocol between the thin client and the remote backend is JetBrains' proprietary RD protocol (Remote Development protocol). It transmits editor state, completion popups, and UI deltas efficiently, adapting to available bandwidth. The protocol also supports port forwarding so that web applications running on the remote host can be previewed in the local browser seamlessly.

Setting Up Remote Development

Prerequisites

Before you begin, ensure the following requirements are met:

Installing JetBrains Gateway

JetBrains Gateway is available as a standalone application and can be installed via several methods:

Option 1: JetBrains Toolbox — Install JetBrains Toolbox, then browse the available products and click "Install" next to Gateway.

Option 2: Direct download — Visit the JetBrains website, download the Gateway installer for your OS, and run it.

Option 3: Package managers (Linux) — On Ubuntu, you can use the snap package:

sudo snap install intellij-gateway --classic

Or on Arch Linux via AUR:

yay -S jetbrains-gateway

Option 4: Via an existing IDE — In IntelliJ IDEA 2023.1 or newer, the Remote Development plugin ships pre-bundled. You can initiate a remote session directly from the Welcome screen by clicking "Remote Development" or by installing the "Remote Development" plugin from the marketplace if it's missing.

Connecting via SSH

This is the most common workflow. Follow these steps:

  1. Launch JetBrains Gateway on your local machine.
  2. On the Welcome screen, select "SSH" as the connection type.
  3. Enter your remote server's hostname or IP address, the SSH port (default 22), and your username.
  4. Choose the authentication method — password, SSH key, or SSH agent.
  5. Click "Check Connection" to verify connectivity. Gateway will test the SSH connection and report whether the remote machine meets the requirements for hosting the IDE backend.
  6. Once the connection is verified, Gateway will prompt you to select the IDE version to install on the remote server. You can choose a specific IntelliJ IDEA version (e.g., 2024.1, 2024.2) or use the latest stable release.
  7. Specify the project directory on the remote server — the path where your source code lives.
  8. Click "Start IDE" — Gateway will download and install the IDE backend on the remote server (if not already cached), launch it, and connect the local thin client.

For key-based authentication, ensure your SSH key is properly configured. Here's an example ~/.ssh/config entry that streamlines the connection:

Host dev-server
    HostName 10.0.1.50
    User johndoe
    Port 22
    IdentityFile ~/.ssh/id_ed25519
    ServerAliveInterval 60
    ServerAliveCountMax 10
    TCPKeepAlive yes

With this SSH config entry, you can simply enter dev-server as the hostname in Gateway, and all connection parameters will be picked up automatically.

Connecting to a Remote IDE Backend (Already Running)

If a remote IDE backend is already running on the server (for example, left running from a previous session), Gateway can reconnect to it directly without launching a new instance. This preserves your open files, terminal sessions, and debugger state.

To reconnect:

You can also list running backends manually on the remote server via the command line:

ps aux | grep -i intellij | grep -i remote

Each backend process writes a lock file with connection details, typically located in ~/.cache/JetBrains/RemoteDev/ on the remote host.

Working with Docker Containers

JetBrains Gateway supports connecting to IDE backends running inside Docker containers. This is particularly useful for ephemeral environments or when the remote server itself is containerized.

You can use the provided Docker image or create a custom one. Here's an example Dockerfile that prepares a development container with IntelliJ IDEA backend support:

FROM ubuntu:22.04

# Install essential dependencies for IntelliJ IDEA backend
RUN apt-get update && apt-get install -y \
    openssh-server \
    curl \
    git \
    build-essential \
    fontconfig \
    libxrender1 \
    libxtst6 \
    libxi6 \
    libfreetype6 \
    && rm -rf /var/lib/apt/lists/*

# Configure SSH for remote development
RUN mkdir /var/run/sshd && \
    echo 'PermitRootLogin yes' >> /etc/ssh/sshd_config && \
    echo 'PasswordAuthentication yes' >> /etc/ssh/sshd_config && \
    echo 'ClientAliveInterval 60' >> /etc/ssh/sshd_config

# Create a user for development
RUN useradd -m -s /bin/bash developer && \
    echo 'developer:developer' | chpasswd

# Expose SSH port
EXPOSE 22

# Start SSH daemon
CMD ["/usr/sbin/sshd", "-D"]

Build and run the container:

docker build -t dev-container .
docker run -d --name my-dev-env -p 2222:22 dev-container

Then connect from Gateway using SSH on port 2222 with user developer.

For production setups, you should use SSH key injection rather than hardcoded passwords:

# Generate a key pair for container access
ssh-keygen -t ed25519 -f ~/.ssh/dev-container-key -N "" -C "dev-container"

# Build with the public key baked in
docker build --build-arg SSH_PUB_KEY="$(cat ~/.ssh/dev-container-key.pub)" -t dev-container .

# Connect using the private key
ssh -i ~/.ssh/dev-container-key -p 2222 developer@localhost

Configuration File: .remote-dev.json

JetBrains Remote Development can be configured via a JSON file checked into the project repository. This file, typically named .remote-dev.json and placed in the project root, defines the remote environment settings so that every team member gets an identical setup.

Here's a comprehensive example:

{
  "sshConfig": {
    "host": "dev-server.internal.company.com",
    "port": 22,
    "user": "${env:USER}",
    "keyPath": "~/.ssh/id_ed25519"
  },
  "ideSettings": {
    "productCode": "IU",
    "version": "2024.1.2",
    "projectPath": "/home/dev/project",
    "javaHome": "/usr/lib/jvm/java-17-openjdk-amd64",
    "vmOptions": [
      "-Xmx8g",
      "-Xms2g",
      "-XX:+UseG1GC"
    ]
  },
  "plugins": [
    "org.intellij.scala",
    "org.jetbrains.plugins.go",
    "PythonCore"
  ],
  "env": {
    "GRADLE_HOME": "/opt/gradle-8.5",
    "MAVEN_HOME": "/opt/maven-3.9",
    "NODE_PATH": "/opt/node-v18/lib/node_modules",
    "PATH": "/usr/local/bin:/opt/gradle-8.5/bin:/opt/maven-3.9/bin:${env:PATH}"
  }
}

Key fields explained:

When a developer opens this project via Gateway, the configuration is read automatically, eliminating manual setup steps.

Configuring the Remote Environment

Customizing IDE Settings

The remote IDE backend stores its settings separately from your local IDE installations. You can synchronize settings using JetBrains' Settings Repository feature or by manual export/import.

Using Settings Repository (recommended):

  1. On your local IntelliJ IDEA, go to File → Manage IDE Settings → Settings Repository
  2. Configure a Git repository URL (e.g., a private GitHub repo) to store your settings
  3. Push your current settings to the repository
  4. On the remote IDE backend (accessible through the Gateway-connected UI), navigate to the same menu and point it to the same repository
  5. The remote IDE will pull and apply your settings automatically

Using manual export:

Export settings from your local IDE via File → Manage IDE Settings → Export Settings, then transfer the ZIP file to the remote host and import it through the remote IDE's equivalent menu.

You can also configure the remote backend's JVM options and environment via command-line overrides when launching from Gateway. This is useful for allocating more heap memory to a large project:

# On the remote host, you can customize the backend VM options file
# Location (varies by version):
nano ~/.cache/JetBrains/RemoteDev/IU-241.14494.240/idea.vmoptions

# Example contents:
-Xmx12g
-Xms4g
-XX:+UseZGC
-XX:SoftRefLRUPolicyMSPerMB=50
-Dsun.awt.disablegrab=true
-Dide.process.manager.threads=4

Managing Plugins

Plugins on the remote backend operate identically to a local IDE installation. You can install, update, and disable plugins through the standard Settings → Plugins UI within the remote IDE session.

For team consistency, consider predefining required plugins in the .remote-dev.json file as shown earlier. Plugin IDs can be found on the JetBrains Plugin Marketplace URL — for example, the Go plugin's page URL ends with /go/, and its ID is org.jetbrains.plugins.go.

To extract plugin IDs from an existing IDE installation for sharing:

# List installed plugins with their IDs on the remote host
find ~/.cache/JetBrains/RemoteDev/*/plugins/ -name "*.jar" -maxdepth 1 \
  | xargs -I {} basename {} .jar \
  | grep -v "^_" \
  | sort

Environment Variables and Paths

The remote IDE backend inherits the environment of the SSH login shell. However, because the backend is launched non-interactively, some profile scripts (.bashrc, .bash_profile, .profile) may not be sourced automatically.

To ensure your development tools are on the PATH, you have several options:

Example ~/.profile snippet that works for both interactive and non-interactive remote IDE sessions:

# Development environment — sourced for both interactive and remote IDE sessions
export JAVA_HOME="/usr/lib/jvm/java-21-openjdk-amd64"
export GRADLE_HOME="/opt/gradle-8.7"
export MAVEN_HOME="/opt/maven-3.9.8"
export GOPATH="$HOME/go"
export PATH="$JAVA_HOME/bin:$GRADLE_HOME/bin:$MAVEN_HOME/bin:$GOPATH/bin:$PATH"

# SDKMAN! (if used)
if [ -f "$HOME/.sdkman/bin/sdkman-init.sh" ]; then
    source "$HOME/.sdkman/bin/sdkman-init.sh"
fi

Best Practices

1. Pre-cache IDE Backends on Remote Servers

The first connection to a remote server incurs a delay while Gateway downloads and installs the IDE backend (typically 1–3 minutes depending on network speed). You can pre-cache the backend on frequently used servers to eliminate this wait:

# On the remote server, pre-download the IDE backend installer
cd /tmp
curl -L -o idea-backend.tar.gz \
  "https://download.jetbrains.com/idea/ideaIU-2024.1.2.tar.gz"
tar xzf idea-backend.tar.gz -C ~/.cache/JetBrains/RemoteDev/
# Gateway will detect the cached version and skip the download step

2. Use SSH ControlMaster for Persistent Connections

SSH ControlMaster multiplexes multiple sessions over a single TCP connection, reducing authentication overhead and improving responsiveness. Configure it in your SSH config:

Host *
    ControlMaster auto
    ControlPath ~/.ssh/controlmux/%r@%h:%p
    ControlPersist 10m

Create the control socket directory:

mkdir -p ~/.ssh/controlmux

Gateway will benefit from this automatically when connecting to hosts matching the Host * pattern.

3. Allocate Sufficient Remote Resources

The remote IDE backend is a full IntelliJ IDEA process. For large projects (500,000+ files, multiple languages), allocate at minimum:

Monitor resource usage on the remote host to avoid contention with other services:

# Check IDE backend resource consumption
ps aux | grep -i intellij | grep -v grep
htop -p $(pgrep -f "intellij.*remote")

4. Version Your Remote Environment Configuration

Commit the .remote-dev.json file to your project repository. This ensures every developer — including new team members — can spin up an identically configured remote IDE session with zero manual setup. Combine it with a DEVELOPMENT.md document that explains how to connect:

# Remote Development Setup

This project uses IntelliJ IDEA Remote Development.

## Prerequisites
- JetBrains Gateway installed locally
- SSH access to our development server (`dev-server.internal.company.com`)
- An authorized SSH key pair

## Quick Start
1. Open JetBrains Gateway
2. Select "New SSH Connection"
3. Enter host: `dev-server.internal.company.com`
4. Gateway will read `.remote-dev.json` automatically
5. Click "Start IDE" — the environment provisions itself

## First Connection
The initial connection downloads the IDE backend (~3 minutes).
Subsequent connections reuse the cached backend.

5. Leverage Port Forwarding for Web Previews

When running web applications, database admin tools, or API servers on the remote host during development, Gateway automatically forwards those ports to your local machine. You can configure explicit port forwarding rules:

{
  "sshConfig": {
    "host": "dev-server",
    "port": 22,
    "user": "developer",
    "forwardPorts": [
      {
        "remotePort": 8080,
        "localPort": 8080,
        "description": "Application server"
      },
      {
        "remotePort": 5432,
        "localPort": 15432,
        "description": "PostgreSQL tunnel"
      }
    ]
  }
}

This allows you to access http://localhost:8080 in your local browser and have it reach the remote server's port 8080 transparently.

6. Handle Disconnections Gracefully

The remote IDE backend continues running even if your local Gateway client disconnects (network interruption, laptop sleep, etc.). Upon reconnection, Gateway restores your entire session — open files, terminals, running processes, and debugger state persist.

To intentionally suspend a session and resume later:

To fully stop a remote backend when done:

# From within the remote IDE: File → Exit (or Ctrl+Q / Cmd+Q)
# Alternatively, kill the backend process on the remote host:
pkill -f "intellij.*remote.*backend"

7. Secure the Remote Environment

Since the remote IDE backend has full access to your source code and build tools, apply these security measures:

Example restrictive SSH configuration for the remote development user:

# /etc/ssh/sshd_config (relevant excerpts)
Match User developer
    PasswordAuthentication no
    PubkeyAuthentication yes
    AuthenticationMethods publickey
    PermitUserEnvironment no
    X11Forwarding no
    AllowTcpForwarding yes
    PermitOpen any
    ClientAliveInterval 60
    ClientAliveCountMax 3

Troubleshooting Common Issues

Issue: "Backend fails to start" or "Connection refused"

This typically indicates that the remote IDE backend process crashed during startup or couldn't bind to its internal port. Check the backend logs on the remote host:

# Locate and inspect backend logs
find ~/.cache/JetBrains/RemoteDev/ -name "idea.log" -mmin -30 \
  | xargs tail -100

# Check for JVM crashes
dmesg | grep -i "out of memory" | tail -20
journalctl -xe | grep -i intellij

Common causes: insufficient RAM (increase -Xmx), missing JDK (install OpenJDK 17+), or incompatible glibc version (ensure the remote OS is recent enough).

Issue: "High latency / sluggish typing"

The RD protocol is optimized for typical network conditions, but certain factors can degrade responsiveness:

Issue: "Project files not found / wrong path"

Ensure the project path in Gateway or .remote-dev.json matches the absolute path on the remote filesystem. Relative paths are resolved against the SSH user's home directory. Verify with:

# SSH into the remote host and confirm the path exists
ssh dev-server "ls -la /home/developer/projects/my-app/build.gradle"

Issue: "Plugins not loading on remote backend"

Some plugins are platform-specific and may not function correctly in a headless remote environment. Check plugin compatibility in the JetBrains Marketplace — plugins tagged with "Remote Development compatible" are verified to work. If a plugin causes backend crashes, disable it by removing its directory:

# Remove a problematic plugin from the remote backend
rm -rf ~/.cache/JetBrains/RemoteDev/IU-*/plugins/plugin-id-folder/
# Restart the backend via Gateway

Conclusion

IntelliJ IDEA Remote Development fundamentally changes how developers interact with large, remote, or regulated codebases. By separating the IDE's compute-intensive backend from the lightweight UI client, it delivers a responsive editing experience regardless of where source code physically resides. The JetBrains Gateway and SSH-based connectivity make onboarding straightforward, while the .remote-dev.json configuration file enables teams to codify and share their development environments as infrastructure-as-code.

Whether you're working on a monorepo that strains your laptop, accessing a cloud-native application inside a VPC, or standardizing toolchains across a distributed team, Remote Development provides a practical, secure, and high-performance solution. By following the setup steps, configuration patterns, and best practices outlined in this guide, you can establish a robust remote development workflow that scales with your engineering organization and keeps developers productive regardless of their local hardware limitations.

🚀 Need a reliable AI agent for your project?

Deploy Hermes Agent in 10 minutes. Managed hosting, zero DevOps.

Get Started — $23.99/mo
← Back to all articles