Skip to main content

Desktop App Setup (macOS / Windows)

The Agentrix Desktop app is the recommended way to use Agentrix on macOS and Windows. It is a self-contained application — no pre-installed Node.js or package manager is required.

Download​

Download the installer from agentrix.xmz.ai:

  • macOS — .dmg file (supports both Apple Silicon and Intel)
  • Windows — .exe installer

macOS installation​

  1. Open the .dmg file.
  2. Drag Agentrix to the Applications folder.
  3. Launch Agentrix from Applications or Spotlight.

On first launch macOS may show a security prompt. Go to System Settings → Privacy & Security and click Open Anyway.

Windows installation​

  1. Run the .exe installer.
  2. Follow the installation wizard.
  3. Agentrix will launch automatically when the installer finishes.

First-Time Setup​

On the first launch, the app opens a Dependency Setup screen. It checks for and installs each required tool automatically.

macOS dependencies​

ToolHow it is installed
HomebrewOfficial install script
Node.jsManaged runtime (downloaded into ~/.agentrix/node-runtime/)
Gitbrew install git
ripgrepbrew install ripgrep
Claude CLIbrew install --cask claude-code
Codex CLInpm install -g @openai/codex
Agentrix CLInpm install -g @agentrix/cli

Windows dependencies​

ToolHow it is installed
ScoopOfficial PowerShell install script
Node.jsManaged runtime (downloaded into %USERPROFILE%\.agentrix\node-runtime\)
Gitscoop install git
Claude CLInpm install -g @anthropic-ai/claude-code
Codex CLInpm install -g @openai/codex
Agentrix CLInpm install -g @agentrix/cli

The app shows live output for each step and lets you retry if a step fails. You do not need to run any commands manually.

Authentication​

After dependencies are installed, the app opens the Agentrix login page in your browser. Sign in to your account and the app receives the authentication token automatically via a deep-link callback (agentrix-desktop://).

The token is stored in ~/.agentrix/credentials.json and shared with the CLI daemon.

System Tray​

After setup, Agentrix runs as a system tray icon (macOS menu bar / Windows notification area).

The tray icon indicates daemon status at a glance:

Icon stateMeaning
● RunningDaemon is running and accepting tasks
◐ StartingDaemon is starting up
○ StoppedDaemon is not running

Right-click the tray icon to open the context menu:

  • Show Dashboard — open the main app window
  • Open Web App — open agentrix.xmz.ai in your browser
  • Daemon → Start / Stop / Restart — control the daemon
  • Quit — exit the Desktop app (daemon is stopped)

App Window​

Click the tray icon (or choose Show Dashboard) to open the main window. It embeds the Agentrix web app, so you have access to tasks, settings, and team features without leaving the desktop app.

Settings​

The Desktop app reads and writes the same ~/.agentrix/settings.json as the CLI. You can edit it directly or use the Settings screen in the app.

See Settings for the full configuration reference.

Updates​

The Desktop app checks for updates on launch. When a new version is available it will prompt you to update.

The Agentrix CLI component (@agentrix/cli) inside the app is also updated separately through the dependency manager.

Uninstall​

macOS​

  1. Quit the app from the tray menu.
  2. Move Agentrix.app from Applications to Trash.
  3. Optionally remove state data:
rm -rf ~/.agentrix

Windows​

  1. Quit the app from the tray menu.
  2. Uninstall via Settings → Apps → Agentrix.
  3. Optionally remove state data from %USERPROFILE%\.agentrix.

Next Steps​