# Attach to a remote process

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

RubyMine enables you to attach to a running process on a local or remote computer. This capability allows you to debug applications that cannot be launched directly from the IDE.

In this topic, we’ll use this capability to debug a [sample Rails application](https://github.com/JetBrains/sample_rails_app) running on a remote machine.

## 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). Note that [GDB](https://www.gnu.org/software/gdb/) should also be installed on a remote machine. In our tutorial, the remote computer has the `sample-web-server` name. > **Tip:** > For the remote macOS machine, [LLDB](http://lldb.llvm.org) should be installed.

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

## Clone and run a remote application

First of all, we need to clone and run the [sample application](https://github.com/JetBrains/sample_rails_app) on a remote machine. To do this, [connect to a remote machine](running-ssh-terminal.html#start_ssh_session) and use instructions from the [Getting started](https://github.com/JetBrains/sample_rails_app#getting-started) chapter. After performing the required steps, use the `rails server` command to run an application:

![Remote session](https://resources.jetbrains.com/help/img/idea/2026.3/rm_remote_attach_mac_console.png)

## Clone a project on a local machine

After running the sample application on a remote machine, launch RubyMine and open the same application on a local machine using this instruction: [Check out a project from a remote host (git clone)](set-up-a-git-repository.html#clone-repo). In URL, insert the following address: `https://github.com/JetBrains/sample_rails_app.git`. Then click Clone.

![Get from Version Control dialog](https://resources.jetbrains.com/help/img/idea/2026.3/rm_get_started_get_from_version_control_dialog.png)

## 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.

## Attach to a remote process

Now we are ready to debug a remote application.

Procedure:

1. Open the `users_controller.rb` file and set a breakpoint within the create method next to the line where a new user is created.

![Set a breakpoint](https://resources.jetbrains.com/help/img/idea/2026.3/rm_get_started_debug_breakpoint.png)

2. Click Run in the main menu and select the Attach to Process… command.

3. In the invoked dialog, select the remote connection in the SSH group (sample-web-server@22 in our case) and choose the puma process:

![Attach to remote process](https://resources.jetbrains.com/help/img/idea/2026.3/rm_remote_attach_process.png)

The Console tab will display the debugger output:

![Debug console](https://resources.jetbrains.com/help/img/idea/2026.3/rm_remote_attach_debugger_console.png)

## Debug an application

To debug an application, open the browser on a local machine and specify the application address. In our case, it will be `http://sample-web-server:3000`.

![Sign up page](https://resources.jetbrains.com/help/img/idea/2026.3/rm_remote_attach_browser_signup.png)

Click the Sign up now! button. On the Sign up page, enter the required user parameters and click Create my account.

![User credentials](https://resources.jetbrains.com/help/img/idea/2026.3/rm_get_started_debug_enter_credentials.png)

The debugger   [pauses](starting-the-debugger-session.html#pause-resume-debugger) its session on a breakpoint and enables you to [examine](examining-suspended-program.html) the remote application state.

![Debugging a remote application](https://resources.jetbrains.com/help/img/idea/2026.3/rm_remote_attach_debugger.png)

For instance, you can check user parameters specified on the Sign up page.

## Troubleshooting

If you encounter any issues on an attempt to attach to a process, try the following solutions:

* Make sure that the remote application is run with the same Ruby interpreter as [configured](#configure_remote_interpreter) for a debugged project.

* Try to increase the debug connection timeout. To do this, 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 Build, Execution, Deployment | Debugger page, and use the Debug connection timeout option.

