Remote SSH Offload
- Desktop, mobile and web
- All plans
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-10-26 the Claude account follows too, through a server token you create once per account (Settings > Multiple accounts > Claude, Long-lived token button of the account): a remote Claude agent runs on its pinned account, and a Move running agents quota rule moves it to another account that has a token, resuming the conversation. 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. Since 2026-10-27 the environment variables of the agent, its project and its client folder follow it to the server too, {{secret:NAME}} values included, and so do your own MCP servers (Claude Code and Codex).
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' accounts and secrets to this host (named "Copy the agents' accounts to this host" before 2026-10-27, and "Copy the agents' Codex account to this host" before 2026-10-26), Install the AgentsRoom tools on this host and Keep agents running on this host when AgentsRoom closes.
- Settings > Multiple accounts > Claude: the Long-lived token button of each account opens Long-lived token (status "Saved on this computer" or "No token yet", Create the token, a paste field, Remove the token).
- 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.
- Status bar, Machines chip: under your computers, the SSH servers block lists the servers this computer sends agents to, with how many of their agents are running, or Not answering while the server is out of reach.
- 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
- Save the server in Servers (see SSH Connections). While no connection is saved, the settings tab says "No SSH connection saved yet. Add your server, or import it from your SSH config, to run this project on it." and offers Add a connection and Import from ~/.ssh/config right there, in every interface mode.
- 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.
- 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.
- 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. Since 2026-11-03 the product help (product_help_search, product_help_get) answers there too instead of "kb folder missing", the client folder settings read by the agent are the real ones instead of an empty list, and backlog_get / capabilities_get show the state of a ticket's team run. 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. Exception since 2026-10-26: a Codex agent whose install could not be refreshed (no open session yet on a password connection, host briefly unreachable) runs on the tools an earlier launch from this computer left on the host, and the terminal prints "AgentsRoom tools could not be updated on <host> (<reason>): the agent uses the copy already installed there. The tools that need this computer (dev commands, agent mail, browser, commit box) may be unavailable." A Claude agent already kept its tools in that case, through the configuration file the earlier launch wrote in the project folder.
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.
Claude account on the host (since 2026-10-26): one step per account. A Claude sign-in cannot be copied to the host: its refresh token works only once, so the host and this computer would sign each other out at the first renewal. Each account gets its own long-lived token instead. In Settings > Multiple accounts > Claude, click Long-lived token on the account, then Create the token: AgentsRoom runs claude setup-token in a dialog, you sign in in the browser (with the account of that row: the token bills the account signed in to claude.ai in the browser, which AgentsRoom cannot check), paste back the code if asked, and the token is captured and saved. A token made elsewhere can be pasted instead (it starts with sk-ant-oat01-). Since 2026-11-06 the paste field also takes a Claude Platform API key (sk-ant-api03-…, made on platform.claude.com): it is copied to ~/.agentsroom/claude/<account id>/api-key and exported as ANTHROPIC_API_KEY, so those agents are billed per use to that key's organization instead of the subscription, and AgentsRoom answers Claude Code's "use this API key?" question for you on the host. It is kept encrypted in this computer's vault and never shown again. Before each launch of a Claude agent bound to that account, the desktop copies it to ~/.agentsroom/claude/<account id>/oauth-token on the host (readable by your user only) and the remote command exports it as CLAUDE_CODE_OAUTH_TOKEN; the host's own ~/.claude (settings, MCP servers, conversations) is not touched. The first time on a host the terminal prints "Claude account “<label>” copied to <host> through its server token: agents launched there run on it. You can turn this off in the settings of that SSH connection." An account without a token prints at every launch "Claude account “<label>” has no server token yet, so the agent runs on the login <host> has. Create one in Settings > Multiple accounts > Claude, Server token button of that account." Another computer of your account without the token reuses the copy the first one left on that host ("…applied on <host> with the server token another of your computers left there…"). A quota rule Move running agents (or a manual account change) relaunches a remote Claude agent on the new account's token and resumes the same conversation, since the conversation stays in the host's ~/.claude; only accounts that have a token on this computer can take over there, and the CLI's own login is never picked for a remote agent. Removing the token or the account removes its copies on every host.
Environment variables on the host (since 2026-10-27): nothing to do. Before each remote launch, the variables of the agent (its own block and its toolkits), of the project (Project settings > AI providers) and of the client folder are sent to the host over SSH, never in a command line: the desktop replaces each {{secret:NAME}} by its value from this computer's vault, writes everything in a file only your user can read, and the remote command loads that file and deletes it before the agent starts. The file is kept in memory, never on the server's disk, when the server has a memory folder for your user ($XDG_RUNTIME_DIR, else /dev/shm, on Linux); otherwise (a macOS server, or a launch from a Windows computer, whose SSH sessions are not shared) it goes to ~/.agentsroom/env/. The variables of Settings > AI providers and the provider's proxy stay on this computer, as they describe this machine. The first time on a host, the terminal prints "Environment variables of this agent sent to <host> over SSH, secrets included, in a file only your user can read and deleted as soon as the agent starts. You can keep the secrets on this computer in the settings of that SSH connection." With Copy the agents' accounts and secrets to this host unticked, the variables that use a secret stay here and every launch says which ones ("Not sent to <host>: MY_TOKEN. These variables use secrets from your vault, and copying accounts and secrets is turned off for that SSH connection, so the agent starts without them."); the other variables still travel. A failure is printed at every launch with its reason ("The environment variables of this agent could not be sent to <host> (<reason>): the agent starts without them.").
Your own MCP servers on the host (since 2026-10-27): nothing to do. The servers of Settings > AI providers, the client folder, the project, the toolkits and the agent are merged as for a local launch and given to the remote CLI: Claude Code through a configuration file written next to the environment file, Codex on its launch line. A {{secret:NAME}} in a server is never written in that configuration: it becomes a variable reference, and the value travels in the environment file. The first time on a host the terminal prints "Your MCP servers sent to <host> for this agent: <names>. …"; a server left behind is named at every launch with the reason ("MCP servers not sent to <host>: <names> (<reason>)."). A server started by a command (stdio) needs that command installed on the server. Servers that sign in with OAuth stay on this computer.
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. A server that does not answer at all is given up after 20 seconds per attempt (since 2026-10-09; before, an unreachable address could hang for minutes and retry forever).
Host not answering (since 2026-10-09): when the agents of a remote project lose their server (typically a VPN such as Tailscale that is not connected yet when AgentsRoom starts), the project says so at the top of its agent list: "<host> is not answering", how many agents are waiting for it, "If this server is behind a VPN (Tailscale, WireGuard…), connect to it, then retry.", and a Retry button. Retry checks the server first: when it answers, every agent waiting for it (in every project of that server) is relaunched on its previous conversation; otherwise "Still no answer. Check the VPN or the network, then retry." with ssh's own message. The server badge of the project (sidebar, projects home) turns into a crossed-out red server icon meanwhile.
Remote Claude conversations (since 2026-10-09): a Claude Code agent of a remote project now comes back on its conversation after a restart, like a local one. Before, nothing on this computer could learn the id of a conversation running on the server, so every restart gave an empty console.
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' accounts and secrets to this host (key
shipAgentAccounts, ticked by default, SSH connections only, synced with your account like the other transport fields). Covers the Codex login, the Claude server token and, since 2026-10-27, the vault secrets the agents' environment variables use. Untick it for a host you do not trust with your subscriptions and secrets: agents then use the login the host has, the variables that use a secret stay on this computer (the others still travel), and what was copied (Codex credentials, Claude tokens, environment files left on the host) is removed. - Settings > Multiple accounts > Claude > Long-lived token (per account, none by default). The token itself is a credential: it stays in this computer's encrypted vault, is not synced to your other computers, and no agent tool can read or write it (
settings_*and the other MCP tools never see it). Shown only while the Remote SSH feature is available to your account. - 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. Its environment variables and your own MCP servers of the folder follow the agent there too since 2026-10-27. 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 Claude account follows once it has a server token ("Claude account chosen for the agent, once it has a server token (Settings > Multiple accounts): the token is copied to the host before the launch (can be turned off per SSH connection)"). The other profiles stay local ("Antigravity, Grok and Cursor account profiles, and a Claude account without a server token: the remote CLI uses the login it has over there"): an Antigravity account is an API key that would need a machine-wide mode switch on the host, and Grok and Cursor are not covered yet. 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. A Claude agent started from the phone gets its account's server token on the host like a desktop launch (since 2026-10-26); the token is created on the desktop only, since it runs claude setup-token on the computer. Its environment variables reach the host too (since 2026-10-27), with the same layers and the same rules; the terminal lines about them are printed on desktop launches 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 Claude account chosen for the agent, once it has a server token; 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); since 2026-10-27, the environment variables of the agent, the project and the client folder, secrets included, and your own MCP servers (Claude Code and Codex). In the built-in browser,
localhostopens the host: see Built-in browser on the localhost of an SSH host. - 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; the environment variables of Settings > AI providers and the provider's proxy (the remote shell keeps its own); Antigravity, Grok and Cursor account profiles, and a Claude account without a server token. 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. Since 2026-10-19 a LOCAL checkout mapped to a host refuses a step's Own checkout too, the run stopping with the reason (turn Own checkout off on that step): the checkout used to be cut on this computer while the step started on the host, in a folder the host does not have, so the step never started and nothing alerted you. 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.
- Claude account on the host: same channel rules as the Codex account (password connections need an open tab, never SSM or WinRM). The token only carries model requests: on the host, Remote Control and the claude.ai connectors are not available to that agent, and
/statusmay show the token as the sign-in method instead of the account email. A token is valid one year; when it expires or is revoked, create a new one. The token bills the account that was signed in to claude.ai in the browser when it was created, whichever row you created it from. Only an account that has its token on THIS computer can take over a remote agent at a quota limit (a copy another computer left on the host is used for launches, not for the switch). - Environment variables on the host: same channel rules as the accounts (a password connection needs an open terminal tab on the host on macOS and Linux, its stored password on Windows; never SSM or WinRM). The names the host's own session sets are never sent (HOME, USER, LOGNAME, SHELL, PWD, MAIL, the SSH_* socket variables, DISPLAY, XAUTHORITY, XDG_RUNTIME_DIR, XDG_SESSION_*, and shell parameters such as IFS, UID or PPID). A
{{secret:NAME}}this computer cannot read travels as written, exactly as it reaches a local agent, and the usual notice says so. With Keep agents running on this host when AgentsRoom closes, reattaching to an agent still running keeps the variables it started with: restart it to apply new ones. A file left by a launch that never ran its command is removed by the next launch of that agent, or after a day by any launch on that host. - Your own MCP servers on the host: Claude Code and Codex only (the other CLIs still get none there, and the terminal says so). OAuth servers stay on this computer. A server that needs a secret stays here when Copy the agents' accounts and secrets to this host is unticked. Codex cannot read a secret from the environment in a URL, a command or an argument, has no SSE transport and cannot take a server name with a dot: such a server stays here, named in the terminal. On Codex, a secret in the environment of a command server reaches it under its own name, so the agent's own environment carries it too. A restricted run sends none of them. A server started by a command needs that command on the server.
- On macOS, versions before 1.177.0 could fail every
ssh_execand 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/configalias 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
base64command for that path. - Automatic reconnection gives up after 3 attempts; use Retry on the project's "<host> is not answering" banner once the server is reachable again (or restart the agent by hand). With Keep agents running on this host when AgentsRoom closes, the agent keeps working on the server meanwhile and the restart attaches to it.
- Resuming a remote conversation after a restart works for Claude Code, oh-my-pi, and since 2026-11-06 Codex and Antigravity (their conversation is found on the server by the agent's own signature). Grok, Cursor and Kimi Code agents of a remote project still start a new conversation after a restart. A remote Claude agent started from the phone is not resumable yet, and after a
/clearthe next restart starts a new conversation (Claude; and Antigravity, whose post-/clearconversation carries no signature). - 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
-
My agent on the server stops at launch with "Argument list too long". Fixed on 2026-11-02 (reported by a user): a long launch command (system prompt, brief, resumed conversation) passed the server's size limit. A long command is now sent in two steps, from a Mac or Linux computer as from Windows.
-
On the server, starting a ticket, a team or a fast reply answers "unknown project" or "project is not open". Fixed on 2026-11-02 (reported by a user): when the path on the server is not enough to identify the project, its tools now use the project's own id.
-
Can the agents keep working with my computer off? Agents already started can, with Keep agents running on this host when AgentsRoom closes, but team runs, triggers and the phone link stay on your computer, since AgentsRoom runs there. To have everything on the server, run AgentsRoom itself there: see Linux Server Mode.
-
Where do I see all the servers my agents run on? In the Machines chip of the status bar, block SSH servers: only the servers a project of this computer sends its agents to, never the saved connections used for a terminal only. Each shows its number of projects and of running agents, or Not answering while the server is out of reach. AgentsRoom does not test the servers for this list: a server is marked not answering only when an agent lost its connection to it.
-
My agent started on the server without my
--settingsfile, and the terminal said an option was ignored. Since 2026-10-06 a CLI option whose value is a Windows drive path (C:/...orC:\...) is left out of a launch on a Linux or macOS host, because that path does not exist there; the terminal names the option and the agent starts without it. Your saved options are untouched and local launches keep them. To keep those settings on the server, copy the file there and put the server path in the CLI options of the folder linked to the SSH connection, or in the agent's CLI options. -
My Codex agent on the server has no AgentsRoom tools, while my Claude agents there do. Fixed on 2026-10-26. A Codex agent receives the tools on its launch line, so a launch whose install on the host failed (typically right after restarting AgentsRoom, before any session to that host is open) used to start with none, and the agent was told they were absent. It now runs on the copy an earlier launch left on the host, like the Claude agents. The same agent launched from the phone also gets them now. If the terminal still says "AgentsRoom tools could not be installed", no launch from this computer ever installed them on that host: open a terminal tab on the host and restart the agent.
-
My agent on the server created a dev command, but running it answered "not found". Fixed on 2026-10-18: an agent running on the server can now start, follow and stop the dev command it just created (
commands_createthencommands_run), and the command runs for the project on the server, not on this computer. -
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 (
DefaultShellin the registry, pointing atbash.exeof 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. Environment variables and secrets reach the host since 2026-10-27 (see the next question). Still expected for the variables of Settings > AI providers, the Antigravity, Grok and Cursor account profiles, and a Claude account without a server token: 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.
-
My agent on the server does not see
MY_TOKEN={{secret:MY_TOKEN}}, not even as text. Before 2026-10-27 the environment variables never crossed SSH: they reached the localsshcommand, which does not pass them on (reported by a user). Update the desktop: the variables of the agent, the project and the client folder are now sent to the host before each launch, the secret resolved on this computer. If the terminal says "Not sent to <host>", tick Copy the agents' accounts and secrets to this host on the connection; if it says "could not be sent", read the reason (on a password connection, open a terminal tab on the host first). A variable set in Settings > AI providers stays on this computer: move it to the project or the agent. -
My own MCP server works locally but the agent on the server does not have it. Before 2026-10-27 your MCP servers never reached the server. Update the desktop: Claude Code and Codex agents now receive them at each launch. If the terminal says "MCP servers not sent to <host>", read the reason in parentheses: OAuth sign-in (stays on this computer), a secret while copying secrets is off on the connection, or a field Codex cannot take. A server started by a command also needs that command installed on the server.
-
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. The project then shows "<host> is not answering" with Retry: connect your VPN or network, then click it.
-
AgentsRoom started before my VPN (Tailscale) was connected and my remote agents are dead. Since 2026-10-09 the project shows "<host> is not answering" within seconds. Connect the VPN, then click Retry: every waiting agent of that server is relaunched on its conversation. Before, each agent printed a red "gave up" line in its own terminal and had to be restarted one by one.
-
My remote agents come back empty after every restart (update, crash, quit), their history gone. Claude Code: fixed on 2026-10-09, a remote Claude conversation is now named when it starts and resumed on the server after a restart (conversations started before that update cannot be found again). Codex and Antigravity: fixed on 2026-11-06 (reported by a user): nothing was deleted, AgentsRoom simply did not know which conversation on the server belonged to which agent, so each restart opened a new one. It now finds, on the server, the conversation each agent signed, keeps it up to date while the agent works, and resumes it after an update or a crash (or offers it on the Restore past agent card after a normal quit). Conversations from before the update are found again too: at its next launch, each agent gets back its latest conversation of the last 30 days. Older ones stay on the server: for Codex, run
codex resumein the project folder on the server to pick one. With Keep agents running on this host when AgentsRoom closes (tmux 3.0 or later on the server), the agents do not even stop when AgentsRoom restarts. -
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/configalias. -
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' accounts and secrets 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 project is pinned to a Claude account, but
/statuson the server shows another one, and my quota rules never move my remote agents. Before 2026-10-26 Claude accounts never crossed the SSH boundary: every remote Claude agent ran on the server's own login (reported by a user). Update the desktop, then give each account a server token: Settings > Multiple accounts > Claude, Long-lived token on the account, Create the token. The next launch prints "Claude account “<label>” copied to <host>…", and a Move running agents rule then moves remote agents to another account that has a token./statusmay then show the token as the sign-in method instead of the email: that is expected. -
Can AgentsRoom copy my Claude login to the server instead of a token? No, on purpose: a Claude login renews a single-use refresh token, so a copy on the server and the one on this computer would sign each other out within hours. The server token is made for automation, valid one year, and leaves your login untouched.
-
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, my Claude server token, my secrets or my account token to a server? Every file is written on the host readable by your user only, and the Claude token and the environment variables are read on the host itself, never written in a command line; the environment file is deleted as soon as the agent starts. Untick Copy the agents' accounts and secrets 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.
-
With Keep agents running on, my restarted agent showed "no such session" and "Shared connection closed", then a local shell. Did it run on my computer? No, it never ran on your computer. The agent's CLI had already exited on the server before AgentsRoom could attach to it, and the last screen was printed only on an error code. Since 2026-10-09 (reported by a user) that last screen of the server is always shown when the attach did not happen, so you see what the CLI printed before stopping instead of an empty local shell.
Related
- SSH Connections: the connection you map the project to, with its two per-host switches.
- Multiple Accounts: the Claude accounts and their server token.
- Account Auto-Switch: what moves an agent to another account at a quota limit.
- Remote Fleet: run agents on your other AgentsRoom machines instead of a bare server.
- Linux Server Mode: AgentsRoom itself on the server, with no screen, your computer can be off.
- Agent Teams: team runs on a remote project.
- AgentsRoom MCP: the tools installed on the host.
- Secret Manager: where the SSH credential lives.
- Remote Agent Control: pilot the offloaded agent from the phone.
- Git Worktrees: the ticket worktrees now cut on the host, and the case that is still refused.