Desktop App

Forgexa Desktop is a native application built with Tauri 2, wrapping the web frontend with integrated daemon management, system tray, and OS notifications.

Runtime Requirements

Forgexa Desktop embeds a Python-based daemon that executes AI agent tasks on your machine. Python 3.9 or later must be installed before you can use the daemon features.

Check Your Python Version

# macOS / Linux
python3 --version

# Windows
python --version

You should see Python 3.9.x or higher.

Install Python

1. Download the Windows installer from python.org/downloads.
2. Run the installer. On the first screen, check "Add Python to PATH" before clicking Install.
3. Open a new terminal and verify:

   python --version

4. In the Forgexa app, open Settings → Daemon and click Start.

Do not use the Microsoft Store version

Windows 11 places a python.exe stub in %LOCALAPPDATA%\Microsoft\WindowsApps. When Python is not actually installed this stub silently exits without launching any interpreter, which causes the daemon to fail with no log output. Always install from python.org.

Symptom: repeated "SESSION START" with nothing after it

If you open %USERPROFILE%\.forgexa\daemon\daemon.log and see only repeated === DAEMON SESSION START === lines, Python is missing or installed incorrectly. Install Python from python.org and restart the app.

Required Python Packages

The daemon installs its own dependencies automatically on first start. No manual pip install is needed — the app handles this.

Download & Install

Download the latest release from the Releases page.

Platform	Format	Notes
macOS	.dmg	Universal binary (Intel + Apple Silicon)
Linux (Debian/Ubuntu)	.deb	Ubuntu 22.04+
Linux (other)	.AppImage	Any modern distro
Windows	.msi, .exe	Windows 10+ (.msi = WiX, .exe = NSIS)

Unsigned Installer

The current release is not code-signed. Follow the platform-specific steps below to bypass OS security warnings.

macOS

1. Open the downloaded .dmg file (e.g., Forgexa_1.2.3_universal.dmg)
2. Drag Forgexa.app to the Applications folder
3. Remove the quarantine attribute so macOS allows it to run:

sudo xattr -cr /Applications/Forgexa.app

If macOS blocked the .dmg itself before you could complete the drag, clear the quarantine on the download first, then repeat steps 1–3:

sudo xattr -cr ~/Downloads/Forgexa_1.2.3_universal.dmg

After that, double-click Forgexa in Applications to launch.

Linux — .deb (Ubuntu / Debian)

sudo dpkg -i ~/Downloads/Forgexa_1.2.3_amd64.deb

Launch from the Applications menu or run forgexa in a terminal.

Linux — .AppImage

chmod +x ~/Downloads/Forgexa_1.2.3_amd64.AppImage
./Forgexa_1.2.3_amd64.AppImage

You can also install AppImageLauncher to integrate AppImages into the system menu.

Windows

Two installer formats are available — choose either:

Option A — .exe (NSIS, recommended for most users)

1. Double-click Forgexa_1.2.3_x64-setup.exe
2. If Windows SmartScreen shows a warning, click More info → Run anyway
3. Follow the installation wizard

Option B — .msi (WiX, for enterprise/group policy deployment)

1. Double-click Forgexa_1.2.3_x64-setup.msi
2. If SmartScreen shows a warning, click More info → Run anyway
3. Follow the installation wizard

Features

• Daemon Management — Start, stop, and restart the Forgexa daemon directly from the UI
• System Tray — Minimize to tray with quick-access menu (Show / Start Daemon / Stop Daemon / Quit)
• Server Connection — Connect to local or remote API servers with automatic health-check
• Native Notifications — Build, test, and gate results delivered via OS notification center
• Auto-start — Optional launch at system login

Prerequisites (Building from Source)

Tool	Version
Rust	1.77+
Node.js	18+
tauri-cli	2.x (cargo install tauri-cli)

Linux Additional Dependencies

sudo apt install libwebkit2gtk-4.1-dev libappindicator3-dev librsvg2-dev patchelf

Development

# Start frontend dev server (separate terminal)
cd frontend && npm run dev

# Start Tauri dev mode (hot-reload)
cd desktop && cargo tauri dev

Building

macOS

./desktop/scripts/build-macos.sh             # Current architecture
./desktop/scripts/build-macos.sh --universal  # Universal binary
./desktop/scripts/build-macos.sh --sign       # With signing & notarization

Linux

./desktop/scripts/build-linux.sh              # .deb + .AppImage
./desktop/scripts/build-linux.sh --deb-only   # .deb only
./desktop/scripts/build-linux.sh --appimage-only

Windows

.\desktop\scripts\build-windows.ps1

Via Makefile

make desktop-dev    # Tauri dev mode
make desktop-build  # Build for current platform