Remote SSH Offload

  • Desktop, mobile and web
  • All plans
View as Markdown

What it does

Map a project to a remote machine so that its agents run there instead of on your laptop: you pick a saved SSH connection and the path of the project on that host, and from then on launching an agent opens the SSH session and starts the agent CLI in that folder. The terminal, the status tracking and the phone remote stay the same as for a local agent. A project can also be created or opened directly on the server, with no local checkout at all: for such a project the terminal tabs, the dev commands, the file explorer, the Git panel and the session file all live on the host too, so the desktop behaves like a cockpit for a project that exists only over there. Useful for heavy builds, GPU jobs or long-running agents on a powerful server while you keep the cockpit on your screen. The sidebar and the projects home show on which server a project lives. Available to every account since 1.176.0 (2026-09-16). The Codex account chosen in AgentsRoom follows the agent to the host: its credentials are copied there before the launch, so a manual account change, a one-off account override or an automatic switch after a quota wall apply to remote agents exactly as to local ones. Since 2026-09-18 the AgentsRoom tools follow too: an agent launched on the host (Claude Code or Codex) has the same backlog, memory, skills, prompts, dev commands and agent mail tools as a local one, and a team run works on a remote project. Since 2026-10-01 the agent menus and forms of a remote project list the CLIs installed ON THE SERVER (no need to install them on your computer), and a connection can keep its agents running on the server when AgentsRoom closes, so you pick them up later from this computer or another one.

Where to find it

  • Project settings > Remote SSH ("Offload to a remote host"). The tab also holds the two lists Follows the agent to the host / Stays on this computer.
  • New project dialog: the Location choice, This computer or Remote server (SSH).
  • Servers: each connection card has Open a project on this server, and lists the projects hosted on it ("Projects: ..."). The connection form holds the per-host switches Copy the agents' Codex account to this host, Install the AgentsRoom tools on this host and Keep agents running on this host when AgentsRoom closes.
  • The "Configure project path" dialog (a project of your account not yet located on this computer): the third card Open on a remote server (SSH). Since the mapping is saved with your account, that card arrives pre-filled with the server and path on a second computer.
  • Sidebar and projects home: a server badge on the project ("On server <name>") once the mapping is complete. A project that lives only on the server shows <connection>:<remote path> instead of a local folder.
  • Add agent and Edit agent, for an offloaded project: the notice "Agents of this project run on <host>".
  • Agent terminal, when the CLI is missing on the server: the banner "<provider> CLI missing on <host>" with the button Install on <host>.

How to use it

  1. Save the server first in Servers (see SSH Connections); the settings tab says "No SSH connections saved yet" otherwise.
  2. Project settings > Remote SSH: choose the SSH connection and type the Remote project path (absolute path on the host, where the CLI will run). An Active badge confirms the mapping.
  3. Launch an agent as usual. The tab now hosts the SSH session; the agent runs on the host with the same provider, model and options as configured. The persona is inlined into the prompt since the host has none of your local role files.
  4. To go back to local execution, set the connection to None (run locally): the mapping is cleared.

Create a project on the server: New project, set Location to Remote server (SSH), pick the connection and type the remote path (~ is expanded). The desktop checks that the directory exists on the host before saving ("No such directory on <host>", "Could not reach <host>" otherwise); nothing is copied to this computer. If the remote checkout already belongs to an AgentsRoom project, the same project is opened (same agents, backlog and memory). The Remote SSH tab of such a project has no None (run locally) option, only another connection or path; its intro says so.

Open a known project on a server: from the connection card, Open a project on this server, or from the "Configure project path" dialog, Open on a remote server (SSH) then Open on the server.

Work on a project opened on a server: the "+" terminal tab, the play button of a dev command, its restart, "open another tab" and a command proposed by an agent all open on the host, in the project folder; once the command ends the tab drops into an interactive shell there, like a local tab. The file explorer, the file preview, the Changes panel, history, branches, commit and push read and write the host's checkout. Nothing to configure.

AgentsRoom tools on the host: nothing to do. Before each remote launch of a Claude Code or Codex agent, the desktop installs its MCP servers and a copy of your account token on the host (in files only your user can read) and opens an SSH tunnel back to this computer, so the agent uses the backlog, memory, skills, prompts, dev commands and agent mail exactly as a local one. The first time on a host, the terminal prints "AgentsRoom tools installed on <host>: agents launched there have the backlog, memory, skills and dev commands. You can turn this off in the settings of that SSH connection." A refusal or a failure is printed at every launch with its reason, and the agent then runs without the tools.

