Connecting JetBrains IDEs

Connect your JetBrains IDE (IntelliJ IDEA, WebStorm, PhpStorm, etc.) to Workspace Manager workspaces for remote development using SSH-based deployment and remote interpreters.

Overview

JetBrains IDEs support remote development through SSH, allowing you to run your IDE locally while executing code and accessing files on remote workspaces. This provides a seamless development experience with full IDE features running against your remote workspace environment.

Prerequisites

• JetBrains IDE (2021.3 or later recommended)
• SSH access configured (see SSH documentation)
• Workspace running and accessible
• SSH key added to your WSM profile

Supported IDEs

All JetBrains IDEs with SSH deployment support can connect to Workspace Manager workspaces:

• WebStorm
• PhpStorm
• DataGrip

Configuration

JetBrains IDEs use SSH deployment to sync files between your local machine and remote workspace, while executing code remotely. This keeps your IDE running locally with full performance while leveraging the remote workspace environment.

Step 1: Configure SSH Deployment

1. Open your JetBrains IDE
2. Go to Settings/Preferences → Build, Execution, Deployment → Deployment
3. Click the + button to add a new deployment configuration
4. Select SFTP as the type
5. Name your configuration (e.g., “My Workspace”)

Step 2: Configure Connection Settings

In the Connection tab:

1. SSH Configuration: Select OpenSSH config and authentication agent
2. Host: Enter your workspace hostname from SSH config (e.g., wsm.my_workspace)
3. Port: 22 (default)
4. User name: Your workspace ID
5. Authentication: Select Key pair
6. Private key file: Browse to your SSH private key (e.g., ~/.ssh/id_ed25519)

Using SSH Config

If you’ve set up your SSH config properly (see SSH documentation), you can simply use the hostname alias (e.g., wsm.my_workspace) and the IDE will use your SSH config settings.

Step 3: Configure Path Mappings

In the Mappings tab:

1. Local path: Your project root directory
2. Deployment path: Remote workspace path (e.g., /home/developer/project)
3. Web path: Leave blank unless needed for web development

Step 4: Test Connection

1. Click Test Connection to verify SSH access
2. If successful, you’ll see a confirmation message
3. Click OK to save the configuration

Step 5: Configure Automatic Upload

To automatically sync files when you save:

1. Go to Settings/Preferences → Build, Execution, Deployment → Deployment → Options
2. Set Upload changed files automatically to the default server: On explicit save action
3. Optionally enable Upload external changes to sync files modified outside the IDE

Step 6: Start Developing

You’re now ready to develop remotely:

• Edit files locally - they’ll sync automatically
• Debugging works with remote processes using SSH port forwarding
• Terminal can connect to remote workspace

Deployment Tools

Manual Upload/Download

Right-click on files or folders:

• Deployment → Upload to [server name]
• Deployment → Download from [server name]
• Deployment → Sync with Deployed to [server name]

Compare with Remote

• Deployment → Compare with Deployed Version on [server name]
• View differences between local and remote files
• Merge changes as needed

Browse Remote Files

• Tools → Deployment → Browse Remote Host
• Opens a tool window showing remote file system
• Drag and drop files between local and remote

Working with Remote Interpreters

Node.js (WebStorm/IntelliJ IDEA)

Remote Node.js interpreter:

• Uses remote npm/yarn for package management
• Runs scripts defined in package.json remotely
• Debugs Node.js applications on workspace

PHP and Xdebug (PhpStorm)

PhpStorm can debug PHP applications running on remote workspaces using Xdebug over SSH port forwarding.

Prerequisites

• Xdebug installed and configured on the remote workspace
• SSH deployment configured (see steps above)
• Port forwarding enabled

Configure Xdebug on Remote Workspace

Ensure Xdebug is configured on your workspace. Add these settings to ~/html/.user.ini:

xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=127.0.0.1
xdebug.client_port=9003

The key is setting client_host to 127.0.0.1 since we’ll use SSH port forwarding.

.user.ini Location

The .user.ini file should be placed at ~/html/.user.ini on the remote workspace. This file allows per-directory PHP configuration without modifying the global php.ini.

Configure PhpStorm Debug Settings

1. Go to Settings → PHP → Debug
2. Set Debug port: 9003 (or your Xdebug port)
3. Enable Can accept external connections
4. Optionally disable Break at first line in PHP scripts for cleaner debugging

Configure PHP Interpreter

1. Go to Settings → PHP
2. Click … next to CLI Interpreter
3. Click + → From Docker, Vagrant, VM, WSL, Remote…
4. Select SSH and choose your existing deployment configuration
5. Set the PHP executable path on the remote workspace (e.g., /usr/bin/php)
6. PhpStorm will detect Xdebug automatically

Configure Path Mappings

1. Go to Settings → PHP → Servers
2. Click + to add a new server
3. Set Name: Your workspace name
4. Set Host: Your workspace hostname
5. Enable Use path mappings
6. Map your local project root to the remote path (e.g., /home/developer/project)

Start Debugging

