feat: bundle Python backend into desktop app (PyInstaller sidecar) + close packaging gaps

Gap 1 — Backend bundling:
- backend/vortex-backend.spec: PyInstaller spec -> single vortex-backend exe
- backend/backend_entry.py: entry point importing app.main directly (not by
  string) so PyInstaller bundles the full import graph; --host/--port flags
- Verified: bundled exe serves /api/v1/health + /settings standalone

Gap 2 — Real backend lifecycle in main.rs:
- BackendState(Mutex<Option<CommandChild>>) tracks spawned process
- stop_backend now kills the child (was a stub)
- start_backend prefers the PyInstaller sidecar, falls back to python-uvicorn
  for dev; refuses double-start
- get_backend_status: real HTTP health check (reqwest added)
- tauri.conf.json: externalBin binaries/vortex-backend

Gap 3 — User-data dirs:
- config.py: %APPDATA%/Vortex (Win), ~/Library/Application Support/Vortex
  (mac), ~/.local/share/Vortex (linux); VORTEX_HOME still overrides for dev
- config/memory/logs/models subdirs; settings.json + vortex.log moved there

Gap 4 — Apple Silicon + CI bundling:
- build matrix adds macos-arm64 (aarch64-apple-darwin)
- CI build job now runs PyInstaller and places the target-triple-named
  sidecar before tauri:build
- gitignore: backend/dist, build, .build-venv, frontend binaries

Author: seven0070

.github/workflows/ci.yml

@@ -75,6 +75,9 @@ jobs:
           - os: macos-latest
             platform: macos
             target: x86_64-apple-darwin
+          - os: macos-latest
+            platform: macos-arm64
+            target: aarch64-apple-darwin
           - os: ubuntu-latest
             platform: linux
             target: x86_64-unknown-linux-gnu
@@ -110,6 +113,30 @@ jobs:
           sudo apt-get install -y libwebkit2gtk-4.1-dev libappindicator3-dev \
             librsvg2-dev patchelf libgtk-3-dev
 
+      - name: Set up Python (backend bundling)
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+
+      - name: Bundle backend with PyInstaller
+        working-directory: backend
+        run: |
+          pip install -r requirements.txt pyinstaller
+          python -m PyInstaller vortex-backend.spec --noconfirm
+
+      - name: Place sidecar for Tauri (target-triple naming)
+        shell: bash
+        run: |
+          mkdir -p frontend/src-tauri/binaries
+          # Tauri requires: <name>-<target-triple><ext>
+          SIDECAR="frontend/src-tauri/binaries/vortex-backend-${{ matrix.target }}"
+          case "${{ matrix.platform }}" in
+            windows*) cp backend/dist/vortex-backend.exe "$SIDECAR.exe" ;;
+            macos*)   cp backend/dist/vortex-backend "$SIDECAR" ;;
+            linux*)   cp backend/dist/vortex-backend "$SIDECAR" ;;
+          esac
+          ls -la frontend/src-tauri/binaries/
+
       - name: Build Tauri app
         working-directory: frontend
         run: npm run tauri:build

.gitignore

@@ -19,6 +19,12 @@ frontend/build_tauri.log
 frontend/src-tauri/target/
 frontend/src-tauri/gen/
 
+# PyInstaller backend bundle (built by CI, not committed)
+backend/dist/
+backend/build/
+backend/.build-venv/
+frontend/src-tauri/binaries/
+
 # Editor / OS
 .vscode/
 .idea/

backend/app/vortex/config.py

@@ -1,20 +1,57 @@
 # Backend configuration
 import os
+import sys
 from pathlib import Path
 
-# Resolve paths relative to this file
-BASE_DIR = Path(__file__).resolve().parent.parent.parent  # backend/
+# Resolve paths relative to this file (backend/)
+BASE_DIR = Path(__file__).resolve().parent.parent.parent
 
-# Data directory for persistence
-DATA_DIR = os.getenv('VORTEX_HOME', str(BASE_DIR / 'vortex-data'))
-DATA_DIR = Path(DATA_DIR)
 
-# Ensure data directory exists
+def _default_data_dir() -> Path:
+    """Platform-appropriate user-data directory (never the install dir).
+
+    Windows: %APPDATA%/Vortex          (e.g. C:/Users/<u>/AppData/Roaming/Vortex)
+    macOS:   ~/Library/Application Support/Vortex
+    Linux:   $XDG_DATA_HOME or ~/.local/share/Vortex
+    """
+    if sys.platform == "win32":
+        base = os.getenv("APPDATA") or str(Path.home() / "AppData" / "Roaming")
+        return Path(base) / "Vortex"
+    if sys.platform == "darwin":
+        return Path.home() / "Library" / "Application Support" / "Vortex"
+    # Linux / other POSIX
+    base = os.getenv("XDG_DATA_HOME") or str(Path.home() / ".local" / "share")
+    return Path(base) / "Vortex"
+
+
+def _resolve_data_dir() -> Path:
+    """VORTEX_HOME env wins; fall back to platform user-data dir.
+
+    Dev override: set VORTEX_HOME=backend/vortex-data to keep data in-repo
+    during development (the smoke tests do exactly this).
+    """
+    env = os.getenv("VORTEX_HOME")
+    if env:
+        return Path(env)
+    return _default_data_dir()
+
+
+# Data directory for persistence (user-data dir by default)
+DATA_DIR = _resolve_data_dir()
 DATA_DIR.mkdir(parents=True, exist_ok=True)
 
 # Database path
 SQLITE_URL = f"sqlite:///{DATA_DIR / 'vortex.db'}"
 
