Platform support

AgentMux runs on Windows, macOS, and Linux. This page is the canonical answer to “does X run on my OS?” — bookmark it.

At a glance

Area	Windows	macOS	Linux
Launcher (`agentmux-launcher`)	✅ ships	✅ ships (`task dev` v0.41.0+; packaged DMG v0.42.x+)	✅ ships (AppImage entry point A0 v0.42.x; Unix-socket IPC + reducer + saga A1 v0.42.x)
Host (`agentmux-cef`) — Chromium embed	✅ ships	✅ ships (DMG, v0.42.x+)	✅ ships (AppImage, v0.42.x+)
Sidecar (`agentmux-srv`)	✅ ships	✅ cross-platform	✅ cross-platform
`agentmux-common` (path resolution, runtime mode)	✅ ships	✅ cross-platform	✅ cross-platform
Frontend / SolidJS renderer	✅ ships	✅ runs in any CEF	✅ runs in any CEF
WRR (Window Reality Reconciliation)	✅ Win32 hooks	❌ not planned (by design)	❌ not planned (by design)
Browser pane (CefBrowserView)	✅ ships	✅ ships (v0.42.x+)	✅ ships (v0.42.x+)
Terminal pane (PTY)	✅ ConPTY	✅ posix_openpt	✅ posix_openpt
Shell-integration scripts (bash / zsh / fish / pwsh)	✅ all four	✅ all four	✅ bash + zsh + fish (pwsh optional)
Native window drag (title-bar + floater header)	✅ ships	✅ ships	✅ ships (patched libcef.so, v0.42.x+)
Floating-pane tear-off / redock	✅ ships	✅ ships	✅ ships (Phase A, v0.41+, Wayland desktop)
Per-window opacity	✅ ships (`WS_EX_LAYERED` alpha)	✅ ships (`NSWindow` alpha)	✅ ships (`_NET_WM_WINDOW_OPACITY` on X11/XWayland; the page fades itself on native Wayland)
Native splash screen	✅ ships	✅ ships	✅ ships (X11 window, centered under XWayland too; Wayland fallback when there is no X display)
Crashpad reports	✅ `<data-dir>/cef-cache/Crashpad/`	✅ same path	✅ same path
Sidecar minidumps	✅ crash monitor → `C:\CrashDumps\agentmuxsrv\`	❌ uses macOS crash reporter (`~/Library/Logs/DiagnosticReports/`)	❌ uses systemd-coredump or apport
Portable distribution	✅ `.7z` (`task package`)	✅ DMG, notarized (v0.42.x+)	✅ AppImage (`task package:linux`, v0.42.x+); also `.deb`, `.rpm` and `.tar.gz`
Multi-instance isolation under `~/.agentmux/`	✅ ships	✅ same layout	✅ same layout
Version isolation (per-version single-instance domain + version-scoped runtime dirs)	✅ v0.41.1+	✅ v0.42.x+	✅ v0.42.x+

✅ — supported and tested · 🟡 — partial / in progress · ❌ — not supported

What’s Windows-coupled today

A handful of features are Windows-coupled because they hook directly into Win32:

WRR (Window Reality Reconciliation) — hooks WM_PAINT, SetWindowPos, GetForegroundWindow to reconcile against AgentMux’s reducer model. Windows-only by design: a full macOS/Linux observation layer is not planned — its drift classes are largely Windows-specific defenses, and Wayland exposes no portable per-window event API. The cross-platform safety net is the host’s orphan reconciler; the one real gap (crash-orphan detection) is tracked in #1569, not as a WRR port. task dev on macOS/Linux runs without WRR drift detection. See WRR.
Sidecar crash minidumps — the sidecar’s own crash monitor writes to C:\CrashDumps\agentmuxsrv\ (Debugging → Sidecar crash dumps). On macOS the system Crash Reporter writes to ~/Library/Logs/DiagnosticReports/; on Linux it depends on whether systemd-coredump or apport is installed.

Pages and admonitions in these docs that are Windows-specific are flagged with a :::note[Windows-only] block at the top of the relevant section. If you don’t see a flag, assume it works cross-platform.

What’s cross-platform today

The architecture is designed cross-platform from the start:

The four-process topology (architecture overview) doesn’t change per OS — same launcher / host / sidecar / renderer split.
Path resolution (multi-instance) uses ~/.agentmux/ everywhere; the channel + version sub-dir layout (channels/<ch>/versions/<v>/) is identical across OSes.
Persistence (SQLite + JSONL) is byte-identical. A backup taken on Windows can be restored on macOS or Linux.
Reducer state, sagas, and the frontend slice migration (reducer stack) are pure logic with no OS-specific code.
MuxAPI — every command in the catalog is OS-independent at the wire level.
Version isolation (v0.41.1+ Windows; v0.42.x+ macOS + Linux) — each release version has its own single-instance domain (the launcher’s IPC socket/pipe hash includes the build version). Runtime DBs, CEF cache, host logs, and IPC artifacts are version-scoped under channels/<channel>/versions/<v>/. Agent definitions and settings are channel-wide under channels/<channel>/, so upgrading doesn’t reset your agents or settings.

Per-OS notes

Windows

Path separators in commands and config are \\; the docs uses / for portability — both work in PowerShell and Git Bash.
Use PowerShell 7+ or Git Bash (MSYS2) for the shell-integration scripts. CMD is not supported.
The taskkill recipes in the debugging page expect Windows.
%APPDATA%, %LOCALAPPDATA%, %USERPROFILE% resolve to the standard Windows paths.

macOS

Ships as a notarized .dmg (v0.42.x+). The launcher binary is Contents/MacOS/AgentMux inside the app bundle.
WRR is Windows-only by design — no NSWindow observation layer is planned. The cross-platform safety net is the orphan reconciler (#1569 tracks the remaining crash-orphan gap); see the WRR row in the table above.
Shell integration: bash, zsh, and fish ship by default. PowerShell support is opt-in.

Linux

Ships as an AppImage (task package:linux) — one self-contained file, no installer. System requirements: glibc 2.31+ and FUSE (for the compressed SquashFS mount; pre-installed on most desktop distros — see Installation → Linux for the --appimage-extract fallback if FUSE is absent).
Launch flow: AppRun → linux-apprun.sh → agentmux-launcher (the AppImage entry point). The launcher supervises the sidecar and host as a process group. On first launch the AppImage extracts itself to ~/.local/share/agentmux/extracted/<version>/ for faster subsequent starts.
Single-instance IPC: Unix domain socket at $XDG_RUNTIME_DIR/agentmux/<hash>.sock (fallback: /tmp/agentmux-<uid>/<hash>.sock). The full reducer + saga coordinator runs on Linux (A1, v0.42.x+) — same feature set as Windows.
Display server: defaults to XWayland (--ozone-platform=x11). Set AGENTMUX_OZONE_PLATFORM=wayland for native Wayland (experimental).
Window drag: requires the patched libcef.so bundled in all release AppImages (CefWindow::BeginWindowDrag() dispatches xdg_toplevel.move / _NET_WM_MOVERESIZE).
Wayland app_id: agentmux. Desktop file: agentmux.desktop (auto-registered by the AppImage on first launch).
WRR: Windows-only by design — no Linux equivalent is planned (Wayland exposes no portable per-window event API); the launcher runs without drift detection, with the orphan reconciler as the safety net.

Reading the docs across platforms

When you see a recipe like:

# Windows
muxlog host '\[fe\]'

it works the same on macOS and Linux unless an explicit :::note[Windows-only] flag says otherwise. Path examples use ~/.agentmux/... consistently — the env var AGENTMUX_LOG_DIR resolves to the right per-instance path regardless of OS.

If a section is genuinely Windows-coupled, you’ll see a flag like this:

:::note[Windows-only]
This recipe relies on Windows Error Reporting. macOS and Linux equivalents are documented above the table.
:::

Roadmap

Cross-platform parity priority order (subject to change):

Window transparency on Linux — root cause identified (views::SolidBackground), fix in progress.
Native splash screen on Linux — Windows and macOS already have it; Linux splash is spec-complete and ready to implement.
Native crash-reporting hookup — replace the Windows-WER-only path with per-OS native handlers feeding into a unified diagnostics view.
Native Wayland (non-XWayland) — experimental today; stability work ongoing.

WRR equivalents on macOS/Linux are deliberately not on this list — WRR is Windows-only by design, with the orphan reconciler as the cross-platform safety net (#1569; see WRR).

Track progress on GitHub Discussions and the main agentmux repo.