Desktop app fails on startup: agx serve failed to start (local API not available)

[clawbundle]

Description

Summary

When launching AgenticX Desktop (Electron + Vite dev flow), the app shows an error dialog and fails to start the local backend. The UI loads in the browser at http://localhost:5173, but the desktop shell reports that the agx CLI could not be started.

Error message

• Title (localized): AgenticX Desktop 启动失败
• Body (localized): 无法启动本地服务，请检查 agx 是否可用。
• Technical: Error: agx serve failed to start

Expected behavior

Either:

1. The desktop app should start successfully when following the documented setup, or
2. Prerequisites (installing agx, PATH configuration) should be clearly documented before first run, with a actionable error (e.g. “install agx from …”, “add … to PATH”).

Actual behavior

Startup fails with the above error. Vite reports as ready (http://localhost:5173/), but the Electron side cannot spawn or keep agx serve running.

Steps to reproduce

1. Clone the repository and install dependencies under desktop/ (npm install).
2. Start the dev workflow (e.g. npm run dev or the documented desktop dev command).
3. Open the app; observe the error dialog on startup.

Environment

• OS: Windows 10/11 (Git Bash / MINGW64)
• Node / npm: (fill in your versions, e.g. node -v, npm -v)
• Branch: main
• agx: (e.g. agx --version or “not installed / not on PATH”)

Additional context

• The Electron main process appears to run something equivalent to:
  agx serve --host 127.0.0.1 --port <port>.
• If agx is missing from PATH in the environment Electron inherits, or the binary is not installed, startup will fail with this message.

Suggestions (optional)

• Document how to install agx and verify agx is on PATH for GUI-launched processes on Windows.
• Consider detecting missing agx early and surfacing stderr from the spawn attempt in the dialog or logs.
• Optionally support a configurable path to the agx executable for dev setups.

[DemonDamon]

Thanks for the detailed report — this is very helpful.

What was going wrong

On Windows, Electron does not always inherit the same PATH as Git Bash, and the Desktop main process previously only prepended a few well-known locations (conda/scoop-style). After pip install -e ., agx.exe usually ends up under:

• a repo-local .venv\\Scripts (recommended), or
• %LocalAppData%\\Programs\\Python\\Python3xx\\Scripts (python.org installer), or
• %AppData%\\Python\\Python3xx\\Scripts (pip install --user).

Because npm run dev runs with desktop/ as cwd, the parent .venv\\Scripts was easy to miss unless it was also on PATH. In some cases spawn("agx", …) could fail immediately (the generic “agx serve failed to start” path).

What we changed (on main)

desktop/electron/main.ts now:

1. Prepends repo-adjacent .venv / venv Scripts (Windows) or bin (macOS) — resolved from both desktop/ and the parent repo root.
2. On Windows, also prepends common python.org and pip --user script directories.
3. Resolves agx.exe (or fallback) to an absolute path before spawn, and surfaces error.message when spawn fails so logs/dialogs are actionable.

Please pull latest main and retry

From a clean cmd.exe or PowerShell (or Git Bash, but verify with where agx in cmd too):

cd <path-to-your-clone>
git pull origin main

REM Optional but recommended: isolated venv at repo root
py -3 -m venv .venv
.venv\Scripts\activate.bat
python -m pip install -U pip
pip install -e .

where agx
agx --version

cd desktop
npm install
npm run dev

If it still fails, please paste:

• Output of where agx and agx --version from cmd.exe
• The full error text from the dialog (it should now include a system message such as ENOENT when spawn fails)

That will tell us whether it’s still PATH-related or something else (port bind, antivirus blocking the child process, etc.).

Thanks again for filing this.