SSH Connections

  • Desktop, mobile and web
  • All plans
View as MarkdownFeature page

What it does

An SSH connection manager and a built-in SSH terminal in one place. Save the machines you reach (VPS, staging box, build server, a Windows server, an AWS instance behind Session Manager), or import them from ~/.ssh/config, then open any of them as a terminal tab next to your dev terminals and run an agent CLI straight on the remote machine. A saved connection is also the network path other features reuse: database connections tunnel through it, and agents reach it over MCP by id, running commands and transferring files without ever handling a password, a passphrase or a key.

Where to find it

  • Inside a project, terminal bar > Servers ("Open a terminal on a remote machine, over SSH or AWS SSM"). The room dock: Servers ("Saved SSH and AWS SSM connections"), also the Servers tab of the Commands & connections modal.
  • Command palette (Cmd K / Ctrl K): saved connections are a source.
  • Phone: the SSH connections sheet of the project.

How to use it

  1. Import from ~/.ssh/config: AgentsRoom reads your OpenSSH config, lists the hosts found (with "Through <bastion>" for ProxyJump and "Already imported" marks), and creates one connection per selected host. A long config is filtered by the search field ("Search a host (alias, hostname, user)"): the count becomes "Matching hosts: N of M", and Select all / Deselect all apply to the matches. Your config file is never modified. An imported connection is opened by its alias, so OpenSSH keeps applying the whole block: identity file, bastion, agent.
  2. Or New connection: name, Transport (SSH, AWS SSM or WinRM, the latter described in Windows Connections (WinRM)), host, port, user, Authentication (Password, Private key with a path and optional passphrase, or SSH agent), Jump host (none, or an address like [email protected]), Remote path, Remote shell (Server default, PowerShell, PowerShell 7 for a Windows server), description, scope (this project only or every project of your account). Test connection tells you what it could verify: "Connected. The server accepted the key" for key or agent auth, "Port reachable. The password can only be checked when you connect" for a password.
  3. Click Connect on a card: a terminal tab opens and the ssh line is typed for you; the desktop injects the password when the binary asks for it. Run your agent CLI there like on any machine.
  4. Duplicate connection opens the creation form pre-filled (the secret is never copied). The card lists the projects offloaded to that server ("Projects: ..."). Reorder the cards by dragging them; a long list scrolls by itself when the dragged row nears the top or the bottom (same in the Commands and Databases tabs).
  5. Pick a connection in a database connection's Reach through to tunnel through it.

Settings

  • openCommandsInSamePane / openCommandsSplitDirection (global, also Open connections in the same pane in the Servers modal): open as a split of the focused pane instead of a new tab.
  • Restore connections on launch (Servers modal): reopen this project's open connections when the app starts.
  • agentConnectionWrites (global, Agents can manage connections, Settings > AI providers, ON by default): agents may save, update and delete connections on their own through ssh_connection_save / ssh_connection_delete, with no form for you to review. A credential is never accepted as a value: the agent names a secret of your vault (passwordSecret / passphraseSecret) and the desktop copies it, so nothing appears in a conversation. Turn it off and an agent can only propose a connection through the pre-filled form.

Agent tools (MCP)

  • ssh_list: metadata only (name, host, port, user, auth type, remote path, scope) plus the live tab when one is open.
  • ssh_exec: run one command on a saved machine, get its output and exit code. The agent's working tool; the credential is injected by the desktop.
  • ssh_transfer: move one file to or from the machine; returns a local path and a byte count, never the content.
  • ssh_connect: open a saved connection as a visible terminal tab (idempotent: an already open tab is returned). Readable afterwards through commands_output.
  • ssh_connection_new: propose a connection by pre-filling the creation form; you review, type the credential and save.
  • ssh_connection_save / ssh_connection_delete (behind agentConnectionWrites): write, update or remove a connection outright. id updates an existing connection; scope is project (default) or global; the credential is a vault secret NAME, never a value. A delete also drops the stored credential and unties any connection jumping through it.

A Windows host can also be saved with the WinRM transport (PowerShell Remoting, NTLM or Kerberos, on-prem Exchange included): see Windows Connections (WinRM).

Providers

All providers, no difference. The remote CLI can be any agent installed on the server.

Mobile

Yes: the phone lists the connections of the project (plus the global ones) and opens a terminal on one; the session is created on the desktop and streamed to the phone encrypted, with the same remote shell choice. No connection form on the phone.

Limits

  • A connection follows your account to your other computers with everything that describes the server: host, port, user, transport (SSH, AWS SSM with its target, AWS profile name and region, or WinRM with its authentication, endpoint and read-only flag), jump host, remote shell, remote path. Three things stay on the machine where they were entered: the password or passphrase (never sent to the server), the private key path and the ~/.ssh/config alias (they point at files of that machine). On another computer an imported entry falls back to its user@host:port form. The AWS profile travels by name: if that computer has no profile with this name, the connection fails with the AWS CLI's "profile could not be found" instead of silently using the default profile.
  • An edit or a delete made offline is kept and sent on the next sync, it is never overwritten by the older copy of the account. The list resyncs when you sign in, when the app starts, when the window gets the focus back and when the network returns.
  • Forward agent and free-form -o options exist only on imported connections, taken from your config.
  • A database tunnel through a password-authenticated connection is refused: use a key, the SSH agent, or an imported entry.
  • "Test" on a password or SSM connection cannot verify the credential without opening a session, and says so.
  • Restarting an SSH tab from the pane label is disabled on purpose: reconnect from the Servers list.
  • The ssh line of a terminal tab, and the scripts behind ssh_exec and ssh_transfer, are typed into your local login shell and quoted for it: PowerShell on Windows, POSIX shells and fish elsewhere.

Common questions

  • Can I run Claude Code or Codex on a remote server? Yes: connect, then launch the CLI in the remote terminal. To make a whole project's agents launch there automatically, see Remote SSH Offload.
  • Do my agents see my SSH password? Never. MCP tools expose metadata; the desktop injects the credential after the agent asked for the connection by id.
  • ssh_exec fails on my server whose private key has a passphrase, while the terminal works. Fixed on 2026-09-29: the passphrase saved with the connection is now given to the key for ssh_exec and ssh_transfer too, as the terminal already did.
  • Can an agent create a connection? Yes: by default it can save, update and delete them on its own (ssh_connection_save, on by default since 2026-10-01), the credential being copied from a vault secret it only names. Prefer the reviewed path (ssh_connection_new opens the pre-filled form) when you would rather decide each one; turn Agents can manage connections off (Settings > AI providers) to keep only that reviewed path.
  • A server with no public address? Save it as an AWS SSM connection; see RDS through AWS SSM.
  • Windows server lands on cmd.exe. Set Remote shell to PowerShell or PowerShell 7.
  • Can I open a project or run agents on a Windows server? Not yet: the terminal works, but a remote project needs a host with a Linux or macOS shell (see Remote SSH Offload). WSL set as the default shell of the server's OpenSSH service makes it work today.
  • My SSM connection uses the wrong AWS profile on my other computer. Versions before 2026-09-28 kept the profile name on the machine where it was typed, so elsewhere the connection used the default profile. Open the Servers list once on the machine that has the right profile: it pushes the name to your account and the other computers pick it up.
  • My SSM connection or my bastion is missing on my other computer. Sync now carries the transport of a connection (SSM target, region, jump host, remote shell); connections saved by an older version are pushed again the first time the newer desktop loads them, so open the Servers list once on the machine that created them.

Related