Cline SSH Remote: Setup Guide for Cline Desktop (2026)

On September 17, 2026, Cline Desktop v0.0.31 shipped a feature that changes where the coding agent actually works: SSH remotes. Ten days later, v0.0.37 (September 26) put "SSH remotes" at the top of a brand-new What's-new dialog — which is why searches for cline ssh remote are spiking right now. The one-line pitch, straight from the official docs: "The app stays on your computer; the agent, its tools, and your code live on the remote machine."

That split is the whole point. Your laptop keeps the chat UI, the approval buttons, and the live output; a dev box, build server, or cloud VM does the editing, the terminal commands, and the git work. If your project already lives on a Linux server — or your laptop is a 13-inch compromise while the real hardware sits elsewhere — this cline remote setup guide is for you. Below: how the architecture works, what you need, the full walk-through in Settings → Remote, jump-host configuration, the six errors you will actually hit, and how it compares with VS Code Remote-SSH. Everything is sourced to Cline's docs and GitHub release notes; where a detail isn't printed, we say so instead of guessing.

Quick answer

• What it is: a local-UI / remote-execution split for Cline Desktop. File edits, terminal commands, Git, and MCP servers execute on the remote host; chat, approvals, and live output stay in the desktop app.
• Since when: first shipped in Cline Desktop v0.0.31 on September 17, 2026. The v0.0.37 update (September 26) didn't introduce it — it re-highlighted it in the new What's-new dialog. Get both dates right and most tutorial-grade confusion disappears.
• What you need: key-based SSH login to a Linux (x64/arm64) or macOS host, already trusted by your machine. No root access, no npm, no open ports — Cline copies a self-contained helper (~30 MB on Linux) to the host over your existing SSH connection.
• How to connect: get passwordless ssh working in a terminal, then in Cline: Settings → Remote → New Host → Test Connection, and pick the host from the environment selector on the new-session screen. About two minutes, start to finish.
• Biggest limits: password authentication is never offered (keys only), one host at a time, Windows hosts are unsupported, and a network drop closes the tunnel after about 45 seconds.

The architecture: UI on your desk, execution on the host

Most "remote development" stories are really "move your whole IDE to the server" stories. Cline Desktop's SSH remote takes the other cut, and the docs page is explicit about the boundary: "file edits, terminal commands, Git, and MCP servers all execute remotely, while the chat, approvals, and live output stay in the app."

What runs where:

The mechanics are lighter than you'd expect. On first connect, Cline copies "a small self-contained helper" to ~/.cline/remote/ on the host — roughly 30 MB on Linux, cached per Cline version — starts it, and talks to it through an SSH tunnel. The docs' list of what that spares you: "No apt, npm, root access, or open ports are needed."

A few design details worth knowing before you trust it with a server:

• Nothing is exposed on the network. The helper starts a Cline Hub bound to the host's loopback interface; the app forwards it locally via ssh -L, "so nothing on the host is exposed to the network."
• It drives your system ssh with BatchMode=yes and StrictHostKeyChecking=yes — meaning it reuses the keys, config, and known-hosts trust you already have, and refuses to bypass prompts rather than working around them.
• Your API key is not parked on the server. The key/token "is sent to the host for the session over the authenticated tunnel; it is not written to the remote machine's provider settings."
• It won't touch an existing Cline CLI install. If the same account runs the Cline CLI on that host, the remote helper spins up its own isolated Hub instead.
• Host metadata is stored locally at ~/.cline/data/settings/remote-environments.json (mode 0600) and holds an identity-file path — never key contents — per the v0.0.31 release notes.

What you need before connecting

The prerequisites are short:

