Linux Server Mode

  • Desktop app
  • All plans

What it does

Runs AgentsRoom on a Linux machine with no screen and no desktop environment: Ubuntu Server, Debian, a VPS, a home server. agentsroom --server starts the app with no window. You sign it in with a code confirmed from another device, and from then on it is one of your computers: your phone and the AgentsRoom app on your other machines see its projects, start its agents, read their terminals and answer their questions. Your own computer can be off in the meantime. It is the same app as on a desktop, so team runs, triggers, agent mail, the backlog and every provider work the same, on the server, without an SSH session open.

It differs from Remote SSH Offload, where AgentsRoom runs on your computer and only the agents run on the server: there, team runs and triggers stop when your computer stops. Here, nothing depends on your computer.

Where to find it

  • On the server, in a terminal: agentsroom --server.
  • To confirm the sign-in, on any device: the page /device of agentsroom.dev. The server prints the link with its code.
  • From your other computers: the sidebar section On my other machines and the Machines chip of the status bar.
  • From the phone: Your desktops in Settings, and the Remote action of a project.

How to use it

  1. Install the package on the server: sudo apt install ./desktop_<version>_amd64.deb (arm64 on an ARM server). The download page lists both.
  2. Install at least one agent CLI and sign in to it on the server, for example npm install -g @anthropic-ai/claude-code, then claude. Git is expected for your projects.
  3. Run agentsroom --server. It prints a link and a code:
[server] Sign this server in to your AgentsRoom account:
[server]   1. Open https://agentsroom.dev/device?code=ABCD-EFGH
[server]      on your computer or your phone.
[server]   2. Check that the code is ABCD-EFGH, then confirm.
  1. Open the link on your computer or your phone, sign in if asked, check the machine and the code, then click Connect. The server prints Signed in as <you>.
  2. Open a project on it: agentsroom --server --open ~/my-repo, run on the server, works whether a server is already running or not. The phone can also do it: pair with the server under Your desktops, then open a directory of that machine. A clone of a repository your account already has joins that project, with its name, agents and backlog, and the console says so: linked to your account project "<name>".
  3. Use it: the project appears in On my other machines on your computers. Click it, start an agent, or pick a ticket's Run on menu.

Keep it running after you log out, and bring it back after a reboot, with a systemd service. Save this as ~/.config/systemd/user/agentsroom.service:

[Unit]
Description=AgentsRoom server
After=network-online.target
Wants=network-online.target

[Service]
ExecStart=/usr/bin/agentsroom --server
Restart=on-failure
RestartSec=10

[Install]
WantedBy=default.target

Then run systemctl --user daemon-reload, systemctl --user enable --now agentsroom and sudo loginctl enable-linger "$USER". journalctl --user -u agentsroom -f shows its log, sign-in code included. systemctl --user stop agentsroom stops it within seconds: the agents stop, and they come back on their conversation at the next start.

With the AppImage, a service must pass the display arguments itself, otherwise the app relaunches and systemd loses track of it: ExecStart=/home/you/AgentsRoom.AppImage --server --ozone-platform=headless --ozone-override-screen-size=1600,1000 --disable-gpu. Started by hand in a terminal, the AppImage relaunches itself once: your prompt comes back, and the link and code appear in the same terminal a moment later. The AppImage needs FUSE (sudo apt install libfuse2t64, or libfuse2 before Ubuntu 24.04).

Settings

None for the mode itself. It is a command-line flag, --server, and --open <path> opens a project (several are accepted).

  • On its first start a server answers two first-launch questions for you, in ~/.agentsroom/settings.json, only if they have no value: walkthroughCompleted becomes true and restoreOnExit becomes always.
  • deviceName (global, this computer only): the name it goes by on your other devices, the system's hostname by default. See Remote Fleet.
  • Every other setting works as usual and is reachable by an agent through settings_set, which is how you change one on a machine whose interface nobody sees.

Agent tools (MCP)

Same tools as on a desktop, none of its own. projects_open opens a directory of the server as a project: a clone of a project of your account joins it, and its answer says so (accountLink). settings_set changes a setting of the server.

Providers

All providers whose CLI runs on Linux, no difference. You install and sign in to each CLI on the server, as on a desktop. Run the server as a normal user: Claude Code refuses its bypass mode as root.

Mobile

Nothing to install or to change on the phone: the server shows up under Your desktops like any computer of your account, and the phone drives it the same way (agents, terminals, backlog, teams, opening a directory). The sign-in confirmation page works in the phone's browser.

