# Debug an application using 'Ruby remote debug'

> For the complete documentation index, see [llms.txt](https://www.jetbrains.com/help/ruby/2026.3/llms.txt).

RubyMine offers you two ways to debug applications that are run on the remote machine:

* Add a [remote Ruby interpreter](configuring-language-interpreter.html#add_remote_ruby_interpreter), configure mappings between files of the local and remote project, and [start a debugging session](starting-the-debugger-session.html).

* Run the application on the remote machine, add a remote Ruby interpreter, configure mappings, and [attach to a running process](attaching-to-remote-process.html).

The specified ways may not suit for debugging some projects, for example, [SketchUp](https://github.com/SketchUp/sketchup-ruby-api-tutorials/wiki/RubyMine-Debugger-Setup). In such cases, you can use the Ruby remote debug run/debug configuration.

In this tutorial, we'll show you how to debug a [sample Rails application](https://github.com/JetBrains/sample_rails_app) using Ruby remote debug.

## Prerequisites

In this tutorial, we'll use two machines to demonstrate debugging of the remote application:

* Local machine: Mac with macOS, with RubyMine [installed](installation-guide.html).

* Remote machine: The Ubuntu machine with enabled [SSH access](running-ssh-terminal.html#set_up_ssh) and the Ruby interpreter [installed](set-up-a-ruby-development-environment.html#ruby). In our tutorial, the remote computer has the `sample-web-server` name.

On both machines, we’ll use the jetbrains user’s home directories to store source code.

## Create the 'Ruby remote debug' configuration

At first, let's create and set up the Ruby remote debug configuration in RubyMine:

Procedure:

1. Go to `Run | Edit Configurations` in the main menu, click ![the Add icon](https://resources.jetbrains.com/help/img/idea/2026.3/app.expui.general.add.svg), and select Ruby remote debug from the list.

2. Specify the following settings:

![Ruby remote debug](https://resources.jetbrains.com/help/img/idea/2026.3/rm_ruby_remote_debug_example.png)

* Name: Enter a run/debug configuration name. Example: Remote debug: sample_rails_app

* Remote host: Specify a hostname or IP address of the remote machine. Examples: `sample-web-server`, `172.30.163.90`

* Remote port: Specify a remote port used to establish a connection between the IDE and debugger. Example: 1234

* Remote root folder: Specify a root folder on the remote machine, where the application to be debugged is located. Example: `/home/jetbrains/apps/sample_rails_app`

* Local port: Specify a local port used to establish a connection between the IDE and debugger. Example: 26162

* Local root folder: Specify an application's root folder on the local machine. Example: `/Users/jetbrains/RubymineProjects/sample_rails_app`

3. After you've specified all the settings, copy the command generated in the Server command field to the clipboard.

```SHELL
rdebug-ide --host 0.0.0.0 --port 1234 --dispatcher-port 26162 -- $COMMAND$
```

It will be used later to [start the debugger](#start_debug_remote) on a remote machine. The $COMMAND$ part will be replaced with the actual command for running the application.

Click OK in the Run/Debug Configurations dialog.

## Configure a remote interpreter

In this part, we’ll configure a remote interpreter using SSH.

Procedure:

1. Open the Settings dialog `Ctrl+Alt+S` (Windows), `⌘ Comma` (macOS), `⌘ Comma` (IntelliJ IDEA Classic (macOS)), `⌘ Comma` (macOS System Shortcuts), `Ctrl+Alt+S` (XWin), `Ctrl+Alt+S` (GNOME), `Ctrl+Alt+S` (KDE), `Ctrl+Alt+S` (Emacs), `Ctrl+Alt+S` (Sublime Text), `⌘ Comma` (Sublime Text (macOS)), `Ctrl+Alt+S` (Visual Studio), `⌘ Comma` (Visual Studio (macOS)), `Meta+Comma` (TextMate), `Ctrl+Alt+S` (NetBeans), `Ctrl+Alt+S` (Eclipse), `⌘ Comma` (Eclipse (macOS)), go to the Language & Frameworks | Ruby Interpreters page, click the ![Add](https://resources.jetbrains.com/help/img/idea/2026.3/app.expui.general.add.svg) button and select Remote Interpreter or Version Manager from the list:

![New remote](https://resources.jetbrains.com/help/img/idea/2026.3/rm_add_remote_ruby_interpreter.png)

2. In the invoked dialog, select SSH Credentials and specify parameters in the following way:

![Configure Remote Ruby Interpreter](https://resources.jetbrains.com/help/img/idea/2026.3/rm_remote_attach_ssh_credentials.png)

* SSH configuration: Click the ellipsis button to create an [SSH configuration](running-ssh-terminal.html#add_ssh_config) for connecting to a remote machine.

* Ruby or version manager path: Here you should specify the path to the Ruby interpreter or the [version manager](ruby-version-managers.html) executable. In this tutorial, we use rbenv on a remote machine.

After you have specified all the settings, click OK.

3. If you specified a path to the version manager executable in the previous dialog, RubyMine suggests selecting the required Ruby interpreter. In this step, you need to choose the interpreter used to run a remote application.

Click OK and select the added interpreter in the Ruby Interpreters page.

![Ruby Interpreters](https://resources.jetbrains.com/help/img/idea/2026.3/rm_remote_attach_select_remote_sdk.png)

4. The final thing you need to do is to specify mappings between files of a local and remote project. To do this, click the Edit Path Mappings ![Edit Path Mappings](https://resources.jetbrains.com/help/img/idea/2026.3/app.vcs.folders.svg) button. In the Edit Project Path Mappings dialog, specify the local and remote project root paths.

![Edit Project Path Mappings](https://resources.jetbrains.com/help/img/idea/2026.3/rm_remote_attach_path_mappings.png)

> **Tip:**
> If necessary, you may specify not project root paths but only folders containing sources required for debugging.

In our case, the paths will look as follows:

* Local Path: `/Users/jetbrains/RubymineProjects/sample_rails_app`

* Remote Path: `/home/deploy/sample_rails_app`

Click OK in this dialog and then click OK in the Settings dialog. Now we are ready to attach to a remote process and debug the application.

## Start debugging on the remote machine

In this part, we'll install the debugging gems and start a debugging session on the remote machine.

Procedure:

1. (Optional) RubyMine allows you to [debug](debugging-code.html) Rails applications with Spring. This may require updating a system or project Spring configuration file to load the debugger into every process [forked](https://github.com/rails/spring#running-code-after-forking) by Spring. To do this, add the following code to `~/.spring.rb` or `config/spring.rb` file:

```RUBY
Spring.after_fork do
    if ENV['DEBUGGER_STORED_RUBYLIB']
        ENV['DEBUGGER_STORED_RUBYLIB'].split(File::PATH_SEPARATOR).each do |path|
            next unless path =~ /ruby-debug-ide/
            load path + '/ruby-debug-ide/multiprocess/starter.rb'
        end
    end
end
```

2. Install the debugging gems to the target Ruby interpreter. To do this, add the debase and ruby-debug-ide to the `Gemfile` and run `bundle install`.

```RUBY
gem 'debase'
gem 'ruby-debug-ide'
```

3. Go to the application's folder and run it with the debugger attached using the following command.

```SHELL
rdebug-ide --host 0.0.0.0 --port 1234 --dispatcher-port 26162 -- bin/rails s
```

> **Tip:**
> If you want to debug a plain Ruby script, the command will look in the following way:
>
>
>
>
>
>
> ```
> rdebug-ide --host 0.0.0.0 --port 1234 --dispatcher-port 26162 -- lib/script.rb
> ```

## Start debugging on the local machine

Now we are ready to start debugging in the IDE.

Procedure:

1. Set the [breakpoints](using-breakpoints.html#set-line-breakpoint) in your application.

2. Run the debugging session. To do this, press `Ctrl` (Windows), `Ctrl` (macOS), `Ctrl` (IntelliJ IDEA Classic (macOS)), `Ctrl` (macOS System Shortcuts), `Ctrl` (XWin), `Ctrl` (GNOME), `Ctrl` (KDE), `Ctrl` (Emacs), `Ctrl` (Sublime Text), `Ctrl` (Sublime Text (macOS)), `Ctrl` (Visual Studio), `Ctrl` (Visual Studio (macOS)), `Ctrl` (TextMate), `Ctrl` (NetBeans), `Ctrl` (Eclipse), `Ctrl` (Eclipse (macOS)) twice and type the configuration name (Remote debug: sample_rails_app) in the popup. Press and hold down the `Shift` (Windows), `Shift` (macOS), `Shift` (IntelliJ IDEA Classic (macOS)), `Shift` (macOS System Shortcuts), `Shift` (XWin), `Shift` (GNOME), `Shift` (KDE), `Shift` (Emacs), `Shift` (Sublime Text), `Shift` (Sublime Text (macOS)), `Shift` (Visual Studio), `Shift` (Visual Studio (macOS)), `Shift` (TextMate), `Shift` (NetBeans), `Shift` (Eclipse), `Shift` (Eclipse (macOS)) key (the dialog title changes to Debug) and press `Enter` (Windows), `⏎` (macOS), `⏎` (IntelliJ IDEA Classic (macOS)), `⏎` (macOS System Shortcuts), `Enter` (XWin), `Enter` (GNOME), `Enter` (KDE), `Enter` (Emacs), `Enter` (Sublime Text), `⏎` (Sublime Text (macOS)), `Enter` (Visual Studio), `⏎` (Visual Studio (macOS)), `Enter` (TextMate), `Enter` (NetBeans), `Enter` (Eclipse), `⏎` (Eclipse (macOS)).