1. Click the Start Listening for PHP Debug Connections button (phone icon) in the toolbar
2. Set breakpoints in your PHP code
3. Trigger your PHP application (via browser, CLI, etc.)
4. PhpStorm will pause at your breakpoints

Troubleshooting Xdebug

Xdebug not connecting:

1. Verify port forwarding is active: ssh -R 9003:localhost:9003 wsm.my_workspace
2. Check Xdebug is loaded: ssh wsm.my_workspace "php -v" (should show Xdebug)
3. Verify Xdebug settings: ssh wsm.my_workspace "php -i | grep xdebug"
4. Check PhpStorm is listening (phone icon should be green)
5. Verify firewall isn’t blocking port 9003

Breakpoints not hit:

1. Verify path mappings are correct
2. Check that Xdebug client_host is set to 127.0.0.1
3. Ensure xdebug.start_with_request=yes is set
4. Try adding XDEBUG_SESSION=1 to your request

Connection timeout:

1. Check SSH tunnel is active
2. Verify remote Xdebug port matches local port (9003)
3. Test port forwarding: ssh -R 9003:localhost:9003 wsm.my_workspace "nc -zv 127.0.0.1 9003"

Other Languages

Similar remote interpreter/SDK configuration available for:

• Java/Kotlin (IntelliJ IDEA)
• Ruby (RubyMine)
• Go (GoLand)
• C/C++ (CLion)

Port Forwarding

JetBrains IDEs automatically handle port forwarding for remote development:

1. When you run a web server or service on the remote workspace
2. The IDE detects the port and offers to forward it
3. Click the notification to open in your local browser
4. Access remote services as if they were local

You can also manually configure port forwarding:

• Tools → Deployment → Configuration → SSH tab
• Add port forwarding rules as needed

See Port Forwarding documentation for more details.

File Sync Best Practices

• Enable automatic upload: Ensures remote files stay in sync
• Use explicit save: Prevents excessive sync operations
• Review sync conflicts: Check for conflicts before overwriting
• Sync before running: Ensure latest code is deployed before execution

Troubleshooting

Cannot Connect to Remote Host

Symptoms: Connection timeout or refused

Solutions:

1. Verify workspace is running in WSM dashboard
2. Test SSH connection from terminal: ssh wsm.my_workspace
3. Update SSH config: wsm-cli ssh config-update
4. Check firewall settings
5. Verify SSH key is added to WSM profile

Authentication Failed

Symptoms: Permission denied (publickey)

Solutions:

1. Verify SSH key path in IDE settings
2. Check key permissions: chmod 600 ~/.ssh/id_ed25519
3. Ensure key is added to WSM profile
4. Test key with: ssh -i ~/.ssh/id_ed25519 wsm.my_workspace
5. Check SSH agent is running: ssh-add -l

Files Not Syncing

Symptoms: Changes not appearing on remote workspace

Solutions:

1. Check automatic upload is enabled
2. Manually upload: Right-click → Deployment → Upload
3. Review excluded paths in deployment settings
4. Check deployment logs: Tools → Deployment → View Deployment Logs
5. Verify path mappings are correct

Port Forwarding Not Working

Symptoms: Cannot access remote web services

Solutions:

1. Verify service is running on remote workspace
2. Check port forwarding settings in deployment configuration
3. Manually add port forwarding rule
4. Test port forwarding from terminal: ssh -L 8080:localhost:8080 wsm.my_workspace
5. Check firewall rules on workspace

Gateway Connection Issues

Symptoms: Cannot establish connection

Solutions:

1. Ensure SSH connection works from terminal first
2. Verify workspace has sufficient resources
3. Check network connectivity and firewall settings

Slow Performance

Symptoms: IDE is sluggish, file operations are slow

Solutions:

1. Exclude large directories from sync (node_modules, build, etc.)
2. Use Gateway instead of file sync for large projects
3. Disable unnecessary plugins
4. Increase IDE memory: Help → Change Memory Settings
5. Check network latency to workspace

Host Key Verification Failed

Symptoms: Host key has changed warning

Solutions:

1. Remove old host key: ssh-keygen -R wsm.my_workspace
2. Reconnect and accept new host key
3. Update known_hosts file
4. Verify workspace hasn’t been recreated (new host key)

Advanced Configuration

Custom SSH Options

Add custom SSH options in deployment configuration:

1. Go to Settings → Deployment → Configuration
2. Select your deployment → SSH tab
3. Add custom SSH options as needed

Multiple Workspaces

Configure multiple deployment configurations for different workspaces:

1. Create separate deployment configurations for each workspace
2. Set one as default for automatic operations
3. Switch between configurations as needed
4. Use different run configurations for different workspaces

Shared Team Settings

Share deployment configurations with your team:

1. Export deployment settings: File → Manage IDE Settings → Export Settings
2. Commit .idea/deployment.xml to version control (remove sensitive data)
3. Team members import settings or check out from VCS

Related Documentation

• SSH Access - Configure SSH keys and connection
• Connecting Visual Studio Code - VS Code remote development
• Port Forwarding - Forward ports from workspaces
• File Sync with rsync - Alternative file synchronization

Additional Resources

• JetBrains Remote Development Documentation
• SSH Deployment Guide