Skip to main content
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.
This page assumes you have never used SSH. If you already log in to the machine with ssh user@host and it does not ask for a password, skip ahead to Add the host in Cline.

​
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.
1

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.
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).
2

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

Log in once and trust the host

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.
The 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 to it. If it asks for anything, Cline will not be able to.

​
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.
Cline Desktop Remote settings showing a saved host with a passed connection test
Saving or testing a host does not connect to it. Nothing runs on the remote machine until you select it in the next step.

​
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 environment selector in Cline Desktop listing Local, Cloud, and a saved SSH host
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.
A Cline Desktop session on an SSH host where whoami, hostname, and pwd show the remote account and project directory
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.

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