Remote Development over SSH

Cline Desktop can work on a machine other than the one it is installed on. You add an SSH host once, pick it from the environment selector, and every session you start runs on that host: file edits, terminal commands, Git, and MCP servers all execute remotely, while the chat, approvals, and live output stay in the app on your computer.

You do not install anything on the remote machine. On first connect, Cline copies a small self-contained helper to ~/.cline/remote/ on the host, starts it, and talks to it through an SSH tunnel. No apt, npm, root access, or open ports are needed.

What you need

• Cline Desktop on macOS, Windows, or Linux.
• An SSH client on your computer. macOS, Linux, and Windows 10/11 include one; open a terminal and run ssh -V to confirm.
• A remote machine running Linux (x64 or arm64) or macOS that you can reach over the network, with an account on it. Connecting to a Mac requires running Cline Desktop on a Mac. Windows hosts and 32-bit Raspberry Pi operating systems are not supported.
• Key-based login to that machine, with the host already trusted by your SSH client. The next section walks through both.

SSH in two minutes

SSH is a secure way to run commands on another computer. Two things have to be true before Cline can use it. Cline runs ssh in the background with no way to answer prompts, so both must be set up ahead of time from a normal terminal.

Create a key pair (once per computer)

Instead of a password, SSH can prove who you are with a pair of files: a private key that stays on your computer and a public key you hand to servers. If you already have ~/.ssh/id_ed25519, skip this step.

ssh-keygen -t ed25519

Press Enter to accept the default location. You can leave the passphrase empty, or set one and add the key to your SSH agent (see Troubleshooting).

Install your public key on the remote machine

This is the one time you will type the account's password. Replace dev with your username on the remote machine and dev.example.com with its hostname or IP address.

macOS / Linux

ssh-copy-id [email protected]

Windows (PowerShell)

type $env:USERPROFILE\.ssh\id_ed25519.pub | ssh [email protected] "mkdir -p ~/.ssh && cat >> ~/.ssh/authorized_keys"

Cloud providers usually do this for you when you create a VM: the key you chose in their console is already installed, so you may only need step 3.

Log in once and trust the host

ssh [email protected]

The first time you connect to any machine, SSH shows its fingerprint and asks Are you sure you want to continue connecting (yes/no)?. Type yes. SSH remembers the fingerprint in ~/.ssh/known_hosts so it can detect if someone swaps the server out later.

You should land in a shell on the remote machine without being asked for a password. Type exit to come back.

Step 1: Add the host in Cline

Open Settings → Remote and click New Host.

Fill in the form:

Click Test Connection. Cline logs in over SSH and reports the host's platform. A green Passed badge means your key and host trust are set up correctly. Testing also saves the host to the list on the left.

Step 2: Connect and open a project

Go back to the new-session screen. The environment selector is the small laptop icon to the left of the workspace picker. It shows Local by default. Click it and choose your host under Remote.

The first connection takes a few seconds while Cline uploads its helper to the host. Once connected, the icon changes to a server and the workspace picker shows your remote home directory. Open the workspace picker and choose Open folder... to browse the remote machine and pick a project, then click Use this folder.

Cline remembers recent workspaces separately for each host, so on later connections the project appears in the picker's list.

Step 3: Work as usual

Start a session the same way you would locally. Every tool call runs on the remote machine as the SSH user, in the folder you picked.

Everything that runs on the host:

• Reading, searching, and editing files, and @-mentioning them
• Terminal commands and Git operations, including switching branches
• MCP servers and other tools configured on that machine (the helper picks up the remote login shell's PATH, so tools installed under your account are visible)
• Session history, which is stored on the host

Everything that stays on your computer:

• The chat, approvals, and live streaming output
• Your provider settings. The current API key or access token is sent to the host for the session over the authenticated tunnel; it is not written to the remote machine's provider settings

To go back to your own machine, open the environment selector and choose Local. This disconnects, stops the helper on the host, and leaves it cached in ~/.cline/remote/ for a faster reconnect.

Behind a proxy or jump host

SSH does not use your system's HTTP(S) proxy, even when the rest of Cline Desktop does. If the host is only reachable through a proxy or a bastion, tell your SSH client how to get there and Cline follows along, because it runs your own ssh and reads your ~/.ssh/config.

Define an alias with the route, then enter the alias in the SSH host field:

# Through a bastion (jump host)
Host build-box
  HostName 10.0.4.12
  User dev
  ProxyJump [email protected]

# Through an HTTP proxy (macOS / Linux, using netcat)
Host build-box-via-proxy
  HostName dev.example.com
  User dev
  ProxyCommand nc -X connect -x proxy.example.com:3128 %h %p

# Through a local SOCKS proxy such as Clash or v2ray
Host build-box-via-socks
  HostName dev.example.com
  User dev
  ProxyCommand nc -X 5 -x 127.0.0.1:7890 %h %p

%h and %p expand to the host and port. On Windows, nc is not included; use connect.exe from Git for Windows instead, for example ProxyCommand connect -H proxy.example.com:3128 %h %p.

Test it from a terminal first: ssh build-box should log you in with no prompts. Then add build-box as the SSH host in Cline and leave User and Port blank so the alias supplies them.

Limitations

• Key-based login only. Password prompts are never shown, so password-only accounts cannot connect.
• The host must already be trusted. Cline refuses unknown or changed host keys rather than prompting. Log in once from a terminal first.
• Remote hosts: Linux x64 and arm64, and macOS when Cline Desktop is running on a Mac. Windows hosts are not supported.
• One host at a time. Switching hosts disconnects from the current one.
• Not available in remote sessions yet: attaching files from your computer, and opening a remote file in a local editor.
• If the network drops, the tunnel closes after about 45 seconds and you reconnect by selecting the host again.

Troubleshooting

Cline shows the SSH client's own error in the Environment status panel. The common ones:

How it works

For those who want the details:

1. Cline runs your system ssh with BatchMode=yes and StrictHostKeyChecking=yes, plus -i <identity file> and -p <port> if you filled those in. It never stores passwords or private-key contents; host settings live in ~/.cline/data/settings/remote-environments.json with owner-only permissions.
2. On connect it checks the host's OS and architecture, then uploads a matching, self-contained Cline helper to ~/.cline/remote/ (about 30 MB for Linux, sent once per Cline version and cached).
3. The helper starts a Cline Hub bound to the host's loopback interface. Cline forwards it to a random local port with ssh -L, so nothing on the host is exposed to the network.
4. Only Cline's authenticated protocol crosses the tunnel. Tool execution and session storage happen on the host; the app is a client.

A Cline CLI already running on the same remote account is left untouched; the desktop's helper uses its own isolated Hub.

Related

• Cline Desktop
• Cline CLI