• Cline Desktop on macOS, Windows, or Linux. (If you're starting from zero, our Cline Desktop tutorial covers the app itself.)
• A local SSH client — ssh -V confirms it. It's built into macOS, Linux, and Windows 10/11.
• A remote machine running Linux (x64 or arm64) or macOS. Connecting to a Mac as the host requires running Cline Desktop on a Mac.
• Key-based login, with the host already trusted. Cline never shows password prompts or host-key questions.
• Not supported: Windows hosts, and 32-bit Raspberry Pi OS.

Step 1: get passwordless SSH working first

This is the one-time part, done in your own terminal — and it's the part that prevents 90% of the errors people hit later. From the docs:

1. ssh-keygen -t ed25519 — skip if ~/.ssh/id_ed25519 already exists.
2. ssh-copy-id dev@dev.example.com — the only time you'll type a password. (On Windows, pipe the key into authorized_keys with PowerShell.)
3. ssh dev@dev.example.com and type yes once to trust the host fingerprint.

The docs' one-line test: "if ssh dev@dev.example.com puts you on the remote machine with no password prompt and no yes/no question, Cline can connect." If that fails, fix it here — nothing you configure inside Cline will paper over a broken SSH login.

Step 2: add the host under Settings → Remote

In Cline Desktop: Settings → Remote → New Host. The fields:

Click Test Connection — a green "Passed" badge confirms the settings, and testing also saves the host. One quirk the docs call out: "Saving or testing a host does not connect to it." The real connection happens in the next step.

Step 3: connect, open a folder, work

Back on the new-session screen, click the environment selector — the laptop icon to the left of the workspace picker — and choose your host under Remote. The first connect uploads the helper to the host; then use Open folder… to pick a project on the remote machine. Recent workspaces are remembered per host.

From here, work as usual: every tool call executes on the host as your SSH user, and the chat streams approvals and output back to your desktop. To go back to local, pick Local in the same selector — the docs say that "disconnects, stops the helper on the host, and leaves it cached," so reconnecting is fast.

Jump hosts and proxies: ProxyJump is the way

If your server sits behind a bastion — or you only have an HTTP/SOCKS proxy — note that Cline's SSH layer ignores your system's HTTP(S) proxy settings; it's plain SSH underneath. The documented route is to define an alias in ~/.ssh/config:

• Jump host (bastion): use the ProxyJump directive to chain through the bastion.
• HTTP/SOCKS proxy: use ProxyCommand with nc. On Windows, the docs point to connect.exe from Git for Windows instead of nc.

Then use that alias as the SSH host field in Cline. The connection logic — including the tunnel — flows through the same path your terminal SSH would.

Troubleshooting: the six errors you will actually hit

All from the official troubleshooting list:

Pattern worth internalizing: Cline does not create SSH auth, it consumes it. Every one of these is fixed at the terminal layer first.

Limits to know before you rely on it

• Key-based login only. "Password prompts are never shown" — if your server only allows password auth, set up keys first.
• Trust must already exist. Cline rejects unknown or changed host keys rather than prompting; the trust-on-first-use moment happens in your terminal.
• One host at a time. No multi-host sessions in the current build.
• Two things don't work remotely yet: attaching local files to a message, and opening a remote file in a local editor.
• Network drop kills the session. The tunnel closes "after about 45 seconds" of disconnection; reconnect by reselecting the host. Unsaved in-flight work is your responsibility — same as any SSH session.

Timeline: v0.0.31 shipped it, v0.0.37 put it back in the spotlight

A lot of coverage conflates the two dates, so here's the clean sequence from the release notes:

• v0.0.31 (Sep 17, 2026) — SSH remote ships: "Add and test a host under Settings → Remote, then pick it from the environment selector beside the workspace picker on the welcome screen." The same release made parallel sub-agents concurrent — "delegating three independent pieces of work takes as long as the slowest one." Mac hosts at this point required a locally built helper via CLINE_REMOTE_HELPER_BINARY.
• v0.0.34 (Sep 22) — Mac-to-Mac connections: "You can now connect to a Mac as an SSH remote from a Mac," with a signed helper for Apple Silicon and Intel hosts.
• v0.0.36 (Sep 25) — SSH settings polish: Save is disabled until a saved host changes, and the new-host button is renamed Add.
• v0.0.37 (Sep 26) — a new About page (version, update channel, Check for updates) and a one-time What's new dialog after updates. Its first edition is why you're reading this: "The first one covers SSH remotes, worktrees, pull request status in the composer, and parallel sub-agents." It stays viewable via Highlights on the About page.

So: if a post told you SSH remote is "the v0.0.37 feature," it's off by ten days and one version. v0.0.37 is the megaphone, not the feature.

What else came in that batch

The What's-new dialog groups four things, and two of them pair naturally with SSH remote:

• Parallel sub-agents. Per the subagents docs, Cline can "spawn focused research agents that run in parallel," each with "its own prompt and context window," which explore the codebase read-only — file reads, search, ls, grep, git log, git diff — and "return a detailed report to the main agent" without filling its context. They can't edit files, browse, touch MCP servers, or search the web, and the feature is labeled experimental. It's enabled by default (via the use_subagents tool; disable it under Settings → Features → Agent). Since all tool execution runs on the host during an SSH remote session, subagent exploration works against the remote checkout — a good pairing for large repos on beefy dev boxes.
• Worktrees. Git worktrees let you check out several branches side by side; the v0.0.35 notes show worktree-aware behavior already in place (slash-menu plugin commands follow "the conversation's own workspace (including worktrees)"). We did not find a dedicated docs page for the full worktree feature set, so treat specifics as still evolving — that's our honest line, not a complaint.
• PR status in the composer. Listed in the What's-new dialog; no dedicated docs page we could verify yet, so we won't describe mechanics we haven't seen.

Cline SSH remote vs VS Code Remote-SSH and terminal agents

The obvious benchmark is Microsoft's. Per VS Code's docs, Remote-SSH "runs commands and other extensions directly on the remote machine" and "will install VS Code Server on the remote OS." So the two agree on the core principle — code and execution on the host — and differ elsewhere:

And the third way: terminal agents (Claude Code, Codex CLI, the Cline CLI) run inside an SSH session in tmux — the interface itself lives on the server. Cline Desktop's SSH remote inverts that: the GUI and its approval buttons stay on your desk, execution happens remotely. If you live in an editor, Remote-SSH plus Cline's editor extension (our Cline tutorial covers the editor route) remains the natural setup; if you prefer Cline Desktop's chat-first workflow but your code is on a server, this feature exists precisely for you.

Honest notes

• The docs page prints no version numbers. Every version fact in this post comes from the GitHub release notes (v0.0.31, v0.0.34, v0.0.36, v0.0.37), linked inline.
• Worktrees and PR-status-in-composer have no dedicated docs pages that we could find; we've described only what the What's-new dialog and release notes state. These may get their own documentation — check the current docs if you're reading this later.
• We didn't lab-test every platform combination. Host-support statements (Linux x64/arm64, macOS-from-macOS, no Windows hosts) are the docs', not our benchmark results.
• Latency and performance characteristics are unstated by the official docs; your experience will depend on the link between your desk and the host.

FAQ

Does Cline Desktop support SSH remote development — and since when?

Yes. SSH remotes first shipped in Cline Desktop v0.0.31 on September 17, 2026, under Settings → Remote. The v0.0.37 release on September 26 added the About page and a What's-new dialog that re-highlighted the feature alongside worktrees, PR status, and parallel sub-agents. If your desktop app is older than v0.0.31, update it; the What's-new dialog itself requires v0.0.37.

How do I connect Cline to a remote server over SSH?

Three steps. First, get passwordless SSH working from your terminal: generate a key (ssh-keygen -t ed25519), copy it (ssh-copy-id user@host), and log in once manually to trust the fingerprint. Second, in Cline Desktop go to Settings → Remote → New Host, fill in host/user/port/identity file, and hit Test Connection until you see "Passed." Third, on the new-session screen click the environment selector, pick your host under Remote, and open a remote folder. File edits, terminal commands, Git, and MCP servers then execute on the server while chat and approvals stay local.

Can Cline's SSH remote use password authentication?

No. The docs are categorical: "Password prompts are never shown." Key-based login only, with the host already trusted. If you currently type a password to reach the server, run ssh-copy-id once — and if your key has a passphrase, load it with ssh-add first so the agent can use it non-interactively.

Does it work behind a jump host or bastion server?

Yes, through SSH's own machinery rather than any Cline setting. System HTTP(S) proxies are ignored; define a ~/.ssh/config alias with ProxyJump for bastion chaining (or ProxyCommand with nc for HTTP/SOCKS proxies — connect.exe from Git for Windows on Windows machines), test the alias from your terminal, then use the alias as the SSH host in Cline.

Cline SSH remote vs VS Code Remote-SSH — which should I use?

They solve the same half of the problem — your code and execution live on the host — with different local experiences. VS Code Remote-SSH installs VS Code Server on the remote and gives you the full editor remotely; Cline Desktop's SSH remote drops a ~30 MB helper with no root or npm and keeps a chat-style agent UI local, with approvals as native prompts. Editor-first workflows: Remote-SSH. Agent-first workflows where you want the desktop app's chat and approvals while a server does the compiling: Cline's SSH remote. Running both against the same host is fine — they install separate, unrelated components.

Related reading

• Cline Desktop tutorial — the app this feature lives in, step by step
• Cline tutorial for beginners — Plan/Act, rules, and the editor-side workflow
• Best local model for Cline — run models on your own hardware, which pairs naturally with a home dev box
• DeepSeek + Cline tutorial — wire free DeepSeek models into Cline