CLI missing on the server: the banner "<provider> CLI missing on <host>" explains that installing it on this computer would change nothing. Install on <host> types the install command into the agent's terminal, over SSH, on the server (the password is answered by the desktop, you press Enter); then Relaunch agent. The remote launch also finds CLIs installed in the user folders of the host (~/.local/bin, ~/.npm-global/bin, a Node from nvm), which a non-interactive SSH command does not see by default.

Codex account on the host: nothing to do. When the agent runs on Codex with a bound account, the desktop copies that account's credentials to the host (in a file only your user can read) and the remote CLI runs on it. The first time on a host, the terminal prints "Codex account “<label>” copied to <host>: agents launched there run on it. You can turn this off in the settings of that SSH connection." If the host refreshed the token meanwhile, the fresher copy is adopted on this computer, so you are not asked to sign in again. Removing a profile in Settings also removes its copies on every host. When a remote Codex agent hits its usage limit and is switched to another account (or you rebind it by hand), its conversation is copied between the two accounts on the host and resumed where it was, as for a local agent.

If the SSH transport drops (network, host reboot), the agent pane restarts the agent by itself and resumes the same conversation: "SSH connection lost (code <code>): reconnecting in <n> s…". After three failed attempts it stops with "SSH connection lost: gave up after 3 attempts. Restart the agent once the server is reachable." An agent whose remote command simply ended is not restarted.

Settings

  • Project settings > Remote SSH > SSH connection and Remote project path. The mapping is saved with your account: a project you open on another computer offers the same server. A project that has a local checkout on the other computer keeps running its agents locally there until you map it. No global setting.
  • Servers > connection form > Copy the agents' Codex account to this host (ticked by default, SSH connections only, synced with your account like the other transport fields). Untick it for a host you do not trust with your subscriptions: agents then use the login the host has, and what was copied is removed.
  • Servers > connection form > Install the AgentsRoom tools on this host (ticked by default, SSH connections only, synced with your account). Untick it for a host you do not trust with your account: agents there run without the AgentsRoom tools, and the servers and the token copy are removed from the host.
  • Servers > connection form > Client folder of this host (key folderId, none by default, SSH connections only, synced with your account). Every project opened on this host is filed in that folder and inherits what the folder sets: CLI and accounts, CLI options, Quick / QA / Backlog agents, teams. Your other computers file it the same way. Environment variables and your own MCP servers of the folder apply to local launches only, they are not sent to the host. See Scope Levels.
  • Servers > connection form > Keep agents running on this host when AgentsRoom closes (key persistentSessions, OFF by default, SSH connections only, synced with your account). Agents launched on the host run inside a tmux session there (tmux 3.0 or later needed on the host; without it agents launch as before). Quitting AgentsRoom, sleep or a network drop no longer stops them: the next launch of the agent, from this computer or another one of your account (or the phone), attaches to it. Closing or restarting the agent still stops it.

Agent tools (MCP)

Since 2026-09-18 a Claude Code or Codex agent launched on the host has the same AgentsRoom-MCP tools as a local agent (backlog, memory, prompts, skills, dev commands, agent mail, git_set_commit_message, the QA bot and the embedded browser, all through the tunnel back to this computer), plus the team tools inside a team run. Two differences: settings_list, settings_get and settings_set refuse the global scope from the host ("The app settings (scope "global") are not readable from this remote host"), the project, folder and agent scopes work; and when the tunnel to the desktop is down, the tools that need the desktop (dev commands, agent mail, browser, commit box) answer "desktop bridge unavailable" while the cloud ones (backlog, memory, skills) keep working. An agent of another CLI, or a launch where the tools could not be installed, has none of these tools: it is told so at launch, does not look for them, and writes in its answer what should be recorded (a backlog entry, a memory note, its commit line), ready to paste.

Providers

Any provider whose CLI is installed on the remote host. For a remote project, the ⚡ menu, the menu of an inactive agent and the provider picker of the agent form read the CLIs of the SERVER (asked once, refreshed every 10 minutes and after an Install on <host>): a provider missing there sits under "Not installed on <host>", and one installed there is offered even when this computer does not have it. Until the server has answered (or when it cannot be reached), nothing is hidden. The command is built by the usual provider layer with POSIX quoting (the host is POSIX even when the desktop is Windows). The Codex account bound to the agent (agent pin, project or folder default, one-off override, automatic switch) is copied to the host and used there (the Follows the agent to the host list: "Codex account chosen for the agent: copied to the host before the launch (can be turned off per SSH connection)"). The other providers' profiles stay local ("Claude, Antigravity, Grok and Cursor account profiles: the remote CLI uses the login it has over there"): their credentials live in the OS keychain or have no file to ship. Codex instructions are passed inline instead of through a profile. The AgentsRoom tools are installed on the host for Claude Code and Codex only ("AgentsRoom tools (backlog, memory, skills, dev commands, agent mail): installed on the host with your account token, Claude and Codex (can be turned off per SSH connection)"); the other CLIs read a configuration file the desktop does not write on the host yet, so they run tool-less over there as before.

