Building from Source

Build AgentMux from source on Windows, macOS, or Linux. AgentMux is a Rust desktop app with a SolidJS frontend, hosted in a bundled Chromium runtime via CEF (cef-rs).

Prerequisites

Tool	Version	Purpose
Node.js	22 LTS	Frontend build (Vite + SolidJS)
Rust	1.77+	Backend, host, and launcher
Task	Latest	Build orchestration
CMake	3.20+	Required by `cef-dll-sys` (CEF C wrapper)
Ninja	1.10+	Required by `cef-dll-sys`

Platform-Specific Dependencies

macOS

xcode-select --install
brew install cmake ninja
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Windows

Install Rust from rustup.rs.
Install Visual Studio Build Tools — select “Desktop development with C++” (provides CMake and Ninja).
Verify Ninja is on PATH. The Visual Studio install ships Ninja inside Common7/IDE/CommonExtensions/Microsoft/CMake/Ninja/; copy or symlink ninja.exe to a PATH entry. From Git Bash (note: the * must be unquoted so the shell expands it):
Terminal window
```
cp /c/Program\ Files/Microsoft\ Visual\ Studio/*/Community/Common7/IDE/CommonExtensions/Microsoft/CMake/Ninja/ninja.exe /c/Systems/bin/
```
Or substitute the actual edition (Community, Professional, Enterprise) and year (2022, etc.) so no glob is needed.

Linux (Debian/Ubuntu)

sudo apt install build-essential cmake ninja-build curl wget file libssl-dev
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Install Task

# macOS
brew install go-task/tap/go-task

# Linux
sudo snap install task --classic

# Windows
winget install Task.Task

Clone and Install

git clone https://github.com/agentmuxai/agentmux.git
cd agentmux
npm install

Development

task dev

This launches the four-process app with Vite hot reload. The frontend rebuilds on save (SolidJS HMR via Vite); changes to the Rust crates require a rebuild and restart.

After code changes

Changed	Action
Frontend (TypeScript / SolidJS)	Auto-reloads via Vite HMR
Rust sidecar (`agentmux-srv/`)	`task build:backend`, then restart `task dev`
Rust host (`agentmux-cef/`)	`task build:host`, then restart `task dev`
Launcher (`agentmux-launcher/`)	`task package` (only relevant for portable / installed builds)

Build Commands

Command	Description
`task dev`	Development mode (CEF host + Vite hot reload)
`task build:host`	Build the CEF host binary
`task bundle`	Bundle CEF runtime DLLs
`task build:backend`	Build `agentmux-srv`
`task build:frontend`	Build frontend only
`task package`	Package a portable build for the host platform (Windows ZIP)
`task package:linux`	Linux AppImage (writes to `~/Desktop` per `build-appimage-linux.sh`)
`task test`	Run tests (`vitest`)
`task clean`	Clean build artifacts

Run task --list to see every task. Note that task package:macos and task package:msix exist as TODO stubs in Taskfile.yml but do nothing — the full DMG / MSIX / .deb release artifact set is produced by agentmuxai/agentmux-builder, not local builds.

Source Layout

agentmux/
├── agentmux-launcher/   # Launcher shim (≈325 KB) — spawns the host, owns OS-level facts
├── agentmux-cef/        # CEF host — embeds Chromium, owns the OS window
├── agentmux-srv/        # Sidecar — RPC engine, SQLite persistence, sagas
├── agentmux-common/     # Shared utilities (path resolution, runtime mode)
├── frontend/            # SolidJS + TypeScript (Vite)
├── docs/                # Architecture docs and specs
├── specs/               # Top-level specs
└── Taskfile.yml         # Build task definitions

Communication Flow

launcher ◀── named pipe ──▶ host (CEF)
                              │
                              ├── JS bridge ──▶ renderer (SolidJS)
                              │
                              ├── websocket ──▶ sidecar (agentmux-srv)
                              │                   │
                              │                   └── websocket / wshrpc ──▶ remote `wsh`
                              │
                              ▼
                         OS window, browser panes

See Architecture overview for the full topology and what each edge carries.

Debugging

Frontend

Open Chromium DevTools from the hamburger menu (≡) in the top tab bar → Dev Tools, or use the keyboard shortcut. DevTools is no longer a widget-bar entry (moved to the hamburger menu — see Pane types). Reload the renderer with Ctrl+R / Cmd+R.

Backend Logs

Logs land in <data-dir>/logs/ for the running version. Use the muxlog shell helper from any AgentMux terminal:

muxlog host         # tail the current host log
muxlog srv          # tail the sidecar log
muxlog host '[fe]'  # filter the host log to frontend lines
muxlog host cat     # full file contents

See Multi-instance & dev mode for the per-instance path layout and pointer-file resolution.

Troubleshooting

CMake / Ninja errors

If cargo build fails with “CMake was unable to find a build program corresponding to Ninja”, verify ninja --version works on PATH. On Windows, see the install steps above.

Backend binary not found

Run task build:backend and verify the binary lands in target/release/ (or the platform-equivalent location). The host auto-spawns the sidecar by absolute path.

Frontend not loading

Check the Vite dev port (task dev prints it on startup) is not already in use. Clear and reinstall if needed:

rm -rf node_modules package-lock.json
npm install
task dev

Schema directory missing after clean

dist/schema/ is wiped by task clean but automatically recreated by the copy:schema dependency in dev, start, and package tasks.