+# Sub-directories for separation of concerns
+CONFIG_DIR = DATA_DIR / "config"
+MEMORY_DIR = DATA_DIR / "memory"
+LOG_DIR = DATA_DIR / "logs"
+MODELS_DIR = DATA_DIR / "models"
+
+for _d in (CONFIG_DIR, MEMORY_DIR, LOG_DIR, MODELS_DIR):
+    _d.mkdir(parents=True, exist_ok=True)
+
 # Logging configuration
 LOGGING_CONFIG = {
     'version': 1,
@@ -30,7 +67,7 @@
         },
         'file': {
             'formatter': 'standard',
-            'path': str(DATA_DIR / 'vortex.log'),
+            'path': str(LOG_DIR / 'vortex.log'),
             'maxBytes': 1024 * 1024 * 5,  # 5 MB
             'backupCount': 3,
         },
@@ -39,4 +76,4 @@
         'level': 'INFO',
         'handlers': ['default', 'file'],
     },
-}
+}

backend/app/vortex/settings.py

@@ -13,9 +13,9 @@
 import os
 from pathlib import Path
 
-from .config import DATA_DIR
+from .config import CONFIG_DIR
 
-SETTINGS_FILE = Path(DATA_DIR) / "settings.json"
+SETTINGS_FILE = CONFIG_DIR / "settings.json"
 
 DEFAULTS = {
     "llm_base_url": "http://localhost:8645/v1",

backend/backend_entry.py

@@ -0,0 +1,42 @@
+#!/usr/bin/env python3
+"""PyInstaller entry point — starts the Vortex backend with CLI passthrough.
+
+Usage:
+    vortex-backend.exe [--host 0.0.0.0] [--port 8000]
+"""
+
+import argparse
+import os
+import sys
+
+# Make bundled `app` package importable regardless of CWD
+_HERE = os.path.dirname(os.path.abspath(__file__))
+if _HERE not in sys.path:
+    sys.path.insert(0, _HERE)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Vortex Agent backend server")
+    parser.add_argument("--host", default=os.getenv("VORTEX_HOST", "0.0.0.0"))
+    parser.add_argument("--port", type=int, default=int(os.getenv("VORTEX_PORT", "8000")))
+    parser.add_argument("--no-reload", action="store_true", help="disable auto-reload (release)")
+    args = parser.parse_args()
+
+    # Import the ASGI app DIRECTLY (not via string) so PyInstaller's static
+    # analysis follows the full import graph and bundles every module.
+    from app.main import app  # noqa: E402
+
+    import uvicorn
+
+    uvicorn.run(
+        app,  # app object, not "app.main:app" string
+        host=args.host,
+        port=args.port,
+        reload=False,  # never reload in a frozen bundle
+        log_level="info",
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

backend/vortex-backend.spec

@@ -0,0 +1,84 @@
+# -*- mode: python ; coding: utf-8 -*-
+"""PyInstaller spec — bundle the Vortex FastAPI backend into a single exe.
+
+Build (Windows):
+    cd backend
+    pip install pyinstaller
+    pyinstaller vortex-backend.spec
+
+Output: dist/vortex-backend.exe
+        (Tauri sidecar expects it at frontend/src-tauri/binaries/vortex-backend.exe)
+
+The exe serves the API on 0.0.0.0:8000 with --host/--port passthrough:
+    vortex-backend.exe [--host 0.0.0.0] [--port 8000]
+"""
+
+import os
+from pathlib import Path
+
+ROOT = Path(SPECPATH)  # backend/ (where the spec lives)
+
+a = Analysis(
+    ["backend_entry.py"],
+    pathex=[str(ROOT)],
+    binaries=[],
+    datas=[
+        # package data if any (e.g. governance policy JSON) would go here
+    ],
+    hiddenimports=[
+        "uvicorn.logging",
+        "uvicorn.loops",
+        "uvicorn.lifespan",
+        "uvicorn.protocols",
+        "uvicorn.protocols.http",
+        "uvicorn.protocols.http.auto",
+        "uvicorn.protocols.websockets",
+        "uvicorn.protocols.websockets.auto",
+        "uvicorn.lifespan.on",
+        "uvicorn.lifespan.off",
+        "sqlalchemy.dialects.sqlite",
+        "app.api.v1.routers",
+        "app.api.v1.settings",
+        "app.core.llm_client",
+        "app.core.memory_system",
+        "app.core.orchestration",
+        "app.core.tools",
+        "app.council.council",
+        "app.governance.governance",
+        "app.sovereign.sovereign",
+        "app.knowledge.graph",
+        "app.evolution.evolution_engine",
+        "app.observability.trace",
+        "app.tools.tool_registry",
+        "app.vortex.config",
+        "app.vortex.settings",
+    ],
+    hookspath=[],
+    hooksconfig={},
+    runtime_hooks=[],
+    excludes=[],
+    noarchive=False,
+)
+
+pyz = PYZ(a.pure)
+
+exe = EXE(
+    pyz,
+    a.scripts,
+    a.binaries,
+    a.datas,
+    [],
+    name="vortex-backend",
+    debug=False,
+    bootloader_ignore_signals=False,
+    strip=False,
+    upx=True,
+    upx_exclude=[],
+    runtime_tmpdir=None,
+    console=True,  # console window so logs are visible in dev; False for release
+    disable_windowed_traceback=False,
+    argv_emulation=False,
+    target_arch=None,
+    codesign_identity=None,
+    entitlements_file=None,
+)

frontend/src-tauri/Cargo.lock

@@ -31,6 +31,9 @@ tokio = { version = "1", features = ["full"] }
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 
+# HTTP client (backend health check)
+reqwest = { version = "0.12", features = ["blocking"], default-features = false }
+
 # Logging
 tracing = "0.1"
 tracing-subscriber = { version = "0.3", features = ["env-filter"] }