Mobile

An agent started from the phone while the desktop is on is offloaded transparently: the desktop wraps the launch in SSH exactly as it does for a local click, including for a project created on the server, and installs the AgentsRoom tools on the host in the background (on the very first launch on a host from the phone, the CLI can start before the tools are in place; the next launch is fine). Dev commands, files and git browsed from the phone go through the same desktop and reach the host the same way. A direct connection from the phone while the desktop is off (SSH credentials synced to the phone's secure keystore over the encrypted channel) is still being validated; SSM connections never sync credentials to the phone. The phone does not create remote projects, does not edit the mapping, and shows neither the host badge nor the scope lists. The "CLI missing on <host>" banner is desktop only.

Limits

  • The host must be Linux or macOS (a POSIX shell). A Windows server reached over OpenSSH gives you the terminal and PowerShell (see SSH Connections), but no remote project and no agents launched there: the New project dialog and the connection card answer "<host> did not answer like a Linux or macOS shell. Remote projects need a host with a POSIX shell: a Windows server reached over SSH is not supported yet." Decided on 2026-09-19 not to port the remote mode to PowerShell for now; the workaround is WSL set as the default shell of the server's OpenSSH service, which makes it a Linux host for AgentsRoom.
  • What follows the agent to the host (the Follows the agent to the host list): provider, model and reasoning effort; permission mode and CLI options; role, persona and system prompt; attached skills and prompts (sent inline); terminal and status tracking; terminal tabs and dev commands, opened on the remote machine in the project folder; tab title, push notifications and the "needs input" badge (the session file is read on the remote machine); file explorer and Git panel, served from the remote machine (projects opened on a server); the mapping itself, saved with your account; the Codex account chosen for the agent; the AgentsRoom tools (Claude and Codex); the embedded browser and QA bot, through the SSH tunnel; team runs (the team tools of each step reach the run through the tunnel, the run itself stays on this computer); ticket worktrees ("a ticket that asks for a separate worktree gets it on the server, under the remote checkout, and the agent starts in it", projects opened on a server only).
  • Attached files travel (since 2026-09-23): a ticket's screenshots and the files dropped, pasted or captured into the composer are copied to the host, under .agentsroom/attachments/ of the remote checkout (ignored by git there, 8 MB per file), before the agent reads them, and the agent is told the host path; earlier versions handed it the path the file had on this computer, which the host never had. A file that cannot be copied (Windows desktop with a password connection and no open tab, a file over the cap) keeps its local path.
  • What stays on this computer (the Stays on this computer list): hooks and a team step's own checkout; environment variables and secrets (the remote shell keeps its own); Claude, Antigravity, Grok and Cursor account profiles. Nothing is lost: these settings are wired to this machine and cannot cross the SSH boundary.
  • Ticket worktrees travel (since 2026-09-22): on a project opened on a server, a backlog ticket with Code in a separated worktree for this task gets its worktree cut on the host, under .worktrees/ of the remote checkout, and the agent starts in it. Two gaps: a desktop reaching the host over a password-authenticated connection with no open terminal tab cannot run git there, so the ticket is refused instead of started; and a team step's Own checkout is refused on such a project, the run stopping with the reason. A LOCAL checkout mapped to a host still refuses a worktree ticket ("Git worktrees are not available when a local checkout runs its agents on a remote SSH host ... untick "Code in a separate worktree" on the ticket, open the project directly on the server, or run it locally"): the worktree would be cut on this computer, out of the agent's sight.
  • AgentsRoom tools on the host: Claude Code and Codex only; the host needs Node.js ("Node.js is not installed on the host" otherwise) and a plain SSH connection with a headless channel (never SSM or WinRM). A password-authenticated connection has that channel only through an open session: on Windows never, on macOS and Linux only while a terminal tab or an agent is already open on that host. Without it the launch lines say "password connection with no open session on this host, open a terminal tab on it first" (since 2026-09-19; before, macOS and Linux reported "the copy failed" for the same situation). Two computers launching on the same host overwrite each other's tunnel descriptor: the last one to launch has the desktop tools, the other sees "desktop bridge unavailable" on them while backlog, memory and skills keep working for both. The team reminder hook stays local.
  • Codex account on the host: with a password-authenticated connection the copy cannot happen unless a terminal tab is already open on that host (on Windows, never; the terminal says so: "password connection with no open session on this host, open a terminal tab on it first"); never over SSM or WinRM. An account not signed in on this computer is not copied either. After an account switch, the conversation is resumed on the host since 1.179.0; it starts fresh only on a host without a headless channel. An agent launched from the phone does not get the copy.
  • On macOS, versions before 1.177.0 could fail every ssh_exec and headless read with "unix_listener: path ... too long for Unix domain socket" (exit 255): the shared connection's socket now lives in a short folder. Update the desktop if you still see it.
  • For a project that has a local checkout AND a mapping, only the agents and their session file go to the host: the explorer and the Git panel keep showing the local checkout. The remote explorer and Git panel are for projects opened on a server.
  • The mapping is per project: every agent of the project goes to the same server.
  • Password authentication is injected by the desktop; key or agent authentication is the simplest path. On macOS and Linux the first SSH session (agent or tab) opens a shared connection that the explorer, the Git panel and the session file reuse without a new handshake. Windows OpenSSH has no such sharing: every read is a full connection (slower), and a connection authenticated by password cannot be read that way, so the explorer, the Git panel and the session file stay empty for it. Use a key, an SSH agent or a ~/.ssh/config alias on Windows.
  • On Windows a very long prompt opens two SSH connections in a row (the desktop answers both password prompts); SSM connections keep a single step.
  • The launch line is typed into a terminal of your local login shell (PowerShell on Windows, otherwise the shell of your account: zsh, bash, fish...). All of them are supported; fish was fixed after 1.173.0. On Windows, a long agent prompt made the launch fail with "File name or extension too long" or "command not found: cd": fixed in 1.175.0. The host needs the base64 command for that path.
  • Automatic reconnection gives up after 3 attempts; restart the agent by hand once the server is reachable again. With Keep agents running on this host when AgentsRoom closes, the agent keeps working on the server meanwhile and the restart attaches to it.
  • Persistent sessions: the host needs tmux 3.0 or later. When you reattach, the screen shows the agent's current state, not the lines above it. Closing an agent while the server is unreachable cannot stop it there; it keeps running until you open it again. Another computer does not show the agent as running before you open it.
  • The badge only counts a server when the mapping is complete (connection and path): a server where no agent would start is never announced.

Common questions

  • Can a server be a client's environment, like VS Code Remote SSH? Tie its connection to the client's folder (Client folder of this host) and set the client's CLI, accounts, agents and teams in that folder's settings: every project you open on the server is filed there, on every computer of your account.

  • Do my remote agents keep running when I close AgentsRoom or my laptop sleeps? Only with Keep agents running on this host when AgentsRoom closes ticked on the SSH connection (off by default) and tmux 3.0 or later on the server. The agent then runs in a tmux session on the server; open it again (from this computer, another one of your account or the phone) and you are back in the same session. Without it, the agent stops when the SSH session closes.

  • Do I have to install Claude Code or Codex on my computer to run them on my server? No, since 2026-10-01: for a project whose agents run on a server, the menus and the agent form list the CLIs installed on the server. Before, they only offered the CLIs of your computer.

  • I open a project on my Windows server and get "did not answer like a Linux or macOS shell". Expected: remote projects need a Linux or macOS host. Install WSL on that server and set it as the default shell of OpenSSH (DefaultShell in the registry, pointing at bash.exe of WSL): the host then answers like Linux and the project opens; the folder path is then the WSL path (/mnt/c/...). The terminal tab alone works on Windows without this.

  • Where is the Remote SSH tab? Project settings > Remote SSH, for every account since 1.176.0 (it used to be served only to some accounts).

  • Can one agent of a project run remotely and another locally? Not today: the mapping is per project.

  • Can the remote agent use the backlog tools, the memory or the browser? Yes since 2026-09-18, on Claude Code and Codex: the AgentsRoom tools are installed on the host and reach this computer through an SSH tunnel. Keep Install the AgentsRoom tools on this host ticked on the connection, and have Node.js on the server. Other CLIs still run tool-less there.

  • The remote agent says the AgentsRoom backlog tools "are not reachable" and tells me to reopen the project. Read the launch lines of the terminal: "AgentsRoom tools not installed" (the switch is off for that host), "could not be installed on <host>" with the reason (no Node.js, a password connection with no open session on the host, copy failed), or a CLI other than Claude Code and Codex. In those cases the agent has no AgentsRoom tools, knows it from the start and writes in its answer what should be recorded so you can paste it.

  • The terminal says "The tunnel to this computer could not be opened from <host>". The servers are installed but the reverse SSH tunnel to the desktop failed: backlog, memory and skills work, dev commands, agent mail, browser and the commit box do not. Relaunch the agent once the connection is healthy. If it happened at every launch, including for the team tools of a step run on the server, update AgentsRoom: until 2026-09-26 the tunnel was written in a form OpenSSH refuses ("Bad forwarding specification").

  • I set environment variables, an account or browser access on the agent and the remote side ignores them. Expected for environment variables, secrets and non-Codex account profiles: those stay on this computer. The agent form shows the notice "Agents of this project run on <host>" and the Remote SSH tab lists what travels and what stays.

  • Can I work on a project that only exists on the server? Yes: New project with Location set to Remote server (SSH), or Open a project on this server from the connection card. The code stays on the host; only the app's own files for that project live on this computer. Terminal tabs, dev commands, the explorer and the Git panel then work on the host.

  • The banner says the CLI is missing but it is installed on my computer. The agent runs on the server, and the CLI is missing there: the banner names the host ("<provider> CLI missing on <host>"). Click Install on <host>, let the command run in the agent's terminal, then Relaunch agent. Before 1.180.0 the banner sent you to the local automatic setup, which changed nothing on the server.

  • My ticket asks for a separate worktree and the start failed with a git error. Fixed in two steps. A project opened on the server cuts its worktree on the host since 2026-09-22 and starts the agent in it. A local checkout that merely offloads its agents still cannot: the message now explains it and offers the way out (open the project directly on the server), instead of the misleading "not a git repository" it used to answer. See Git Worktrees.

  • Can a team run on a project offloaded to a server? Yes since 2026-09-18: each step's console starts on the host with the team tools, and they reach the run (which stays on this computer) through the SSH tunnel. See Agent Teams.

  • The terminal says "SSH connection lost (code 255): reconnecting". The network or the host dropped the SSH transport. The pane relaunches the agent and resumes the same conversation on its own; after 3 attempts it gives up and asks you to restart the agent once the server is reachable.

  • The composer says "Not sent: this agent never started, so its terminal is just a shell" while the CLI is clearly running on the host. A bug of versions before 1.176.0: the desktop checked the local PATH for the remote launch. Update the desktop; a remote launch no longer goes through any local file check.

  • Why does the tab title or the needs-input badge not update for a remote agent? Since 1.176.0 they work: the session file is read on the host. Exception: on Windows with a password-authenticated connection they stay empty (see Limits); switch to a key, an agent or a ~/.ssh/config alias.

  • On Windows the agent never starts and ssh says "File name or extension too long". Update the desktop: fixed in 1.175.0.

  • I opened the same project on my second computer: do I have to map the server again? No: the "Configure project path" dialog offers Open on a remote server (SSH) pre-filled with the same server and path. Only a project that has a local checkout on that computer keeps running locally.

  • Which machine holds the code? The badge on the project row says "On server X"; the server's card lists its projects.

  • I switched the Codex account of my agent (or AgentsRoom auto-switched it) but the remote agent still uses the host's login. A bug of earlier versions, when accounts never crossed the SSH boundary (fixed on 2026-09-17). Update the desktop, and check that Copy the agents' Codex account to this host is ticked on the connection; the terminal prints a line when the account is copied, disabled or failed, with the reason.

  • My remote Codex agent hit its limit, switched accounts and started from scratch. Fixed in 1.179.0: the conversation is copied to the new account on the host and resumed where it was. It still starts fresh on a host without a headless channel (Windows with a password connection and no open tab).

  • The agent says "the copy failed" on my password-protected server, but the server is fine. Update the desktop: since 2026-09-19 a password connection with no open session on the host is reported as such ("open a terminal tab on it first") on macOS and Linux too. Open a terminal tab on that host, or switch the connection to a key, and relaunch the agent.

  • Is it safe to copy my Codex credentials or my account token to a server? Both files are written on the host readable by your user only; untick Copy the agents' Codex account to this host or Install the AgentsRoom tools on this host to remove them. Only do it on hosts you trust with your subscription and your account.

  • The remote agent never starts and the terminal says "quotes are not balanced". That is the fish login shell refusing the launch line, a bug of versions up to 1.173.0: update the desktop. Switching the local shell is not needed.

Related