CLion Remote Development over SSH: Toolchains, CMake Sync, and GDB Debugging

If your build target is a Linux box (a server, a VM, or a beefy build machine) but you edit on Windows or macOS, CLion's remote toolchain lets you keep the IDE local while CMake, the compiler, and GDB all run on the remote host. The short version: define an SSH configuration, attach a Remote Toolchain to it, point a CMake profile at that toolchain, and CLion uploads your sources, configures the project remotely, and tunnels a debug session back to your local editor. This works in CLion 2023.1 and later; verify your version under Help → About before starting.

How the pieces fit together

CLion keeps three things separate: the SSH connection (host, credentials), the toolchain (paths to CMake, compiler, debugger on the remote machine), and the CMake profile (build type, generator, which toolchain to use). When you build, CLion syncs your project root to ~/.clion/<project> on the remote host, runs CMake there, and compiles with the remote compiler. Build artifacts and the CMake cache never touch your local disk.

Setting up the SSH configuration and toolchain

First, set up key-based SSH authentication to the remote host. Password auth tends to break automatic uploads and CMake re-runs because of interactive prompts, so use an agent or an unencrypted key if your policy allows.

1. Open Settings → Build, Execution, Deployment → Deployment → SSH Configurations and add your host, user, and key. Use the Test Connection button.
2. Go to Settings → Build, Execution, Deployment → Toolchains, click +, and choose Remote. Select the SSH config you just created.
3. CLion usually auto-detects remote CMake, gcc/g++, and GDB. If the remote CMake lives in a custom prefix (common on older distros like CentOS 7, whose system CMake is below CLion's 3.10 minimum), enter the full path manually, e.g. /opt/cmake-3.28/bin/cmake.
4. Check the toolchain's reported versions in the same dialog — CLion flags missing or too-old tools there.

Mapping a CMake profile to the remote toolchain

Under Settings → Build, Execution, Deployment → CMake, add a new profile and set its Toolchain to the remote one. Give it a distinct build directory so it never collides with a local profile:

Name: Debug-Remote
Build type: Debug
Toolchain: Remote (your SSH host)
Build directory: cmake-build-debug-remote

Separate build directories matter. A CMake cache records absolute paths and compiler locations; reusing one directory across local and remote profiles produces confusing "compiler changed" errors or silently wrong artifacts.

To keep sources in sync, enable Settings → Build, Execution, Deployment → Deployment → Options → "Upload changed files automatically to the default server". On large projects or slow links, leave this off and trigger Tools → Deployment → Sync with Deployed manually instead. Either way, exclude build directories and generated code under Deployment → Excluded Paths — syncing 50k files of generated output on first upload is the most common cause of a seemingly hung setup.

Debugging on the remote host

No extra configuration is needed for a normal run configuration. Set breakpoints, press Debug, and CLion starts gdbserver on the remote host, then connects your local GDB client through an SSH tunnel. Variables, watches, and call stacks appear in the Debug tool window as usual.

For embedded targets, combine the remote toolchain with a Custom GDB Server run configuration: run OpenOCD on the remote host, forward its GDB port over SSH (ssh -L 3333:localhost:3333 user@host from a local terminal), and point the run configuration at localhost:3333.

Verifying it actually went remote

• Build tool window: compile commands should reference remote paths (e.g. /home/user/.clion/...), not local ones.
• On the remote host, check ~/.clion/<project>/cmake-build-debug-remote/ for CMakeCache.txt and compile_commands.json.
• Tools → Deployment → Browse Remote Host shows the uploaded tree; confirm excluded paths are absent.
• Hit a breakpoint and confirm execution stops with a populated Variables view.

Limits and common mistakes

Line endings. CRLF endings uploaded from Windows can trigger odd compiler warnings on Linux. Configure Git with LF checkouts or enable line-separator conversion in Deployment options.

Non-standard sysroots. Symbol resolution for system headers depends on remote include paths. Cross-compilation sysroots need to be declared via CMAKE_SYSROOT in your CMakeLists or added to the toolchain's include directories.

Old remote CMake. Anything below 3.10 is rejected. Install a newer CMake in a custom prefix on the remote host and reference it explicitly in the toolchain.

Remote Development Gateway. CLion 2024.2 added a beta Gateway mode that runs a headless IDE backend on the remote host, which reduces latency on very large codebases. It requires a JetBrains Gateway license, does not yet support every plugin (some static analyzers are absent), and may need JVM tuning on the remote host. Treat it as a preview: verify your critical plugins before committing a team to it.

One caveat: menu paths and the Gateway feature set shift between releases. Confirm the exact labels and supported versions against your installed build (Help → About) before writing team documentation around them.