Windows and Linux
- Desktop app
- All plans
What it does
AgentsRoom desktop runs on macOS, Windows and Linux with the same interface, the same settings and the same mobile pairing. On Windows the agent terminals run through the native console layer (ConPTY) with PowerShell, agent CLIs are found on the Windows PATH (including .cmd shims installed by npm), and git diffs handle Windows paths and CRLF files. On Linux the app behaves like on macOS. Keyboard shortcuts use Ctrl where macOS uses Cmd.
Where to find it
- Downloads: the site's download page, sections Windows and Linux. The Windows button downloads the installer straight away (since 2026-10-12 there is no warning window in between); the Linux section keeps its Installing on Linux help modal.
- Windows: an installer for x64 and ARM64; you can choose the installation directory, installed per user.
- Linux: a .deb package (recommended on Ubuntu, Debian and derivatives) or a portable AppImage for any distribution.
How to use it
- Windows: download the installer. If the browser flags it, choose Keep; if Windows Defender shows the blue SmartScreen screen, click More info then Run anyway. Run the installer and pick a directory if you wish.
- Linux .deb: double-click it in the software center or install it from a terminal; trailing debconf and apt warnings after "Setting up desktop" are harmless.
- Linux AppImage: make the file executable and run it. On Ubuntu 22.04 and newer install FUSE first if it refuses to start (
sudo apt install libfuse2). Alibz.soerror means a corrupt download: fetch it again. - Launch, install or sign in to your agent CLIs as on macOS; the setup assistant detects them.
Settings
disableHardwareAcceleration(global, Settings > Appearance > Rendering > Disable hardware acceleration): draws the interface on the processor instead of the graphics card. Off by default. Turn it on when a faulty display driver corrupts the window, and only then: CPU rendering costs performance everywhere else. The switch reads Hardware acceleration on or Hardware acceleration off (CPU rendering), and once changed the row says Applies at the next launch. next to a Restart now button.
Nothing else is platform-specific. Platform-dependent labels in Settings tell you what applies (for example the wake-timer status under Settings > Terminal explains that Windows uses the Task Scheduler and that wake timers must be allowed in the power plan).
Agent tools (MCP)
None specific. The AgentsRoom MCP server works identically on the three systems.
Providers
All providers that ship a CLI for the platform. Detection probes the PATH plus the usual Windows locations (npm global folder, WindowsApps, scoop, cargo). A CLI that is not distributed for Windows or Linux is simply absent from the list.
Mobile
The phone pairs with a Windows or Linux desktop exactly like with a Mac.
Limits
- Windows installers are code-signed and timestamped, so Windows names the publisher, but SmartScreen trusts each new build by reputation and AgentsRoom ships often: a brand-new version can be flagged for a few days. Nothing is wrong with the file.
- Some antivirus products have quarantined unsigned older builds; if the app "disappears", reinstall the current version. Since 2026-11-10 every file AgentsRoom ships on Windows is signed (its native modules and Electron's DLLs included), and the bundled Microsoft terminal component keeps Microsoft's own signature instead of being re-signed by AgentsRoom, to give antivirus products fewer reasons to flag the app.
- Windows performance: process creation and file access are much slower than on macOS, and Chromium may fall back to software rendering in a VM or over Remote Desktop, which makes typing feel laggy. Running on real hardware with a working graphics driver fixes most of it.
- A display driver that corrupts the window is the driver's doing, not the app's: nothing the interface draws can repaint around it, which is why the only answer is the Disable hardware acceleration switch. It is read at startup, so it never takes effect on the running window.
- Windows: the hidden-terminal reading of a CLI's
/usageor/statusscreen (the only quota source for Grok and Kimi, the fallback for Claude and Codex) is available since 1.173.0; before that the Grok and Kimi gauges were missing on Windows. It is slower there, because a PowerShell profile can take several seconds to reach its prompt. Codex session detection uses a working-directory heuristic instead of an exact match. - Zoom shortcut: Ctrl + may require Ctrl = without Shift on some layouts; the View menu items always work.
- Linux: when the display server or compositor crashes (seen under WSL2 with WSLg), the app cannot survive it, but since 2026-09-24 it relaunches itself a few seconds after the display comes back and restores its consoles and team runs the usual way (Restore Session). At most three relaunches per ten minutes; a crash unrelated to the display is never relaunched. Nothing to set, and nothing of the kind on macOS or Windows.
- Linux on Wayland (GNOME, KDE...): AgentsRoom runs through XWayland, as it always did, so it can place its own windows and hold global shortcuts. To try native Wayland anyway, start it with
AGENTSROOM_NATIVE_WAYLAND=1or--ozone-platform=wayland; without an X server (no XWayland) it uses Wayland on its own. - Linux on a tiling Wayland compositor (Hyprland, Sway, niri, river, dwl, scroll, mango, miracle-wm, jay, qtile): AgentsRoom runs as a native Wayland app by default, and the compositor manages every window. Detached windows tile like the main one, follow the display scale without
--force-device-scale-factor, and draw no minimize, maximize or close buttons. The app sets no position, minimum size or maximize, so Reopen at the previous size and the pinned screen in Global settings have no effect there. The Dynamic Island stays off, because it would become a tile. Input methods (fcitx5, IBus) work through--enable-wayland-ime. The interface size comes from the compositor's scale alone: GTK's text size (text-scaling-factor, oromarchy display text sizeon Omarchy) no longer enlarges the whole app; to change the app's size, use Settings > Appearance > Zoom. To go back to XWayland, setAGENTSROOM_NATIVE_WAYLAND=0or start with--ozone-platform=x11. - Global shortcuts on a tiling compositor (region screenshot, voice push-to-talk) go through the desktop portal, so the compositor owns the key. On Hyprland, run
hyprctl globalshortcutsto find the shortcut, then add abindwith theglobaldispatcher. Sway has no portal backend for them, and support on niri and the other compositors depends on your portal setup: if the shortcut does nothing, use the on-screen button. - Secondary windows on Linux open with a stable title,
AgentsRoom - <panel>(for exampleAgentsRoom - terminals), and the same class as the main window (agentsroom), which is enough to write a compositor rule. A project or command window then renames itself, so match its initial title. File dialogs open over the window that asked for them. - Linux with no screen (Ubuntu Server, a VPS): a plain launch fails with "Missing X server or $DISPLAY", and says to use
agentsroom --server, which runs the app with no window. See Linux Server Mode. - Cloud Agents, tunnels and the relay do not depend on the OS.
Common questions
- Windows says "Unknown publisher" or blocks the installer. Click More info, then Run anyway. The installer is signed; the warning is SmartScreen reputation on a fresh build.
- AgentsRoom vanished when my display restarted under WSL2 / Linux. Since 2026-09-24 it comes back by itself once the display answers again, with its consoles and team runs restored. If it does not, update AgentsRoom.
- On Windows, AgentsRoom closed by itself while agents were working, with no error. Fixed on 2026-10-09: Windows reuses process numbers, and closing an agent or a terminal could end an older program that happened to carry the number of a dead parent, AgentsRoom itself or another app restarted by its own updater. Closing an agent or a terminal now only stops that terminal's own processes. A tool run by an agent can still hit the same Windows behaviour on its own; when the app stops without being quit, the cause is now written to the app's log at the next launch.
- Does AgentsRoom run as a native Wayland app? On a tiling compositor (Hyprland, Sway, niri...), yes, by default. On GNOME, KDE and other desktops it stays on XWayland so it can place its own windows; set
AGENTSROOM_NATIVE_WAYLAND=1before launching it to opt in, with those limits. - On Hyprland or Sway, how do I go back to XWayland? Set
AGENTSROOM_NATIVE_WAYLAND=0(for example withenv = AGENTSROOM_NATIVE_WAYLAND,0inhyprland.conf) or start the app with--ozone-platform=x11. The Dynamic Island comes back, and the windows are XWayland ones again, with the blur that brings on a scaled display. - The interface is too large on Hyprland, Sway or niri at a fractional scale, with the zoom at 100%. Fixed on 2026-11-05 for the usual cause: a GTK text size (
text-scaling-factor, set on Omarchy byomarchy display text size) multiplied the whole interface on top of the compositor's scale. Update AgentsRoom and restart it. If it is still too large, remove any--force-device-scale-factoryou added by hand: on native Wayland it multiplies the compositor's scale, so1.6on a 1.6 screen gives 2.56. Under XWayland (AGENTSROOM_NATIVE_WAYLAND=0) the size comes fromGDK_SCALE, which only takes whole numbers; there,--force-device-scale-factor=1.6is still the way to get 1.6. To check: in the app's developer console,devicePixelRatioshould equal your monitor's scale. For a size of your own, use Settings > Appearance > Zoom. - My global shortcut does nothing on Hyprland. On native Wayland the compositor owns the key: run
hyprctl globalshortcutsto find the shortcut, then bind it, for examplebind = SUPER SHIFT, S, global, <the name it lists>. The composer button keeps working either way. - The Dynamic Island disappeared on my tiling compositor. That is intended: it would have become a tile. Settings says so where the island settings used to be.
- Can it run on Ubuntu Server, with no desktop environment? Yes, with
agentsroom --server: see Linux Server Mode. - Can a Windows PC be one of my machines in Remote Fleet? Yes: install the app and sign in to the same account (Remote Fleet). Agents started there follow the tool switches like anywhere else (AgentsRoom tools settings). The app has to stay open, since
agentsroom --serveris Linux only. The Claude Code hooks need Python on that PC (python.exeor thepylauncher): without it no hook is written, statuses come from the terminal, and the approval asked before an agent drives the browser is not there. A Windows host reached over SSH is a different mode: terminal only, no agents (Remote SSH Offload). - The app does not start and says "libasound.so.2" or "libgbm.so.1" is missing. A minimal install lacks what a desktop always has.
sudo apt install libgbm1 libasound2t64 python3(libasound2before Ubuntu 24.04); packages since 2026-11 pull them in. - The AppImage crashes or closes right after starting on Wayland, or stays closed after an update. Fixed on 2026-11-04. On GNOME and KDE the AppImage restarts itself once to run through XWayland, and that restart could die with a SIGBUS, leaving no window. Update AgentsRoom; until then, start it with
--ozone-platform=x11, which skips the restart. - Which Linux package should I pick? .deb on Ubuntu, Debian and derivatives; AppImage elsewhere. Both auto-update.
- Does the ARM64 Windows build exist? Yes, the installer covers x64 and ARM64.
- The app is slow on my Windows PC. Check you are not in a VM or Remote Desktop session and that the graphics driver is active; software rendering is the usual cause.
- Noise or "frost" creeps across the window, and text garbles then clears when I hover it. That is the display driver corrupting what the graphics card draws. Settings > Appearance > Rendering > Disable hardware acceleration, then Restart now: the interface is drawn on the processor instead and the artefacts go. Turn it back off if a driver update fixes your machine.
Related
- Linux Server Mode: running on a machine with no screen.
- Auto-update: how updates install on each system.
- CLI Doctor: diagnosing a CLI that fails to start.
- Keep the Machine Awake: wake timers and power assertions per OS.
- Restore Session: what comes back after a relaunch.
- Appearance Customization: the Appearance tab the rendering switch lives in.