[P3][Phase 3][Platform] Desktop Agents — Windows, macOS, Linux

[krishsutariya1742]

Overview

Deliver installable desktop agents for Windows, macOS, and Linux that connect to EngineX and execute local tasks — file access, desktop applications, VPN-only systems — without CLI setup for end users.

This is an edge/local automation capability, not the primary product interface. Most users operate through the web dashboard on a server (or client self-hosted EngineX in their VPC). Implement when a client requires on-machine access.

Priority: P3 — lowest on the board. No active work until a design partner requires local file or VPN automation.

---

Ticket metadata

Field	Value
Phase	Phase 3 — Expansion / backlog
Priority	P3 — Parked
Type	Platform (desktop client)
Depends on	#4 Multi-tenant for secure registration (or interim single-tenant token for pilots)

---

Existing run modes

Mode	Status	Audience	Environment
Web dashboard	Built	Approvers, operators	Browser → ./engine serve
CLI	Built	Engineers	./engine run, validate, setup-credentials
TUI	Built	Power users	./engine run --tui
Headless daemon	Built	Operations	./engine run --daemon
Desktop installer (#5)	Not built	Employees with local data	Installed application

Dashboard includes (PR #12): Ops console (/ops), checkpoint resume, HITL evidence panel, OAuth Connect (HubSpot/Zoho/Google Calendar).

Default GTM path today: client installs EngineX OSS in their VPC (headless and/or dashboard) — not desktop connector.

---

When to build vs defer

Build when

• Data resides only on the user's machine (local files, Downloads)
• Target systems are VPN/local-only and unreachable from cloud
• Air-gapped or high-security deployment
• IT requires managed rollout (MSI/pkg/deb) at scale

Defer — use server + web instead

• #2 Hourly Tracking (server-side timer agent)
• log_monitor and similar server-side agents
• SAP/ERP/API integrations reachable from server
• Human approval via browser (pause_nodes)

---

Personas

Persona	Role
Knowledge worker	Local tasks execute automatically; approvals in browser
IT admin	Fleet deployment; registration token management
Platform team	Registration provisioning; agent health monitoring

---

Phased delivery

MVP — Thin desktop connector

• Install → register with EngineX backend → maintain connection
• Secure registration (one-time token or OAuth device flow)
• Background service (Windows Service / macOS LaunchAgent / systemd)
• Backend dispatches local tool call → desktop executes → returns result
• Status UI: connection state, logs

Phase 2 — Distribution

• Windows MSI, macOS .pkg (notarized), Linux .deb/.rpm
• Auto-update with signed releases
• Enterprise silent install support

Phase 3 — Extended runtime

• Full agent graphs offline; sync on reconnect
• Local credential vault per tenant policy

---

Non-goals

• Replacing web dashboard for approvals and workflow visibility
• Default go-to-market path (server + browser first)
• Offline agent authoring or marketplace in v1

---

System architecture

Cloud ↔ desktop ↔ local execution

Desktop agents register to a tenant backend (#4) and execute only delegated local work:

sequenceDiagram
 participant IT as IT admin
 participant Cloud as EngineX backend
 participant Desk as Desktop connector
 participant Local as Local files / VPN tools
 participant Web as Web dashboard

 IT->>Desk: Install + registration token
 Desk->>Cloud: Register (tenant-scoped)
 Cloud->>Web: Agent online — visible in session

 Cloud->>Desk: Dispatch local tool job
 Desk->>Local: Scoped read / write / command
 Local->>Desk: Result or error
 Desk->>Cloud: Return payload
 Cloud->>Web: Update session — operator sees outcome

Loading

Placement in product stack

flowchart LR
 subgraph primary [Primary path — most users today]
 VPC[Client VPC self-hosted EngineX]
 WEB[Web dashboard]
 SRV[Server-side agents]
 WEB --> SRV
 VPC --- WEB
 end

 subgraph edge [Edge path — when cloud cannot reach data]
 DESK[Desktop connector]
 LOC[Employee machine]
 DESK --> LOC
 end

 SRV --> BACK[(EngineX runtime)]
 DESK --> BACK

Loading

Reference diagram

---

Definition of done (MVP)

• Installs on Windows, macOS, Linux
• Securely registers to EngineX backend
• Backend dispatches local tool; result visible in dashboard session
• Persists as background service across reboot
• Installation and troubleshooting documentation
• E2E test: register → dispatch → result in session
• Security review (token handling, command sandbox)

---

Open questions

1. Thin connector vs full local AgentRunner for MVP?
2. Protocol: extend SSE/API or new WebSocket/gRPC?
3. Local tool allowlist: tenant admin vs per-machine policy?
4. Code signing and notarization ownership?

[pravinmishra672]

Description

Provide installable desktop agents for Windows, macOS, and Linux that connect to EngineX (hosted or on-prem) and can run local tasks — file access, desktop apps, VPN-only systems — without manual CLI setup for end users.

This is for edge/local automation, not the primary day-to-day user experience.

---

How this differs from what exists today

EngineX already has three run modes — #5 is a fourth, packaged for non-developers:

Mode	Status	Who	Where
Web dashboard	✅ Built	Approvers, operators	Browser → ./engine serve
CLI	✅ Built	Engineers	Terminal — ./engine run, validate
TUI	✅ Built	Power users	Terminal — ./engine run --tui
Headless daemon	✅ Built	Ops/automation	Server — ./engine run --daemon
Desktop installer (#5)	❌ Not built	Employees with local data	Installed app / background service

Most users should still use the web dashboard. Desktop agents are for cases where work must happen on the user's machine (local Excel, internal file shares, air-gapped tools).

Relationship to #4 Multi-Tenant: Desktop agents are clients that register to a tenant's EngineX backend. #4 provides the hosted control plane; #5 provides local execution where the cloud cannot reach.

---

When we need this vs when we don't

Need desktop (#5)

• Agent must read/write files only on employee laptop (C: drive, Downloads)
• Customer system is VPN/local-only; cloud cannot connect directly
• Air-gapped or high-security environment
• "Double-click to install" rollout to 500 non-technical users

Don't need desktop — use server + web instead

• Hourly tracking / finance reconciliation (#2)
• Log monitoring, Slack alerts (log_monitor template)
• SAP/ERP/API integrations reachable from server
• Human review via browser (HITL / pause_nodes)

---

Target personas

Persona	Example
Knowledge worker	Runs local document prep agent; approves in browser
IT admin	Rolls out MSI/pkg/deb to fleet; manages registration tokens
Platform team (us)	Issues tenant registration URL; monitors connected agents

---

Phased delivery (recommended)

Phase 1 — Thin desktop connector (MVP)

Goal: Installable app registers with EngineX backend and executes delegated tool calls locally.

• Design installation workflow (download → register → connect)
• Secure registration: one-time token or OAuth device flow tied to tenant ([P2][Phase 2][Platform] Multi-Tenant Architecture — phased SaaS isolation #4)
• Local background service (Windows Service / macOS LaunchAgent / systemd)
• Bi-directional channel: backend dispatches work → desktop runs tools → returns results
• Minimal local UI: status, logs, "connected / disconnected"
• Document supported local capabilities (file read, shell commands — scope TBD)

Phase 2 — Installers + auto-update

• Windows installer (MSI or WiX)
• macOS package (.pkg) + notarization
• Linux .deb / .rpm
• Auto-update mechanism (signed releases)
• Enterprise silent install flags

Phase 3 — Rich local runtime (optional)

• Run full agent graphs locally when offline
• Sync results when reconnected
• Local credential vault synced with tenant policy

---

Action items (full backlog)

• Design agent installation workflow
• Define desktop ↔ server protocol (extend existing SSE/WebSocket or new RPC)
• Implement secure agent registration process (per-tenant tokens)
• Create Windows installer package
• Create macOS installer package
• Create Linux installation package
• Add auto-update mechanism
• Support background service execution
• Local tool sandbox / permission prompts (which folders, which commands)
• Add installation and troubleshooting documentation
• Test installation across supported platforms
• Cross-platform CI for build artifacts

---

Code / architecture starting points

Today (server-side):
  core/engine/server/       # HTTP API — will receive desktop registrations
  core/engine/runner/       # AgentRunner — reference for what runs locally vs remote
  tools/                    # MCP tools — pattern for local tool execution

New (desktop — TBD location):
  desktop/ or agents/desktop/
  - connector daemon
  - platform installers
  - local tool executor (files, shell — scoped)

Open design choice: Full local AgentRunner vs thin connector that only runs approved local tools dispatched from cloud.

---

Non-goals (explicit)

• Not replacing web dashboard for approvals and workflow visibility
• Not the default GTM path — server + browser first
• Not in Phase 1: full offline agent authoring, local agent marketplace
• Conflicts with pure SaaS pitch if over-emphasized — position as enterprise add-on

Priority: platform · Milestone: Phase 3 / when design partner requires local file access
Depends on: #4 for secure tenant registration (or interim single-tenant registration for pilots)

---

System Architecture

---

Definition of done (Phase 1)

• Agent installs on Windows, macOS, and Linux (manual pkg acceptable before polished installers)
• Installed agent securely registers to an EngineX backend (tenant-scoped)
• Backend can dispatch at least one local tool call; desktop returns result
• Agent runs as background service; survives reboot (platform-dependent)
• Installation + troubleshooting docs published
• E2E test: register → dispatch → result → visible in web dashboard session
• Security review: token handling, local command sandbox, update signing (Phase 2 for updates)

---

Open questions (resolve in design doc)

1. Thin connector vs full local runtime — which for MVP?
2. Protocol: extend current SSE/API or new WebSocket/gRPC channel?
3. Local tool allowlist: who configures — tenant admin or per-machine policy?
4. Code signing / notarization budget and release pipeline ownership?

[pravinmishra672]

Ticket metadata

Field	Value
Phase	Phase 3 — Expansion / backlog
Priority	P3 — Low / enterprise add-on
Type	Platform (desktop client)
Target	Local file/VPN automation on employee laptops
Depends on	#4 (tenant registration) or interim single-tenant token
Blocks	—

Suggested labels (admin): phase-3, priority-p3, type-platform

Why P3: Most users use web dashboard + server-side agents. Build only when a design partner requires local machine access.

See scoped comment above for thin-connector vs full runtime design.

[mishrapravin114]

Kept open — lowest priority on the board.

Build only when a design partner requires local file/VPN access on employee machines. Default path remains web dashboard + server-side agents (#4 multi-tenant for hosted SaaS).

No work planned until Phase 3 and explicit customer demand.

[mishrapravin114]

Status update (2026-06-14)

Run-mode table in this issue body: accurate — four built server modes (web dashboard, CLI, TUI, headless daemon) + desktop connector (not built).

Server-side additions (PR #12): Ops console (/ops), checkpoint resume API + picker, OAuth credential connect.

Still not built: desktop connector (Windows/macOS/Linux installer) — Phase 3 / P3.

Client deployment: docs/CLIENT_DEPLOYMENT_GUIDE.md on main (includes Engine Cloud §2A, client VPC models, diagrams).

Note: Older scoped comment below said "three run modes" — correct count is four server modes; #5 desktop is the fifth packaged mode for end users.