SSH Connections
- Desktop, mobile and web
- All plans
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.
Video (1:12): Agents need my approval, shown in the real app. The box is ticked on a saved "staging" server, a Claude Code agent asked to check that server gets the card "Allow this agent on this server?" with the exact command, Allow runs it once and the agent names the failing service, then the next command asks again and Decline sends nothing.
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.
- In every interface mode (Simple and Balanced fold the Servers button away): while no connection is saved, New project > Remote server (SSH), the remote card of a project that has no folder on this computer, and project settings > Remote SSH show Add a connection and Import from ~/.ssh/config themselves. A connection created from New project is global (no project exists yet).
- Agents need my approval: Servers > the Edit (pencil) button on the connection card > near the bottom of the Edit connection form, above Description; tick it, then Save.
- Command palette (Cmd K / Ctrl K): saved connections are a source.
- Phone: the SSH connections sheet of the project.
How to use it
- 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.
- 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. - Click Connect on a card: a terminal tab opens and the
sshline is typed for you; the desktop hands the password tosshwhen it asks for it. Run your agent CLI there like on any machine. - 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). The order follows your account to your other computers (Live settings sync and Machines).
- 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 throughssh_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. -
Agents need my approval (per connection, in the connection form, every kind: SSH, SSM, WinRM; off by default; field
agentApproval, synced to your account like the rest of the connection): before an agent opens a terminal (ssh_connect), runs a command (ssh_exec) or transfers a file (ssh_transfer) on this machine, a card opens in that agent's pane, and on your phone, showing the connection, what it wants to do (the exact command, the file and its destination, or the host) and who asks: Allow runs it exactly as shown, Decline stops it. With no answer within about 2 minutes, the request is declined. One Allow covers one request. Declined or unanswered, nothing runs, and the agent is told not to retry nor work around it. On a WinRM connection, a write still gets its own write card afterwards. Your own clicks are not affected. An agent can turn it on throughssh_connection_save, never off, and cannot delete such a connection: only you untick it. Since 2026-11-11 it also covers a database an agent queries through a tunnel on this connection (db_query,db_schema: the card reads Open a database tunnel, with the database and the statement) and the connections that jump through this server. For a command or a file, the card names the connection followed byuser@host, so you see where it will really run.
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. Only a confirmed exit code 0 is a success: a nonzero exit, a timeout or a command whose end could not be confirmed comes back as an error, with the output kept.- Large outputs (since 2026-10-22):
ssh_execshows the agent at most the last 400 lines. When a command prints more (a firewall status report, a switch running config, a long log), every line is saved in a local file under.agentsroom/ssh-outputs/in the project, and the answer gives the agent its path (outputFile,totalLines,truncated: true) so it reads or searches the file with its own tools. The agent can ask for that file even for a short output (saveOutput: true). The directory ignores itself in git, and files older than 7 days are deleted automatically. Works for SSH, SSM, WinRM and the interactive mode. ssh_execwithcommands(interactive mode, since 2026-10-20): for network appliances whose command line only exists inside an open session (WatchGuard Firebox, many switches, routers, UPS cards), where a one-shot command comes back empty or refused. The desktop opens the session, waits for the device prompt, types each line after the previous prompt came back, answers--More--pagers, logs out and returns the whole transcript. SSH and SSM connections only (not WinRM), at most 50 lines per call. The default prompt detection expects a line ending in#,>,$,%or]; an unusual prompt is given withpromptPattern(a regex).ssh_transfer: move one file to or from the machine; returns a local path and a byte count, never the content. A failed or unconfirmed transfer comes back as an error; check the destination before retrying.ssh_connect: open a saved connection as a visible terminal tab (idempotent: an already open tab is returned). The tab joins the tab strip without taking over the screen or the keyboard, so typing in another agent is never interrupted. Readable afterwards throughcommands_output.ssh_connection_new: propose a connection by pre-filling the creation form; you review, type the credential and save. The form opens on the agent's project scope (scope: "global"preselects every project); you can change it before saving.ssh_connection_save/ssh_connection_delete(behindagentConnectionWrites): write, update or remove a connection outright.idupdates an existing connection, and an update only changes the fields the agent sends: auth type, key path, jump host and scope keep their saved value;scopeisproject(the default for a new connection) orglobal; the credential is a vault secret NAME, never a value. A delete also drops the stored credential, unties any connection jumping through it, and is carried to your account so the connection does not come back on the next sync.ssh_folders_get/ssh_folders_apply(since 2026-10-26): read and reorganise the folders of the Servers list.ssh_folders_getreturns the folder tree with full paths, the folder each connection sits in and the connections filed nowhere;ssh_folders_applycreates folders (nested if needed) and moves connections into them in one all-or-nothing batch, saved and synced to your account exactly like a drag in the list. Display arrangement only: no host or credential is touched.
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. Since 2026-10-30, a search field at the top of the sheet ("Search a connection (name, host, IP, user)") narrows the list as you type, like on the desktop; folded folders open while you search so no match stays hidden, and an empty result says "No matching connection".
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, the private key path and the
~/.ssh/configalias (they point at files of that machine). The password and passphrase can follow too since 2026-10-02, end-to-end encrypted, once you turn on Synced Passwords (Settings > Account > Synced passwords); the checkbox Sync this password to my other computers under the field keeps one local. On another computer an imported entry falls back to itsuser@host:portform. 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 and when the network returns, and right away when another of your computers changes it (Live settings sync and Machines); without the relay, also when the window gets the focus back.
- Forward agent and free-form
-ooptions 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.
- A Private key connection signs in with that key only (OpenSSH
IdentitiesOnly=yes, since 2026-10-09), in the terminal,ssh_exec,ssh_transfer, remote projects, database tunnels and Test connection alike. The key may come from its file or from your SSH agent when the agent holds that same key; the agent's other keys are not offered. To sign in with whatever your agent offers, choose SSH agent instead. An imported entry keeps the rules of its~/.ssh/configblock. - Since 2026-11-03 a saved password is handed to
sshitself, during sign-in only, and never typed into the terminal: a remote program that later shows its ownPassword:prompt (su, an installer) gets nothing and you type the answer yourself. A host key question, a 2FA code or a second password attempt is asked in the terminal as plainsshwould. This needs OpenSSH 8.4 or later on your computer; with an older one (the OpenSSH shipped with Windows 10, Ubuntu 20.04) the desktop falls back to watching the terminal for the sign-in prompt, and installing a recent OpenSSH removes that fallback. - "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
sshline of a terminal tab, and the scripts behindssh_execandssh_transfer, are typed into your local login shell and quoted for it: PowerShell on Windows, POSIX shells and fish elsewhere.
Common questions
- Is there a video that shows it? Yes, a minute long, filmed in the real app: the approval card before each command an agent runs on a saved server, https://youtu.be/berHowWtpQI
- I do not see the Servers button, where do I add an SSH connection? The Simple and Balanced interface modes fold it away. Open New project, pick Remote server (SSH), then Add a connection (or Import from ~/.ssh/config): the form opens right there, in any mode. To get the button back: Settings > Interface mode > Full, or Settings > Interface elements > Dev command bar > Servers.
- Can I stop agents from using one of my servers without asking me? Yes, since 2026-11-10: edit the connection and tick Agents need my approval. From then on each
ssh_connect,ssh_execandssh_transferof an agent on that machine waits for your answer on a card in the agent's pane (also on your phone), like the browser tool approval: Allow or Decline, request by request. The other connections keep working as before. A video shows it: https://youtu.be/berHowWtpQI - Can an agent tidy my servers into folders? Yes, since 2026-10-26: ask it to group them (by client, by project, by environment). It reads the current folders with
ssh_folders_get, then creates the folders and files every server in one batch withssh_folders_apply; the result appears in the Servers list and on your other machines. - Can an agent drive a firewall or a switch whose CLI only works in an interactive SSH session (WatchGuard, Cisco-like CLIs)? Yes, since 2026-10-20:
ssh_exectakes acommandslist instead ofcommand, opens the session, types each line at the device prompt and returns the transcript, with the credential still injected by the desktop. If the agent reports that no prompt was recognised, it can passpromptPatternmatching the end of the prompt line. - 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, and only to
sshduring sign-in (since 2026-11-03), so a remote command cannot read it either. - Can an agent read a command output longer than 400 lines (firewall status, switch configuration)? Yes, since 2026-10-22: past 400 lines the complete output is saved to a local file in
.agentsroom/ssh-outputs/and the agent receives its path instead of the whole text in its context, then parses it as it likes. Up to about 16 million characters per command; beyond that, the very beginning is dropped and the agent is told so. ssh_execfails 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 forssh_execandssh_transfertoo, as the terminal already did.ssh_execfails at once with "Connection closed by <host> port 22" or "Too many authentication failures", whilessh -i <key> -o IdentitiesOnly=yesworks. Fixed on 2026-10-09: OpenSSH used to offer every key of your SSH agent (1Password, Secretive, keychain) before the saved key, and the server cut the connection after its sixth failed key; a recent Linux server then also refuses your address for a few minutes. A Private key connection now offers its own key only. If such a connection now fails with "Permission denied (publickey)", the saved file is not the key the server accepts: pick the right file in the connection, or switch it to SSH agent.- My agent reported a remote command as successful, but nothing happened on the server (Windows). Fixed on 2026-10-08: when the local
sshcould not even start (for example a command line too long for PowerShell), the result was read as exit code 0. It now comes back as an error saying the remote command did not start, and since 2026-10-07 a timeout or an unconfirmed end is an error too, never a success. - Can an agent point one of my connections to another server? Not when that connection keeps a stored password or passphrase, nor when it asks for your approval: since 2026-11-11 an agent update that changes its host, user, port, jump host or any other part of its route is refused and nothing is written. The agent can still do it if the same save replaces the password with a secret it names. You keep changing the address yourself in the form, as before.
- 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_newopens 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. - An agent changed a server's address, but
ssh_execstill dials the old one. Signed in, the sync of your connections could put your account's previous copy back right after the agent's save: the list showed the new address for a moment, then the old one was dialed. Versions before 2026-10-14 did it at every save; a rarer timing case remained until 2026-10-19. An agent's update also keeps every field it does not send: the authentication since 2026-10-14, the scope since 2026-10-19 (a server shared with every project no longer moves into the agent's project). - 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.
- I clicked New folder on a long list and nothing seemed to happen. Fixed on 2026-10-28: a new folder was appended at the end, below every other folder and their open contents, out of view. It now appears first in its level, right under the button and already in rename mode. Dragging a folder to the very top of the list also keeps it there (Drop here to put it at the top of the list). The same holds for the Databases, Secrets and Dev commands lists and for the Prompts, Skills and Memory libraries.
- Why does my folder stay in the list when nothing in it matches my search? It does not any more, since 2026-10-29: while you are typing in the search field ("Search a connection (name, host, IP, user)"), a folder with no matching connection is hidden, empty folders included, so the results are all you see; when nothing matches at all, the list says so instead of showing a pile of empty folders. The same holds for the Commands, Databases, Secrets and Kubernetes lists. A folder you create while a search is running stays visible so you can name it. Picking a scope (All, this project) without typing anything still shows your empty folders, so a folder you just made never vanishes.
- I searched a server, closed the window, reopened it and my search was gone. Fixed on 2026-10-28: the search text and the scope filter of each list are kept while the app runs, per list and per window. They are not saved to the account and do not survive a restart, so a stale filter never greets you at launch.
- A server an agent or another window just added did not show in my detached window. Fixed on 2026-10-28: every window re-reads the saved connections as soon as one is written, whoever wrote it (a form in another window, an agent's
ssh_connection_save, the account sync). No need to reattach the window.
Related
- RDS through AWS SSM: the AWS SSM transport and port forwarding.
- Database Connections: databases reached through a saved connection.
- Remote SSH Offload: launch a project's agents on the remote host.
- Secret Manager: where the credentials live.
- Synced Passwords: the opt-in that carries passwords and passphrases to your other computers.
- Dev Terminals: the shared tab strip.
- Windows Connections (WinRM): WinRM (PowerShell Remoting) hosts, saved in the same modal.