Limits

  • Linux only, x64 and ARM64. On macOS and Windows the flag answers that the mode is for Linux: open the app normally, your phone and your other computers reach it the same way.
  • It needs an account. Without a session it stays on its sign-in code and does nothing else.
  • Memory: about 400 MB for the app when idle (measured on Ubuntu 24.04), plus what each agent CLI uses, often 300 MB. CPU when idle: about 5 % of one core.
  • A .deb needs root to update, and nobody can answer a password prompt on a server: when run as a normal user the server prints the commands to run when a version comes out, and the phone shows the same sentence. An AppImage, or a server running as root, downloads the update itself and installs it at the next restart.
  • No screen means no secure keychain by default, so anything that must be encrypted is refused with "No OS keychain is available on this machine": saved SSH and database passwords, vault secrets used as {{secret:NAME}}. A running Secret Service (gnome-keyring, KeePassXC) lifts this.
  • Approve new devices cannot be answered on a server, since its prompt needs a screen: with the switch on, every new device is refused after two minutes and the log says so. Leave it off on a server (the default): any device signed in to your account can then drive it, so protect the account with two-factor sign-in.
  • What needs a screen does nothing there: the embedded browser and the QA Bot, voice mode, global shortcuts, region screenshots, the Dynamic Island, desktop notifications. Phone notifications still work.
  • One server per user account of the machine, like the desktop app. A second start hands its --open over to the running one and leaves.
  • As root, the app runs without the Chromium sandbox and says so. Prefer a dedicated user.

Common questions

  • Can AgentsRoom run on Ubuntu Server without a desktop environment? Yes: agentsroom --server. No Xvfb, no VNC and no X server needed.
  • Can my agents keep working when my laptop is off? Yes, on a server: everything runs there, and your laptop and phone only look at it. It needs the machine to stay on, of course.
  • It fails with "Missing X server or $DISPLAY". That is a plain launch on a machine with no display. Add --server.
  • It fails with "error while loading shared libraries: libasound.so.2" or "libgbm.so.1". Packages before 2026-11 did not declare everything a server is missing. Install them: sudo apt install libgbm1 libasound2t64 python3 (libasound2 before Ubuntu 24.04). Newer packages pull them in.
  • Should I use this or the SSH offload? Server mode if the work must go on with your computer off, or if several computers and a phone share that machine. Remote SSH Offload if you just want agents on a powerful machine while you work at your computer: it installs nothing but the CLI on the server.
  • How do I see the sign-in code of a service? journalctl --user -u agentsroom -f. A code lasts 15 minutes, then a new one is printed.
  • My clone on the server opened as a second project, and my other computer says "Does not have this project open". Versions before 2026-11 gave a clone with no .agentsroom/project.json an identity of its own. Run agentsroom --server --open <folder> again on a current version: the console says now linked to your account project "<name>", the tickets of the duplicate follow, and so does its memory if the project has none. The duplicate's own agents stay behind. Its agents must be stopped first, and the console tells you when they are not.
  • The console says "several projects of your account use this repository". Your account has more than one project on that remote and nothing tells them apart, so the folder opened as a separate project. Delete the projects you no longer use, from your other computer, then open the folder again.
  • Can I keep a clone as a separate project on purpose? Yes: before opening it, give that clone its own .agentsroom/project.json with another projectId. A folder that already carries an identity always keeps it. On a computer with a screen, Duplicate in the project menu does the same.
  • How do I sign a server out? From the phone: Your desktops > Log out from desktop while connected to it. The server then prints a new code and waits.
  • Why does the page ask me to check the machine and the address? Because approving signs that machine in to your account. Only confirm a code you started yourself, just now: someone could send you a link to get their own machine signed in to your account.
  • Do the tool switches and the Claude Code hooks apply on a server? Yes, it is the same app: agents it starts follow the switches of Settings > AgentsRoom tools, of the folder, the project and the agent (AgentsRoom tools settings), and the hooks are written into the project on the server (Turn a Provider Off). Agents launched over SSH from another computer are a different mode (Remote SSH Offload): they keep every tool and get no hook on the host.
  • I only want a script on the server to file cards, not the whole app. Use a server token instead: no app to install, no login to keep alive. See Backlog Server Tokens.
  • Can I see its interface? No, it never paints one. Everything goes through your other devices. To change a setting, ask an agent (settings_set) or use the phone.