A plan for packaging coding-agent-loop as a downloadable Mac app that runs the agent and workspace servers automatically—no browser or manual server startup required.

Today the app runs in a browser: users start the Go agent server (and optionally the workspace server), then open the frontend. This plan describes a standalone Electron app for Runloop that:

• Bundles the agent server and workspace server as binaries inside the app.
• Starts both servers automatically when the user launches the app.
• Opens a single window loading the existing React UI, which talks to localhost.
• Stops both servers when the user quits the app.
• Produces a shareable Mac package (e.g. .dmg) that users can download and run.

Scope: Mac only (Apple Silicon primary; Intel/universal optional). Distribution is a single downloadable artifact (e.g. via GitHub Releases).

┌─────────────────────────────────────────────────────────────────┐
│                     Electron App (user double-clicks)             │
├─────────────────────────────────────────────────────────────────┤
│  Main Process (Node)                                              │
│    1. Check ports 45678 / 45679 availability                      │
│    2. Spawn workspace-server (bundled binary) → port 45679        │
│    3. Spawn agent-server (bundled binary)       → port 45678      │
│    4. Poll /health on both until ready                            │
│    5. Create BrowserWindow → load http://127.0.0.1:45678          │
│    6. On quit: kill both child processes                          │
├─────────────────────────────────────────────────────────────────┤
│  Renderer (existing React frontend)                               │
│    - API base URL: http://127.0.0.1:45678                         │
│    - Workspace API URL: http://127.0.0.1:45679                    │
└─────────────────────────────────────────────────────────────────┘

• Servers run on the user's machine as child processes of the Electron app.
• Binaries live inside the app bundle (e.g. MyApp.app/Contents/Resources/).
• No Docker or extra runtime required; the app is self-contained.

• Status: Released.
• Notes: Dynamic ports implemented. Frontend sync features refined. Binaries built and packaged.

These steps are recommended for a commercial or wide public release to ensure robustness and security.

The standalone Electron application has been successfully packaged and released as v1.21.0.

• DMG: Runloop-1.21.0-arm64.dmg
• ZIP: Runloop-1.21.0-arm64-mac.zip

• Dynamic Port Allocation: Servers now bind to random free ports provided by the OS, eliminating port conflicts with other running instances or services.
• Zero-Dependency Startup: Spawns agent-server and workspace-server sidecar binaries automatically on launch.
• Filesystem Persistence: Configured Go servers to use app.getPath('userData') for databases, logs, and search indices.
• Integrated Frontend: Frontend is served directly via the agent-server.
• Reliable Dev Mode: npm start (with DEV_URL) correctly connects to external backends on standard ports (8000/8081) while packaged app uses internal dynamic ports.

• Code Signing: To distribute outside of local environments, the build process needs an Apple Developer ID.
• Universal Build: Configure electron-builder to produce universal binaries (arm64 + x64) for broader Mac compatibility.
• Security Hardening: Implement Phase 7.2 (IPC Authentication) to secure the local API.

coding-agent-loop/
  desktop/                    # New: Electron app
    package.json              # electron, electron-builder, main script
    main.js                   # Main process: spawn servers, health check, window, cleanup
    preload.js                # Optional: expose API base URL to renderer
    resources/                # Dev: place Go binaries here for local run
  agent_go/
    cmd/server/               # Agent server (build → agent-server for Mac)
    static/                   # Built frontend (Vite build output)
  workspace/                  # Workspace server (build → workspace-server for Mac)
  frontend/                   # Build with VITE_API_BASE_URL etc. for Electron

Packaged app (simplified):

MyApp.app/
  Contents/
    MacOS/Electron
    Resources/
      app.asar (or unpacked)   # Electron app code
      agent-server            # Go binary
      workspace-server        # Go binary

• Docker: Run agent and workspace via docker compose from the Electron app. Possible, but requires users to have Docker installed; not chosen for “download and run” simplicity.
• Hosted backend: No local servers; app talks to cloud API. Not in scope for this plan; would be a different product.
• Windows / Linux: Out of scope for this plan; can be added later using the same pattern (build Go for each OS, electron-builder targets).

• User downloads a single Mac artifact (e.g. .dmg) from a release page.
• User opens the app; agent and workspace start automatically; window shows the existing UI.
• No browser, Docker, or manual server startup required.
• User quits the app; both servers stop; no lingering processes.
• (With signing/notarization) App opens without Gatekeeper blocking it.

• Current browser-based setup: Go server serves frontend from ./static/; frontend uses VITE_API_BASE_URL and VITE_WORKSPACE_API_URL (see frontend/src/services/api.ts).
• Workspace server: workspace/, typically port 8081; docker-compose in repo root.
• Agent server: agent_go/cmd/server/server.go; static files from ./static/.